設定訪客代理程式

本文說明如何管理客體代理程式服務，以及如何透過編輯設定檔來設定其功能。

訪客代理程式是訪客環境的重要元件。訪客環境包含執行個體在 Compute Engine 上執行時所需的指令碼、Daemon 和二進位檔。如要進一步瞭解訪客環境，請參閱訪客環境一文。訪客代理程式預設會搭配Google 提供的作業系統映像檔使用預設設定，但您可能想自訂其行為。如要進一步瞭解訪客代理程式的核心功能，請參閱訪客代理程式功能。

重新啟動訪客代理程式

訪客代理程式會在 Linux 和 Windows 作業系統上以精靈形式執行。在 Linux 上，客體代理程式會以 systemd 服務的形式啟動，在 Windows 上則是以系統服務的形式啟動。

Linux 和 Windows 作業系統的重新啟動步驟有所不同，如下所示：

Linux

如要在 Linux 上重新啟動，請選擇下列其中一個選項：

  • 如為客體代理程式 20250901.00 以上版本，請執行下列指令：

    ggactl_plugin coreplugin restart

  • 如為舊版客體代理程式，請執行下列指令：

    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

對於所有訪客代理程式版本，您也可以使用工作管理員：找出 GCEGuestAgent 服務，然後重新啟動。

更新客體代理程式設定檔

如要自訂客體代理程式的行為，請編輯其設定檔 instance_configs.cfg。您可以在這個檔案中啟用或停用功能，以及設定作業的預設值。

如要在 Linux 和 Windows 作業系統上編輯 instance_configs.cfg 檔案，請參閱下列章節。

Linux

如要在 Linux VM 上編輯設定檔，請按照下列步驟操作：

  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 VM 中，設定檔位於 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 設定刪除使用者時，訪客代理程式執行的指令。 舉例來說，如要移除使用者的主目錄和檔案，請將值設為 userdel -r。 Linux 系統預設
usermod_cmd 設定訪客代理程式在修改使用者群組時執行的指令。 Linux 系統預設
gpasswd_add_cmd 設定訪客代理程式在將使用者加入群組時執行的指令。 Linux 系統預設
gpasswd_remove_cmd 設定訪客代理程式在從群組移除使用者時執行的指令。 Linux 系統預設
groupadd_cmd 設定訪客代理程式在建立新群組時執行的指令。 Linux 系統預設

核心

使用 instance_configs.cfg 檔案 Core 區段中的選項，控管訪客代理程式的核心功能。

選項 說明 作業系統 預設值
cloud_logging_enabled 如果設為 false，訪客代理程式就不會將活動記錄傳送至 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

Daemon

使用 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 區段中的選項，控管訪客代理程式在初始執行個體設定期間執行的各項工作。

選項 說明 作業系統 預設值
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，訪客代理程式會在初次啟動時略過產生主機金鑰的步驟。 Linux true
set_multiqueue 如果設為 false，訪客代理程式不會嘗試為網路驅動程式啟用多佇列功能，藉此最佳化網路效能。如果設為 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 執行指令碼的預設殼層。 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 區段中的選項，控管訪客代理程式管理 VM 網路介面的方式。

選項 說明 作業系統 預設值
setup 如果設為 false，訪客代理程式會略過網路介面設定。 Linux true
ip_forwarding 如果設為 false，訪客代理程式會略過 IP 轉送。 Linux true
manage_primary_nic 如果設為 true，客體代理程式會管理主要和次要 NIC。 Linux false
dhcp_command 啟用網路介面的替代 DHCP 可執行檔路徑。 Linux 空白
restore_debian12_netplan_config 如果設為 true，客層代理程式會重新建立 Debian 12 預設的 netplan 設定，該設定位於 /etc/netplan/90-default.yaml。 Linux (Debian 12) true

OS 登入

使用 instance_configs.cfg 檔案 OSLogin 區段中的選項，設定訪客代理程式與 OS Login 的整合。

選項 說明 作業系統 預設值
cert_authentication 如果設為 false，訪客代理程式不會設定 sshd 的 TrustedUserCAKeys、AuthorizedPrincipalsCommand 和 AuthorizedPrincipalsCommandUser 金鑰。 Linux true

後續步驟