使用串行控制台进行问题排查

Linux Windows

此页面介绍如何启用对实例串行控制台的交互式访问，以调试启动和网络问题、排查实例故障、与 GRand Unified Bootloader (GRUB) 交互以及执行其他问题排查任务。

虚拟机 (VM) 实例具有四个虚拟串行端口。与串行端口交互类似于使用终端窗口，因为输入和输出完全在文本模式下进行，并且没有图形界面或鼠标支持。实例的操作系统、BIOS 以及其他系统级实体通常将输出写入串行端口，并且可以接受输入，例如命令或提示的答案。这些系统级实体通常使用第一个串行端口（端口 1），该端口通常称为串行控制台。

如果您只需要查看串行端口输出，而不需要向串行控制台发出任何命令，则可以调用 getSerialPortOutput 方法或使用 Cloud Logging 读取您的实例已写入其串行端口的信息；具体请参阅查看串行端口日志。但是，如果您在通过 SSH 访问实例时遇到问题，或者需要对未完全启动的实例进行问题排查，您可以启用对串行控制台的交互式访问，从而连接到您的实例的任何串行端口并与其交互。例如，您可以通过串行端口直接运行命令并响应提示。

启用或停用串行端口时，您可以使用元数据服务器所能接受的任何布尔值。如需了解详情，请参阅布尔值。

准备工作

设置身份验证（如果尚未设置）。身份验证是通过其进行身份验证以访问 Google Cloud 服务和 API 的过程。如需从本地开发环境运行代码或示例，您可以按如下方式向 Compute Engine 进行身份验证。

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

执行此任务所需的权限

您必须拥有以下权限才能执行此任务：

针对虚拟机的 compute.instances.setMetadata 权限（如果要在特定虚拟机上启用交互式访问）
针对项目的 compute.projects.setCommonInstanceMetadata 权限（如果要为项目中的所有虚拟机启用交互式访问权限）
针对实例服务账号的 iam.serviceAccountUser 角色

启用对串行控制台的交互式访问权限

为单个虚拟机实例或整个项目启用交互式串行控制台访问。

针对项目启用访问

如果您对某个项目启用交互式串行控制台访问，则会同时对该项目下的所有虚拟机实例启用这一访问。

默认情况下，交互式串行端口访问权限处于停用状态。您也可以通过将 serial-port-enable 键设置为 FALSE 来明确停用这项访问权限。对于这两种情况，任何针对个别实例的设置都将替换项目级的设置或默认设置。

控制台

在 Google Cloud 控制台中，打开元数据页面。
转到元数据
点击修改以修改元数据条目。
添加一个键为 serial-port-enable 且值为 TRUE 的新条目。
保存更改。

gcloud

使用 Google Cloud CLI 输入 project-info add-metadata 命令，如下所示：

gcloud compute project-info add-metadata \
    --metadata serial-port-enable=TRUE

REST

在 API 中，向 projects().setCommonInstanceMetadata 方法发出请求，提供键 serial-port-enable 且值为 TRUE：

{
 "fingerprint": "FikclA7UBC0=",
 "items": [
  {
   "key": "serial-port-enable",
   "value": "TRUE"
  }
 ]
}

针对虚拟机实例启用访问权限

针对特定实例启用交互式串行控制台访问权限。基于个别实例的设置（如果存在）会替换任何项目级的设置。也就是说，即使您在项目级启用了访问权限，也可以通过将 serial-port-enable 设置为 FALSE（而非 TRUE）来针对特定实例停用访问权限。同样，即使您明确或默认针对项目停用了访问权限，也仍然可以针对一个或多个实例启用访问权限。

控制台

在 Google Cloud 控制台中，前往虚拟机实例页面。
转到“虚拟机实例”页面
点击要为其启用访问权限的实例。
点击修改。
在远程访问部分下，勾选允许连接到串行端口复选框。
保存更改。

gcloud

使用 Google Cloud CLI 输入 instances add-metadata 命令，并将 instance-name 替换为实例的名称。

gcloud compute instances add-metadata instance-name \
    --metadata serial-port-enable=TRUE

REST

在 API 中，向 instances().setMetadata 方法发出请求，提供键 serial-port-enable 且值为 TRUE：

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata
{
 "fingerprint": "zhma6O1w2l8=",
 "items": [
  {
   "key": "serial-port-enable",
   "value": "TRUE"
  }
 ]
}

为 Bare Metal 实例配置串行控制台

