配置 guest 代理

本文档介绍了如何管理客机代理服务，以及如何通过修改其配置文件来配置其功能。

客户代理是客户环境的关键组件。访客环境包含实例在 Compute Engine 上运行时所需的脚本、守护程序和二进制文件。如需详细了解客机环境，请参阅客机环境。 虽然客户机代理默认情况下可使用Google 提供的操作系统映像和默认设置，但您可能需要自定义其行为。如需详细了解客机代理的核心功能，请参阅客机代理功能。

重启客机代理

客户机代理在 Linux 和 Windows 操作系统上均以守护进程的形式运行。在 Linux 上，来宾代理以 systemd 服务的形式启动；在 Windows 上，它是一个系统服务。

Linux 和 Windows 操作系统之间的重启步骤有所不同，如下所示：

Linux

如需在 Linux 上重启，请选择以下选项之一：

  • 对于客户机代理版本 20250901.00 或更高版本，请运行以下命令：

    ggactl_plugin coreplugin restart

  • 对于之前的 guest 代理版本，请运行以下命令：

    systemctl restart google-guest-agent

Windows

如需在 Windows 上重新启动，请选择以下选项之一：

  • 对于客户机代理版本 20250901.00 或更高版本，请运行以下命令：

    ggactl_plugin coreplugin restart

  • 对于之前的客户机代理版本，请使用以下 PowerShell 命令：

    1. 如需停止客机代理，请执行以下操作： 

      Stop-Service GCEAgent

    2. 如需启动客机代理，请执行以下操作： 

      Start-Service GCEAgent

    或者，如需重启客机代理，请执行以下操作： 

    Restart-Service GCEAgent

对于所有 Guest 代理版本，您还可以使用任务管理器：找到 GCEGuestAgent 服务，然后重启该服务。

更新 guest 代理配置文件

您可以通过修改客机代理的配置文件 instance_configs.cfg 来自定义其行为。您可以通过此文件启用或停用功能，并为操作设置默认值。

如需在 Linux 和 Windows 操作系统上修改 instance_configs.cfg 文件，请参阅以下各部分。

Linux

如需在 Linux 虚拟机上修改配置文件，请执行以下操作：

  1. 创建或修改位于 /etc/default/instance_configs.cfg 的配置文件，并设置所需的选项。如需查看选项列表，请参阅配置选项。

    例如，如需自定义新用户的创建方式并指定要生成的 SSH 主机密钥类型，请创建或更新包含以下内容的文件：

    [Accounts]
useradd_cmd = useradd -m -G google-sudoers
[InstanceSetup]
host_key_types = ecdsa,ed25519

    注意：Linux 发行版可能会在 /etc/default/instance_configs.cfg.distro 中提供自己的默认设置。代理会先读取这些设置，但您在 /etc/default/instance_configs.cfg 中定义的任何设置都会替换分发默认值。这样可确保在软件包更新期间不会丢失自定义配置。

  2. 修改配置文件后，重启客机代理以使更改生效。

Windows

在 Windows 虚拟机上，配置文件位于 C:\Program Files\Google\Compute Engine\instance_configs.cfg。如需详细了解如何在 Windows 上配置代理，请参阅启用和停用 Windows 实例功能。

配置选项

下表列出了 instance_configs.cfg 文件的可用配置选项。

账号

使用 instance_configs.cfg 文件的 Accounts 部分中的选项来控制访客代理的用户和群组管理。

选项 说明 操作系统 默认值
deprovision_remove 如果设置为 true，则在移除用户账号时，也会删除该用户的主目录。默认情况下，系统只会移除用户账号，而目录会保持不变。 Linux false
groups 新用户的群组列表（以英文逗号分隔）。 Linux 空
useradd_cmd 设置访客代理在创建新用户时运行的命令。例如，如需创建用户的主目录并将用户添加到 google-sudoers 群组，请将值设置为 useradd -m -G google-sudoers。 Linux 系统默认
userdel_cmd 设置在删除用户时由 guest 代理运行的命令。 例如，如需移除用户的主目录和文件，请将该值设置为 userdel -r。 Linux 系统默认
usermod_cmd 设置在修改用户群组时由 Guest 代理运行的命令。 Linux 系统默认
gpasswd_add_cmd 设置在将用户添加到群组时访客代理运行的命令。 Linux 系统默认
gpasswd_remove_cmd 设置在从群组中移除用户时，访客代理运行的命令。 Linux 系统默认
groupadd_cmd 设置客机代理在创建新组时运行的命令。 Linux 系统默认

核心

使用 instance_configs.cfg 文件 Core 部分中的选项来控制 Guest 代理的核心功能。

