Configure the guest agent

Linux Windows

This document describes how to manage the guest agent service and configure its features by editing its configuration file.

The guest agent is a critical component of the guest environment. The guest environment contains scripts, daemons, and binaries that instances need to run on Compute Engine. For more information about the guest environment, see Guest environment. While the guest agent works by default with default settings on Google-provided OS images, you might want to customize its behavior. For more information about guest agent core functions, see Guest agent functionality.

Restart the guest agent

The guest agent runs as a daemon on both Linux and Windows operating systems. On Linux, the guest agent launches as a systemd service, and on Windows, it is a system service.

The restart steps vary between Linux and Windows operating systems as follows:

Linux

To restart on Linux, choose one of the following options:

For guest agent version 20250901.00 or later, run the following command:
```
ggactl_plugin coreplugin restart
```
For previous guest agent versions, run the following command:
```
systemctl restart google-guest-agent
```

Windows

To restart on Windows, choose one of the following options:

For guest agent version 20250901.00 or later, run the following command:
```
ggactl_plugin coreplugin restart
```
For previous guest agent versions, use the following PowerShell commands:
1. To stop the guest agent:
```
Stop-Service GCEAgent
```
2. To start the guest agent:
```
Start-Service GCEAgent
```
Alternatively, to restart the guest agent:
```
Restart-Service GCEAgent
```

For all guest agent versions, you can also use the Task Manager: find the GCEGuestAgent service, and then restart it.

Update the guest agent configuration file

You can customize the guest agent's behavior by editing its configuration file, instance_configs.cfg. This file lets you enable or disable features and set default values for operations.

To edit the instance_configs.cfg file on Linux and Windows operating systems, review the following sections.

Linux

To edit the configuration file on a Linux VM, do the following:

Create or edit the configuration file located at /etc/default/instance_configs.cfg and set the required option. For a list of options, see Configuration options.

For example, to customize how new users are created and specify which SSH host key types to generate, create or update the file with the following content:
```
[Accounts]
useradd_cmd = useradd -m -G google-sudoers
[InstanceSetup]
host_key_types = ecdsa,ed25519
```
Note: Linux distributions might provide their own default settings in /etc/default/instance_configs.cfg.distro. The agent reads these settings first, but any settings you define in /etc/default/instance_configs.cfg override the distribution defaults. This ensures that your custom configurations are not lost during package updates.
After you modify the configuration file, restart the guest agent for the changes to take effect.

Windows

On Windows VMs, the configuration file is located at C:\Program Files\Google\Compute Engine\instance_configs.cfg. For details about configuring the agent on Windows, see Enabling and disabling Windows instance features.

Configuration options

The following tables list the available configuration options for the instance_configs.cfg file.

Accounts

Use the options in the Accounts section of the instance_configs.cfg file to control user and group management by the guest agent.

Option	Description	Operating system	Default value
`deprovision_remove`	If set to `true`, when a user account is removed, the user's home directory is also deleted. By default, only the user account is removed, and the directory remains intact.	Linux	`false`
`groups`	A comma-separated list of groups for new users.	Linux	Empty
`useradd_cmd`	Sets the command that the guest agent runs when creating a new user. For example, to create a user's home directory and add them to the `google-sudoers` group, set the value to `useradd -m -G google-sudoers`.	Linux	System default
`userdel_cmd`	Sets the command that the guest agent runs when deleting a user. For example, to remove the user's home directory and files, set the value to `userdel -r`.	Linux	System default
`usermod_cmd`	Sets the command that the guest agent runs when modifying a user's groups.	Linux	System default
`gpasswd_add_cmd`	Sets the command that the guest agent runs when adding a user to a group.	Linux	System default
`gpasswd_remove_cmd`	Sets the command that the guest agent runs when removing a user from a group.	Linux	System default
`groupadd_cmd`	Sets the command that the guest agent runs when creating a new group.	Linux	System default

Core

Use the options in the Core section of the instance_configs.cfg file to control core functionalities of the guest agent.

Option	Description	Operating system	Default value
`cloud_logging_enabled`	If set to `false`, the guest agent doesn't send activity logs to Cloud Logging.	Linux and Windows	`true`
`log_level`	Sets the logging level for guest agent logs. This setting applies to all logs generated by the guest agent, not just Cloud Logging. The settings and levels are as follows: `0 (FATAL)`: logs critical errors causing the agent to stop. `1 (ERROR)`: logs errors that might prevent the agent from running. `2 (WARN)`: logs potentially harmful conditions. `3 (INFO)`: logs informational messages about agent activity. This is the default setting. `4 (DEBUG)`: logs debugging information. This information can be verbose, but you can reduce the level of verbosity by using the `log_verbosity` option.	Linux and Windows	`3`
`log_verbosity`	Sets the logging verbosity level for `DEBUG` logs. Acceptable values are from `0` to `4`. The higher the value the more verbose the response.	Linux and Windows	`0`