对于 Bare Metal 实例，请将串行控制台的比特率（也称为波特率）提高到 115,200 bps（约 11.5kB/秒）。使用较低的速度会导致控制台输出内容乱码或缺失。

引导加载程序配置因操作系统和操作系统版本而异。如需查看相关说明，请参阅操作系统发行方的文档。

如果要在命令行中为当前会话修改比特率，请使用如下所示的命令：

console=ttyS0,115200

如果要修改 GRUB 配置，请使用如下所示的命令：

serial --speed=115200

请确保更新实际的引导加载程序配置。可以使用 update-grub、grub2-mkconfig 或类似的命令来执行此操作。

连接到串行控制台

Compute Engine 为每个 Google Cloud 区域提供区域级串行控制台网关。启用对虚拟机的串行控制台的交互式访问权限后，您可以连接到区域级串行控制台。

串行控制台使用 SSH 密钥对用户进行身份验证。具体而言，您必须将 SSH 公钥添加到项目或实例元数据中，并将私钥存储在您要建立连接的来源本地机器上。gcloud CLI 和 Google Cloud 控制台会自动为您将 SSH 密钥添加到项目中。如果您使用的是第三方客户端，则可能需要手动添加 SSH 密钥。

控制台

如需连接到虚拟机的区域串行控制台，请执行以下操作：

在 Google Cloud 控制台中，前往虚拟机实例页面。
转到“虚拟机实例”页面
点击您要连接的实例。
在远程访问下，点击连接到串行控制台以在默认端口（端口 1）上进行连接。
如果您要连接到其他串行端口，请点击连接到串行控制台按钮旁边的下拉箭头，然后相应地更改端口号。
对于 Windows 实例，请打开该按钮旁边的下拉菜单，然后连接到端口 2 以访问串行控制台。

gcloud

如需连接到虚拟机的区域串行控制台，请使用 gcloud compute connect-to-serial-port 命令：

  gcloud compute connect-to-serial-port VM_NAME 

      --port=PORT_NUMBER

替换以下内容：

VM_NAME：您要连接到串行控制台的虚拟机的名称。
PORT_NUMBER：您要连接的端口号。对于 Linux 虚拟机，请使用 1；对于 Windows 虚拟机，请使用 2。如需详细了解端口号，请参阅了解串行端口编号。

注意：默认端口号为 1。

其他 SSH 客户端

只要其他第三方 SSH 客户端允许您连接到 TCP 端口 9600，您就可以使用该客户端连接到实例的串行控制台。

如需连接到虚拟机的区域级串行控制台，请根据虚拟机的操作系统运行以下命令之一：

如需连接到 Linux 虚拟机，请运行以下命令：

ssh -i PRIVATE_SSH_KEY_FILE -p 9600 PROJECT_ID.ZONE.VM_NAME.USERNAME.OPTIONS@REGION-ssh-serialport.googleapis.com

如需连接到 Windows 虚拟机，请运行以下命令：

ssh -i PRIVATE_SSH_KEY_FILE -p 9600 PROJECT_ID.ZONE.VM_NAME.USERNAME.OPTIONS.port=2@REGION-ssh-serialport.googleapis.com

替换以下内容：

PRIVATE_SSH_KEY_FILE：实例的专用 SSH 密钥。
PROJECT_ID：此虚拟机实例的项目 ID。
ZONE：虚拟机实例所在的可用区。
REGION：虚拟机实例所在的区域。
VM_NAME：虚拟机实例的名称。
USERNAME：您用于连接实例的用户名。通常是本地机器上的用户名。
OPTIONS：您可以为此连接指定的其他选项。例如，您可以指定某个串行端口并指定任何高级选项。端口号可以是 1 到 4（包括 1 和 4）。如需详细了解端口号，请参阅了解串行端口编号。如果忽略该选项，您将连接到串行端口 1。

如果您在使用第三方 SSH 客户端进行连接时遇到问题，可以使用 --dry-run 命令行选项运行 gcloud compute connect-to-serial-port 命令，以查看代表您运行的 SSH 命令。然后，您可以将选项与正在使用的命令进行比较。

设置安全连接

使用 Google Cloud CLI 之外的第三方 SSH 客户端时，您可以通过检查 Google 的串行端口服务器 SSH 密钥来确保您不会受到假冒或中间人攻击。要设置系统以检查服务器 SSH 密钥，请完成以下步骤：