选项 说明 操作系统 默认值
cloud_logging_enabled 如果设置为 false，则 Guest 代理不会将活动日志发送到 Cloud Logging。 Linux 和 Windows true
log_level 设置访客代理日志的日志记录级别。此设置适用于访客代理生成的所有日志，而不仅仅是 Cloud Logging。设置和级别如下：
  • 0 (FATAL)：记录导致代理停止的严重错误。
  • 1 (ERROR)：记录可能会阻止代理运行的错误。
  • 2 (WARN)：记录可能有害的情况。
  • 3 (INFO)：记录有关代理活动的参考消息。这是默认设置。
  • 4 (DEBUG)：记录调试信息。此信息可能非常详细，但您可以使用 log_verbosity 选项来降低详细程度。
 Linux 和 Windows 3
log_verbosity 为 DEBUG 日志设置日志记录详细程度级别。 可接受的值介于 0 到 4 之间。 值越高，回答就越详细。 Linux 和 Windows 0

守护程序

使用 instance_configs.cfg 文件的 Daemons 部分中的选项，可启用或停用由访客代理管理的特定后台守护程序。

选项 说明 操作系统 默认值
accounts_daemon 如果设置为 false，客机代理会停用用户账号和 SSH 密钥管理。 Linux true
clock_skew_daemon 如果设置为 false，客机代理会停用时钟同步。 Linux true
network_daemon 如果设置为 false，客机代理会停用网络管理。 Linux true

实例设置

使用 instance_configs.cfg 文件的 InstanceSetup 部分中的选项，可以控制在初始实例设置期间由 Guest 代理执行的各种任务。

选项 说明 操作系统 默认值
host_key_types 要生成的主机密钥类型的英文逗号分隔列表。 Linux ecdsa,ed25519,rsa
optimize_local_ssd 如果设置为 false，则客机在启动时不会优化本地 SSD。 Linux true
network_enabled 如果设置为 false，访客代理会跳过需要元数据信息的实例设置函数。将此选项设置为 false 还会停用主机密钥生成，并防止客机代理配置 boto 配置文件。 Linux 和 Windows true
set_boto_config 如果设置为 false，客机代理不会创建或更新 boto 配置文件。使用 Boto 库并依赖默认访客代理配置来访问 Cloud Storage 的应用可能无法正常运行，除非手动进行 boto 配置。 Linux 和 Windows true
set_host_keys 如果设置为 false，则 guest 代理会在首次启动时跳过生成主机密钥的步骤。 Linux true
set_multiqueue 如果设置为 false，则 guest 代理不会尝试通过为网络驱动程序启用多队列功能来优化网络性能。如果值为 true，代理会配置系统以使用多个队列来处理网络流量，从而可能提高吞吐量并缩短延迟时间。 Linux true

IP 转发

使用 instance_configs.cfg 文件 IpForwarding 部分中的选项来配置客户机代理管理 IP 转发和路由的方式。

选项 说明 操作系统 默认值
ethernet_proto_id 守护程序添加的路由的协议 ID 字符串。 Linux 66
ip_aliases 如果设置为 false，则客机代理不会设置别名 IP 路由。 Linux true
target_instance_ips 如果设置为 false，客机代理不会启用内部 IP 地址负载平衡。 Linux true

元数据脚本执行

使用 instance_configs.cfg 文件 MetadataScripts 部分中的选项来控制元数据脚本（例如启动和关闭脚本）的执行。

选项 说明 操作系统 默认值
default_shell 用于执行脚本的默认 shell。 Linux /bin/bash
run_dir 元数据脚本执行的基本目录。 Linux /var/run/google-startup-scripts
startup 如果设置为 false，客机代理将不会运行元数据中的启动脚本。 Linux 和 Windows true
shutdown 如果设置为 false，客机代理不会运行来自元数据的关停脚本。 Linux 和 Windows true

网络接口

使用 instance_configs.cfg 文件 NetworkInterfaces 部分中的选项来控制客户机代理如何管理虚拟机上的网络接口。

选项 说明 操作系统 默认值
setup 如果设置为 false，客机代理会跳过网络接口设置。 Linux true
ip_forwarding 如果设置为 false，则客机代理会跳过 IP 转发。 Linux true
manage_primary_nic 如果设置为 true，则由 Guest 代理管理主网卡和辅助网卡。 Linux false
dhcp_command 用于启用网络接口的备用 DHCP 可执行文件的路径。 Linux 空
restore_debian12_netplan_config 如果设置为 true，则客户机代理会重新创建位于 /etc/netplan/90-default.yaml 的 Debian 12 默认 netplan 配置。 Linux (Debian 12) true

OS Login

使用 instance_configs.cfg 文件的 OSLogin 部分中的选项来配置客户机代理与 OS Login 的集成。

选项 说明 操作系统 默认值
cert_authentication 如果设置为 false，则 guest 代理不会配置 sshd 的 TrustedUserCAKeys、AuthorizedPrincipalsCommand 和 AuthorizedPrincipalsCommandUser 密钥。 Linux true

后续步骤