Daemons

Use the options in the Daemons section of the instance_configs.cfg file to enable or disable specific background daemons managed by the guest agent.

Option	Description	Operating system	Default value
`accounts_daemon`	If set to `false`, the guest agent disables User account and SSH key management.	Linux	`true`
`clock_skew_daemon`	If set to `false`, the guest agent disables Clock synchronization.	Linux	`true`
`network_daemon`	If set to `false`, the guest agent disables Network management.	Linux	`true`

Instance setup

Use the options in the InstanceSetup section of the instance_configs.cfg file to control various tasks performed by the guest agent during the initial instance setup.

Option	Description	Operating system	Default value
`host_key_types`	A comma-separated list of host key types to generate.	Linux	`ecdsa,ed25519,rsa`
`optimize_local_ssd`	If set to `false`, the guest doesn't optimize Local SSD on startup.	Linux	`true`
`network_enabled`	If set to `false`, the guest agent skips instance setup functions that require metadata information. Setting this option to false also disables host key generation and prevents the guest agent from configuring the `boto` config file.	Linux and Windows	`true`
`set_boto_config`	If set to `false`, the guest agent doesn't create or update the `boto` configuration file. Applications that use the Boto library and rely on the default guest agent configuration for Cloud Storage access might not function as expected without manual `boto` configuration.	Linux and Windows	`true`
`set_host_keys`	If set to `false`, the guest agent skips generating host keys on firstboot.	Linux	`true`
`set_multiqueue`	If set to `false`, the guest agent doesn't attempt to optimize network performance by enabling multiqueue features for the network drivers. When `true`, the agent configures the system to use multiple queues for network traffic, potentially improving throughput and reducing latency.	Linux	`true`

IP forwarding

Use the options in the IpForwarding section of the instance_configs.cfg file to configure how the guest agent manages IP forwarding and routing.

Option	Description	Operating system	Default value
`ethernet_proto_id`	The protocol ID string for daemon-added routes.	Linux	`66`
`ip_aliases`	If set to `false`, the guest agent doesn't set up alias IP routes.	Linux	`true`
`target_instance_ips`	If set to `false`, the guest agent doesn't enable internal IP address load balancing.	Linux	`true`

Metadata script execution

Use the options in the MetadataScripts section of the instance_configs.cfg file to control the execution of metadata scripts, such as startup and shutdown scripts.

Option	Description	Operating system	Default value
`default_shell`	The default shell to execute scripts.	Linux	`/bin/bash`
`run_dir`	The base directory for metadata script execution.	Linux	`/var/run/google-startup-scripts`
`startup`	If set to `false`, the guest agent doesn't run startup scripts from metadata.	Linux and Windows	`true`
`shutdown`	If set to `false`, the guest agent doesn't run shutdown scripts from metadata.	Linux and Windows	`true`

Network interfaces

Use the options in the NetworkInterfaces section of the instance_configs.cfg file to control how the guest agent manages network interfaces on the VM.

Option	Description	Operating system	Default value
`setup`	If set to `false`, the guest agent skips network interface setup.	Linux	`true`
`ip_forwarding`	If set to `false`, the guest agent skips IP forwarding.	Linux	`true`
`manage_primary_nic`	If set to `true`, the guest agent manages the primary and secondary NICs.	Linux	`false`
`dhcp_command`	The path to an alternate DHCP executable for enabling network interfaces.	Linux	Empty
`restore_debian12_netplan_config`	If set to `true`, the guest agent recreates the Debian 12 default netplan configuration that is located at `/etc/netplan/90-default.yaml`.	Linux (Debian 12)	`true`

OS Login

Use the options in the OSLogin section of the instance_configs.cfg file to configure the guest agent's integration with OS Login.

Option	Description	Operating system	Default value
`cert_authentication`	If set to `false`, the guest agent doesn't configure sshd's `TrustedUserCAKeys`, `AuthorizedPrincipalsCommand`, and `AuthorizedPrincipalsCommandUser` keys.	Linux	`true`

What's next

View the serial port output to check the guest agent logs and troubleshoot issues.

Configure the guest agent Stay organized with collections Save and categorize content based on your preferences.

Restart the guest agent

Linux

Windows

Update the guest agent configuration file

Linux

Windows

Configuration options

Accounts

Core

Daemons

Instance setup

IP forwarding

Metadata script execution

Network interfaces

OS Login

What's next

Configure the guest agent