下载您将使用的串行控制台的服务器 SSH 密钥：
- 对于区域连接，您可以在 https://www.gstatic.com/vm_serial_port/region/region.pub 中找到区域的服务器 SSH 密钥
- 对于全球连接，请下载 Google 的串行端口服务器 SSH 密钥
打开您的已知 Hosts 文件，该文件通常位于 ~/.ssh/known_hosts。
添加服务器 SSH 密钥的内容，并在此密钥前面附加服务器的主机名。例如，如果 us-central1 服务器密钥包含 ssh-rsa AAAAB3NzaC1yc... 一行内容，那么 ~/.ssh/known_hosts 应有一行类似以下的内容：
```
[us-central1-ssh-serialport.googleapis.com]:9600 ssh-rsa AAAAB3NzaC1yc...
```

出于安全考虑，Google 有时可能会更改 Google 串行端口服务器 SSH 密钥。如果您的客户端无法验证服务器密钥，请立即中止连接尝试，并按照上述步骤下载新的 Google 串行端口服务器 SSH 密钥。

在更新主机密钥后，如果您还是在客户端收到主机身份验证错误，请停止尝试连接到串行端口并与 Google 支持团队联系。请勿使用未通过主机身份验证的连接提供任何凭据。

与串行控制台断开连接

如需断开与串行控制台的连接，请执行以下操作：

按 ENTER 键。
输入 ~.（即依次输入波浪号和英文句点）。

输入 ~? 或查看 SSH 的手册页，您可以发现其他命令：

man ssh

请勿尝试使用以下任何方法断开连接：

CTRL+ALT+DELETE 组合键或其他类似组合键。因为串行控制台无法识别 PC 键盘组合，所以组合键不起作用。
exit 或 logout 命令。因为客机无法感知任何网络或调制解调器连接，所以此方法也不起作用。使用此命令只会使控制台关闭然后再重新打开，而您的会话仍然保持连接。如果您要为会话启用 exit 和 logout 命令，设置 on-dtr-low 选项即可。

使用登录提示连接到串行控制台

如果您尝试排查已完全启动的虚拟机的问题，或者尝试排查虚拟机启动已进入单用户模式后发生的问题，系统可能会在您尝试访问串行控制台时提示您输入登录信息。

默认情况下，不会将 Google 提供的 Linux 系统映像配置为允许本地用户使用密码登录。但是，Google 提供的 Windows 映像配置为允许本地用户使用密码登录。

如果虚拟机正在运行预先配置了串行端口登录的映像，您需要在虚拟机上设置本地密码，以便在出现提示时可以登录串行控制台。您可以在连接到虚拟机或使用启动脚本后设置本地密码。

使用启动脚本设置本地密码

您可以使用启动脚本来设置本地密码，以便在创建虚拟机期间或之后连接到串行控制台。

以下说明介绍如何在创建虚拟机后设置本地密码。

在 Google Cloud 控制台中，转到虚拟机实例页面。

转到虚拟机实例
选择要添加本地密码的虚拟机。
点击修改。
Linux
1. 转到元数据 > 自动化部分。
2. 如果虚拟机已有启动脚本，请复制该脚本并粘贴到安全的位置。
3. 添加以下启动脚本：
  #!/bin/bash useradd USERNAME echo USERNAME:PASSWORD | chpasswd usermod -aG google-sudoers USERNAME
  替换以下内容：
  - USERNAME：您要添加的用户名
  - PASSWORD：用户名的密码。避免使用简单的密码，因为某些操作系统可能对密码长度和复杂度有最低要求。
Windows
1. 进入到自定义元数据部分。
2. 如果虚拟机已有启动脚本，请复制该脚本并粘贴到安全的位置。
3. 点击 Add item（添加项目）。
4. 在密钥字段中，输入 windows-startup-script-cmd。
5. 在值字段中，输入以下脚本：
  net user USERNAME PASSWORD /ADD /Y net localgroup administrators USERNAME /ADD
  替换以下内容：
  - USERNAME：您要添加的用户名
  - PASSWORD：用户名的密码
点击保存。
如需重新启动虚拟机，请点击重置。如需了解详情，请参阅重置虚拟机。
连接到串行控制台。
出现提示时输入您的登录信息。
在创建用户后从虚拟机移除启动脚本。

在虚拟机上使用 `passwd` 设置本地密码

以下说明介绍如何在虚拟机上为用户设置本地密码，以便用户可以使用指定的密码登录该虚拟机的串行控制台。

连接到虚拟机。将 instance-name 替换为您的实例名称。
```
gcloud compute ssh instance-name
```
在虚拟机上，使用以下命令创建本地密码。这样做将为您当前登录的用户设置密码。
```
sudo passwd $(whoami)
```
按照提示创建密码。
接下来，退出该实例并连接到串行控制台。
出现提示时输入您的登录信息。

在其他串行端口上设置登录

默认情况下，大多数 Linux 操作系统会在端口 1 上启用登录提示。但是，端口 1 通常会因日志记录数据以及输出到该端口的其他信息而不堪重负。您也可以选择在其他端口（例如端口 2 (ttyS1)）上启用登录提示，方法是在您的虚拟机上执行下列命令之一。您可以在了解串行端口编号中查看虚拟机的可用端口列表。

下表列出了预配置有串行控制台登录和默认端口的映像。

操作系统	默认情况下具有登录提示的端口	服务管理
CentOS 6	1	`upstart`
CentOS 7	1	`systemd`
CoreOS	1	`systemd`
COS	1	`systemd`
Debian 8	1	`systemd`
Debian 9	1	`systemd`
OpenSUSE 13	1	`systemd`
OpenSUSE Leap	1	`systemd`
RHEL 6	1	`upstart`
RHEL 7	1	`systemd`
SLES 11	1	`sysvinit`
SLES 12	1	`systemd`
Ubuntu 14.04	1	`upstart`
Ubuntu 16.04	1	`systemd`
Ubuntu 17.04	1	`systemd`
Ubuntu 17.10	1	`systemd`
Windows	COM2	不适用

如需在其他串行端口上启用登录提示，请按照以下说明进行操作。

systemd

对于使用 systemd 的 Linux 操作系统：

在下次重新启动之前暂时启用该服务：
```
sudo systemctl start serial-getty@ttyS1.service
```
从下次重新启动开始永久启用该服务：
```
sudo systemctl enable serial-getty@ttyS1.service
```

upstart

对于使用 upstart 的 Linux 操作系统：

通过复制和修改现有 ttyS0.conf 文件来创建新的 /etc/init/ttyS1.conf 文件，以体现 ttyS1。例如：
- 在 Ubuntu 14.04 上执行以下命令：
```
sudo sh -c "sed -e s/ttyS0/ttyS1/g < /etc/init/ttyS0.conf > /etc/init/ttyS1.conf"
```
  注意：Ubuntu 12.04 没有 ttyS0.conf，因此 Google 建议您从 Ubuntu 14.04 复制 ttysS0.conf 文件，并在运行 Ubuntu 12.04 的实例上使用该文件。
- 在 RHEL 6.8 和 CentOS 6.8 上执行以下命令：
```
sudo sh -c "sed -ne '/^# # ttyS0/,/^# exec/p'  < /etc/init/serial.conf  | sed -e 's/ttyS0/ttyS1/g' -e 's/^# *//' > /etc/init/ttyS1.conf"
```
运行以下命令以在 ttyS1 上启动登录提示而不重启：
```
sudo start ttyS1
```

sysvinit

对于使用 sysvinit 的 Linux 操作系统，请运行以下命令：

 sudo sed -i~ -e &#39;s/^#T([01])/T\1/&#39; /etc/inittab
 sudo telinit q

了解串行端口编号

每个虚拟机实例都有四个串行端口。为了与 getSerialPortOutput API 保持一致，系统会将各个端口编号为 1 到 4。Linux 和其他类似系统会将其串行端口编号为 0 到 3。例如，在许多操作系统映像中，对应设备为 /dev/ttyS0 到 /dev/ttyS3。Windows 会将串行端口编号为 COM1 到 COM4。如需连接到在 Windows 中编号为 COM3 而在 Linux 中编号为 ttyS2 的端口，应指定端口 3。使用下表可帮助您确定要连接的端口。

虚拟机实例串行端口	标准 Linux 串行端口	Windows COM 端口
`1`	`/dev/ttyS0`	`COM1`
`2`	`/dev/ttyS1`	`COM2`
`3`	`/dev/ttyS2`	`COM3`
`4`	`/dev/ttyS3`	`COM4`

请注意，许多 Linux 映像都使用端口 1 (/dev/ttyS0) 记录来自内核和系统程序的消息。

发送串行中断

无论系统状态如何，Magic SysRq 组合键功能都可让您执行低层级任务。例如，您可以使用 Magic SysRq 组合键功能同步文件系统、重新启动实例、终止进程、卸载文件系统。

如需使用模拟串行中断发送 Magic SysRq 命令，请执行以下操作：

按 ENTER 键。
输入 ~B（即依次输入波浪号和大写的 B）。
输入 Magic SysRq 命令。

查看串行控制台审核日志

Compute Engine 提供审核日志以跟踪与实例的串行控制台连接和断开连接的用户。要查看日志，您需要具有日志查看器的权限，或者具有项目查看者或编辑者身份。

在 Google Cloud 控制台中，转到 Logs Explorer 页面。
转到 Logs Explorer
展开下拉菜单，然后选择 GCE VM 实例。
在搜索栏中，输入 ssh-serialport.googleapis.com，然后按 Enter 键。
此时会显示审核日志列表。这些日志记录了与串行控制台连接和断开连接的情况。展开任一条目即可了解详情：

对于任何审核日志，您可以执行以下操作：

展开 protoPayload 属性。
查找 methodName 以查看此日志适用的活动（连接或断开连接请求）。例如，如果此日志跟踪与串行控制台断开连接的情况，则方法名称会显示为 "google.ssh-serialport.v1.disconnect"。同样地，连接日志会显示为 "google.ssh-serialport.v1.connect"。串行控制台上的每个会话开始和结束时，系统都会记录审核日志条目。

不同的日志类型有不同的审核日志属性。例如，与连接相关的审核日志具有连接日志的特定属性，而断开连接的审核日志则具有其特定的属性集。还有一些审核日志属性同时适用于这两种日志类型。

所有串行控制台日志

下表提供了所有串行控制台日志的审核日志属性及其值：

属性	值
`requestMetadata.callerIp`	发起连接的 IP 地址和端口号。
`serviceName`	`ssh-serialport.googleapis.com`
`resourceName`	包含项目 ID、地区、实例名称和串行端口号的字符串，用于指示相关串行控制台。例如，`projects/myproject/zones/us-east1-a/instances/example-instance/SerialPort/2` 是实例 `example-instance` 的端口号 2，也称为 COM2 或 /dev/ttyS1。
`resource.labels`	标识实例 ID、地区和项目 ID 的属性。
`timestamp`	指示会话开始或结束时间的时间戳。
`severity`	`NOTICE`
`operation.id`	唯一标识会话的 ID 字符串；您可以使用该属性将“断开连接”条目与相应的“连接”条目相关联。
`operation.producer`	`ssh-serialport.googleapis.com`

连接日志

下表提供了特定于连接日志的审核日志属性及其值：

属性	值
`methodName`	`google.ssh-serialport.v1.connect`
`status.message`	`Connection succeeded.`
`request.serialConsoleOptions`	此请求中指定的任何选项，包括串行端口号。
`request.@type`	`type.googleapis.com/google.compute.SerialConsoleSessionBegin`
`request.username`	为此请求指定的用户名。该属性用于选择要匹配的公钥。
`operation.first`	`TRUE`
`status.code`	对于成功的连接请求，`status.code` 的值为 `google.rpc.Code.OK`，表示操作成功完成且没有发生任何错误。由于此属性的枚举值为 `0`，因此不会显示 `status.code` 属性。但是，检查 `status.code` 值是否为 `google.rpc.Code.OK` 的任何代码都可按预期运行。

断开连接日志

下表提供了特定于断开连接日志的审核日志属性及其值：

属性	值
`methodName`	`google.ssh-serialport.v1.disconnect`
`response.duration`	会话持续的时长（以秒为单位）。
`response.@type`	`type.googleapis.com/google.compute.SerialConsoleSessionEnd`
`operation.last`	`TRUE`

失败的连接日志

连接失败时，Compute Engine 会创建审核日志条目。失败的连接日志看起来与成功的连接条目非常相似，但具有以下指示连接失败的属性。

属性值

severity ERROR

属性	值
`severity`	`ERROR`
`status.code`	能最好地描述错误的 Google API 标准错误代码。以下是可能出现的错误代码： `google.rpc.Code.INVALID_ARGUMENT`：连接失败，因为客户端提供的端口号无效或尝试连接某个未知通道。请参阅有效端口号列表。 `google.rpc.Code.PERMISSION_DENIED`：您尚未在元数据服务器中启用交互式串行控制台。如需了解详情，请参阅启用对串行控制台的交互式访问权限。 `google.rpcCode.UNAUTHENTICATED`：找不到 SSH 密钥或找不到与此实例匹配的 SSH 密钥。请确认您是否通过虚拟机实例的身份验证。 `google.rpc.Code.UNKNOWN`：您的请求出现未知错误。您可以通过 gce-discussion 群组或提交错误报告联系 Google。
`status.message`	针对此条目的人类可读消息。

status.code

能最好地描述错误的 Google API 标准错误代码。以下是可能出现的错误代码：

google.rpc.Code.INVALID_ARGUMENT：连接失败，因为客户端提供的端口号无效或尝试连接某个未知通道。请参阅有效端口号列表。
google.rpc.Code.PERMISSION_DENIED：您尚未在元数据服务器中启用交互式串行控制台。如需了解详情，请参阅启用对串行控制台的交互式访问权限。
google.rpcCode.UNAUTHENTICATED：找不到 SSH 密钥或找不到与此实例匹配的 SSH 密钥。请确认您是否通过虚拟机实例的身份验证。
google.rpc.Code.UNKNOWN：您的请求出现未知错误。您可以通过 gce-discussion 群组或提交错误报告联系 Google。

status.message 针对此条目的人类可读消息。

停用交互式串行控制台访问

可以通过以下两种方式停用交互式串行控制台访问：更改特定实例或项目上的元数据；设置组织政策，停用对组织中一个或多个项目的所有虚拟机实例的交互式串行控制台访问。

在特定实例或项目中停用交互式串行控制台

项目所有者和编辑者以及已被授予 compute.instanceAdmin.v1 角色的用户可以通过更改特定实例或项目的元数据，来停用对串行控制台的访问权限。与启用串行控制台访问权限类似，即是将 serial-port-enable 元数据设置为 FALSE：

serial-port-enable=FALSE

例如，使用 Google Cloud CLI，您可以将此元数据应用于特定实例，如下所示：

gcloud compute instances add-metadata instance-name \
    --metadata=serial-port-enable=FALSE

要将元数据应用于项目，请执行以下命令：

gcloud compute project-info add-metadata \
    --metadata=serial-port-enable=FALSE

通过组织政策停用交互式串行控制台访问

如果您已被授予组织的 orgpolicy.policyAdmin 角色，则无论元数据服务器是否启用了交互式串行控制台访问权限，您都可以通过设置组织政策来阻止对串行控制台的交互式访问。设置组织政策后，该政策会有效地替换 serial-port-enable 元数据键，且组织或项目的所有用户都将无法启用交互式串行控制台访问权限。默认情况下，此限制设置为 FALSE。

停用交互式串行控制台访问权限的限制如下：

compute.disableSerialPortAccess

请按照以下说明在组织中设置此政策。设置政策后，您可以针对单个项目授予豁免。

gcloud

如需使用 Google Cloud CLI 设置政策，请运行 resource-manager enable-enforce 命令。将 organization-id 替换为您的组织 ID。例如 1759840282。

gcloud resource-manager org-policies enable-enforce \
    --organization organization-id compute.disableSerialPortAccess

REST

如需在 API 中设置政策，请向以下网址发出 POST 请求。将 organization-name 替换为您的组织名称。例如 organizations/1759840282。

 POST https://cloudresourcemanager.googleapis.com/v1/organization-name:setOrgPolicy

请求正文应包含具有以下限制的 policy 对象：

"constraint": "constraints/compute.disableSerialPortAccess"

例如：

 {
   "policy":
   {
     "booleanPolicy":
     {
       "enforced": TRUE
     },
     "constraint": "constraints/compute.disableSerialPortAccess"
   }
 }

该政策会立即生效，因此组织下的所有项目都会立即禁止对串行控制台的交互式访问。

如需暂时停用该政策，请使用 disable-enforce 命令：

gcloud resource-manager org-policies disable-enforce \
    --organization organization-id compute.disableSerialPortAccess

或者，您可以发出 API 请求（在请求正文中将 enforced 参数设置为 FALSE）：

{
  "policy":
  {
    "booleanPolicy":
    {
      "enforced": FALSE
    },
    "constraint": "constraints/compute.disableSerialPortAccess"
  }
}

在项目级层设置组织政策

您可以基于每个项目设置相同的组织政策。这将替换组织级设置。

gcloud

如需针对特定项目停止强制执行此政策，请运行以下命令。将 project-id 替换为您的项目 ID。

gcloud resource-manager org-policies disable-enforce \
    --project project-id compute.disableSerialPortAccess

您可以使用具有相同值的 enable-enforce 命令来开始强制执行此政策。

REST

在 API 中，通过向以下网址发出 POST 请求可针对项目启用交互式串行控制台访问权限，将 project-id 替换为项目 ID：

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:setOrgPolicy

请求正文应包含具有以下限制的 policy 对象：

"constraint": "constraints/compute.disableSerialPortAccess"

例如：

{
  "policy":
  {
    "booleanPolicy":
    {
      "enforced": FALSE
    },
    "constraint": "constraints/compute.disableSerialPortAccess"
  }
}

提示和技巧

如果您在使用标准 SSH 客户端进行连接时遇到问题，但 gcloud compute connect-to-serial-port 连接成功，则建议您运行带有 --dry-run 命令行选项的 gcloud compute connect-to-serial-port 命令，以查看代表您运行的 SSH 命令，并将选项与您正在使用的命令进行比较。
设置比特率（也称为波特率）：您可以设置任何所需的比特率（例如 stty 9600），但该功能通常会将有效速率强制设置为 115200 bps（约 11.5kB/秒）。这是因为许多公共映像都会在串行控制台上默认采用较慢的比特率（例如 9600），并且会缓慢启动。
某些操作系统映像的串行端口默认值不方便使用。例如，在 CentOS 7 上，控制台中 Enter 键的默认值 stty icrnl 会发送 CR，也就是 ^M。而由于 bash shell 的掩盖，只有在您尝试设置密码，却发现操作在 password: 提示符出现后就停止不动时，才会察觉这一情况。
如果您以某种特定方式将 shell 连接到端口，有些公共映像会默认停用一些作业控制键。这些键的示例包括 ^Z 和 ^C。setsid 命令可能会解决这个问题。如果不能的话，当您看到 job control is disabled in this shell 消息时，请注意不要运行需要您输入中断的命令。
建议告知系统您正在使用的窗口大小，以便 bash 和编辑器可以妥善管理该窗口。否则，您可能会遇到奇怪的显示行为，因为 bash 或编辑器会尝试根据对可用行数和列数的错误假设来操控显示。使用 stty rows Y cols X 命令和 stty -a 标志查看设置。例如：stty rows 60 cols 120（如果您的窗口是 120 个字符乘 60 行）。
例如，如果您使用 SSH 从机器 A 连接到机器 B，然后再连接到机器 C，从而创建嵌套式 SSH 会话，并且您希望使用波浪号 (~) 命令来执行断开连接或发送串行中断信号等操作，则需要在命令中额外添加足够的波浪号 (~) 字符才能连接至正确的 SSH 客户端。机器 A 上的 SSH 客户端会解释单个波浪号后面的命令；机器 B 上的客户端则解释连续两个波浪号 (Enter~~) 后面的命令，依此类推。您只需要按一次 Enter，因为该输入会一直传到最内层的 SSH 目的地。使用任何提供波浪号转义功能的 SSH 客户端都是如此。

如果您忘记了所需的波浪号字符数，请按 Enter 键，然后逐个输入波浪号字符，直到实例回显波浪号为止。此回显表明您已到达链尾，此时您就知道了如果要向最深层的嵌套 SSH 客户端发送波浪号命令，需要输入的波浪号要比刚才输入的次数少一个。

高级选项

您还可以将以下高级选项与串行端口搭配使用。

控制连接数上限

您可以设置 max-connections 属性来控制此串行端口一次可拥有的并发连接数。连接数的默认值和上限均为 5。例如：

gcloud compute connect-to-serial-port instance-name \
    --port port-number \
    --extra-args max-connections=3

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.max-connections=3@ssh-serialport.googleapis.com

设置重放选项

默认情况下，每次连接到串行控制台时，无论其他 SSH 客户端是否已看到最后 10 行，您都将收到最后 10 行数据的重放。通过设置以下选项，您可以更改此设置并控制返回的行数与行内容：

replay-lines=N：将 N 设置为您要重放的行数。例如，如果 N 为 50，则会包含控制台输出的最后 50 行内容。
replay-bytes=N：重放最新的 N 个字节。您还可以将 N 设置为 new，以重放尚未发送到任何客户端的所有输出。
replay-from=N：从您提供的绝对字节索引开始重放输出。您可以通过发出 getSerialPortOutput 请求来获取串行控制台输出的当前字节索引。如果您设置了 replay-from，则其他所有重放选项都会被忽略。

使用 Google Cloud CLI，将以下内容附加到 connect-to-serial-port 命令，其中 N 是指定的行数（或字节数或绝对字节索引，具体取决于您选择的重放选项）：

--extra-args replay-lines=N

如果您使用的是第三方 SSH 客户端，请在 SSH 命令中提供此选项：

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.replay-lines=N@ssh-serialport.googleapis.com

您还可以使用这些选项的组合。例如：

replay-lines=N 和 replay-bytes=new: 重放指定的行数或重放之前未发送到任何客户端的所有输出，以较大者为准。第一个连接此标志组合的客户端将看到已发送到串行端口的所有输出，后续连接的客户端将只看到最后 N 行。示例：

gcloud compute connect-to-serial-port instance-name--port port-number --extra-args replay-lines=N,replay-bytes=new

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.replay-lines=N.replay-bytes=new@ssh-serialport.googleapis.com

replay-lines=N 和 replay-bytes=M: 重放的行数不超过这些标志所描述的行数或字节数（以较小者为准）。此选项重放的字节数不会超过 N 或 M。

gcloud compute connect-to-serial-port instance-name--port port-number --extra-args replay-lines=N,replay-bytes=M

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.replay-lines=N.replay-bytes=M@ssh-serialport.googleapis.com

处理已丢弃的输出

每个串行端口的最新 1 MiB 输出始终可用，且 SSH 客户端通常不应丢失串行端口中的任何输出。如果由于某种原因，您的 SSH 客户端在一段时间内停止接受输出但并未断开连接，并且产生超过 1 MiB 的新数据，则您的 SSH 客户端可能会丢失部分输出。如果您的 SSH 客户端接受数据的速度不够快，无法与串行控制台端口上的输出保持同步，您可以设置 on-dropped-output 属性来确定控制台的行为方式。

使用此属性设置以下任何适用选项：

insert-stderr-note：在 SSH 客户端的 stderr 上插入一条注释，指示输出已被丢弃。这是默认选项。
ignore：静默地丢弃输出并且不执行任何操作。
disconnect：停止连接。

例如：

gcloud compute connect-to-serial-port instance-name \
    --port port-number \
    --extra-args on-dropped-output=ignore

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.on-dropped-output=ignore@ssh-serialport.googleapis.com

启用通过 exit 或 logout 命令断开连接的功能

当您连接到串行控制台时，可以通过将 on-dtr-low 属性设置为 disconnect 来允许使用 exit 或 logout 命令来断开连接。

在 Google Cloud CLI 中，将以下标志附加到 connect-to-serial-port 命令：

--extra-args on-dtr-low=disconnect

如果您使用的是第三方 SSH 客户端，请在 SSH 命令中提供此选项：

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.on-dtr-low=disconnect@ssh-serialport.googleapis.com

在您重新启动实例时，启用 disconnect 选项可能会导致实例一次或多次断开连接，因为操作系统会在启动时重置串行端口。

on-dtr-low 选项的默认设置为 none。如果使用默认设置 none，您可以在不断开与串行控制台连接的情况下重启实例，但控制台不会通过一般方式（例如 exit 或 logout 命令）或一般组合键（如 Ctrl+D）断开连接。

后续步骤

详细了解 getSerialPortOutput API。
了解如何保留和查看串行端口输出（即使在虚拟机实例被删除之后）。
详细了解问题排查提示。
详细了解如何应用元数据。
了解 SSH 密钥。

使用串行控制台进行问题排查

准备工作

Console

gcloud

REST

执行此任务所需的权限

启用对串行控制台的交互式访问权限

针对项目启用访问

控制台

gcloud

REST

针对虚拟机实例启用访问权限

控制台

gcloud

REST

为 Bare Metal 实例配置串行控制台

连接到串行控制台

控制台

gcloud

其他 SSH 客户端

与串行控制台断开连接

使用登录提示连接到串行控制台

使用启动脚本设置本地密码

Linux

Windows

在虚拟机上使用 passwd 设置本地密码

在其他串行端口上设置登录

systemd

upstart

sysvinit

了解串行端口编号

发送串行中断

查看串行控制台审核日志

停用交互式串行控制台访问

在特定实例或项目中停用交互式串行控制台

通过组织政策停用交互式串行控制台访问

gcloud

REST

在项目级层设置组织政策

gcloud

REST

提示和技巧

高级选项

控制连接数上限

设置重放选项

处理已丢弃的输出

启用通过 exit 或 logout 命令断开连接的功能

后续步骤

在虚拟机上使用 `passwd` 设置本地密码