シリアル コンソールとのやり取り


このページでは、インスタンスのシリアル コンソールへのインタラクティブ アクセスを有効にして、起動やネットワークの問題のデバッグ、不具合のあるインスタンスのトラブルシューティング、GRand Unified Bootloader(GRUB)の操作、その他のトラブルシューティングを行う方法を説明します。

仮想マシン インスタンスには 4 つの仮想シリアルポートがあります。シリアルポートの操作は、入力と出力の全体がテキストモードになり、グラフィカル ユーザー インターフェースやマウスのサポートがないという点で、ターミナル ウィンドウを使用する場合に似ています。インスタンスのオペレーティング システム、BIOS、その他のシステムレベルのエンティティは多くの場合、出力をシリアルポートに書き込み、コマンドやプロンプトへの応答などの入力にアクセスできます。通常、これらのシステムレベルのエンティティは最初のシリアルポート(ポート 1)を使用します。多くの場合、シリアルポート 1 はシリアル コンソールと呼ばれます。

シリアル コンソールにコマンドを発行せずにシリアルポート出力を表示するだけの場合は、getSerialPortOutput メソッドを呼び出すか、または Cloud Logging を使用して、インスタンスがシリアルポートに書き込んだ情報を読み込みます。シリアルポート ログの表示をご覧ください。ただし、SSH 経由でのインスタンスへのアクセスで問題が発生した場合や、完全に起動していないインスタンスのトラブルシューティングを行う必要がある場合は、シリアル コンソールへのインタラクティブ アクセスを有効にすると、任意のインスタンスのシリアルポートへの接続と操作が可能になります。たとえば、シリアルポートで直接コマンドを実行することや、プロンプトに応答することが可能です。

シリアルポートを有効または無効にするときは、メタデータ サーバーが受け入れる任意のブール値を使用できます。詳細は、ブール値の設定をご覧ください。

始める前に

このタスクに必要な権限

このタスクを行うには、次の権限が必要です。

  • 特定のインスタンスのインタラクティブ アクセスを有効にする場合、インスタンスに対する compute.instances.setMetadata
  • プロジェクト全体でインタラクティブ アクセスを有効にする場合、プロジェクトに対する compute.projects.setCommonInstanceMetadata
  • インスタンスのサービス アカウントに対する iam.serviceAccountUser ロール

シリアル コンソールでのインタラクティブ アクセスの有効化

個々の VM インスタンスまたはプロジェクト全体についてインタラクティブ シリアル コンソール アクセスを有効にします。

プロジェクトのアクセスを有効にする

プロジェクトでインタラクティブ シリアル コンソール アクセスを有効にすると、そのプロジェクトに属するすべての VM インスタンスにアクセスできるようになります。

デフォルトでは、インタラクティブ シリアルポート アクセスは無効になっています。serial-port-enable キーを FALSE に設定することで、明示的に無効にすることもできます。いずれの場合も、インスタンス単位の設定がプロジェクトレベルの設定やデフォルトの設定よりも優先されます。

Console

  1. Google Cloud Console で、[メタデータ] ページに移動します。

    [メタデータ] に移動

  2. [編集] をクリックして、メタデータ エントリを編集します。
  3. キーを serial-port-enable、値を TRUE とする新しいエントリを追加します。
  4. 変更を保存します。

gcloud

gcloud コマンドライン ツールを使用して、次のように project-info add-metadata コマンドを入力します。

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

API

API では、projects().setCommonInstanceMetadata メソッドに対してリクエストを実行します。このとき、キーに serial-port-enable、値に TRUE を指定します。

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

VM インスタンスのアクセスを有効にする

特定のインスタンスに対してインタラクティブ シリアル コンソール アクセスを有効にします。インスタンス単位の設定が存在する場合は、その設定がプロジェクト レベルの設定より優先されます。プロジェクト レベルでアクセスが有効になっている場合でも、serial-port-enableTRUE の代わりに FALSE を設定して、特定のインスタンスへのアクセスを無効にできます。同様に、プロジェクトが明示的またはデフォルトでアクセスが無効になっている場合でも、1 つ以上のインスタンスのアクセスを有効にできます。

Console

  1. Google Cloud Console で、[VM インスタンス] ページに移動します。

    [VM インスタンス] ページに移動

  2. アクセスを有効にするインスタンスをクリックします。
  3. [編集] をクリックします。
  4. [リモート アクセス] セクションで、[シリアルポート接続を有効化] チェックボックスをオンにします。
  5. 変更を保存します。

gcloud

gcloud コマンドライン ツールを使用して、instances add-metadata コマンドを入力します。このとき、instance-name はインスタンスの名前に置き換えます。

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

API

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"
  }
 ]
}

シリアル コンソールへの接続

インスタンスのシリアル コンソールの対話型アクセスを有効にした後にシリアル コンソールに接続するには、Google Cloud Console、gcloud コマンドライン ツール、サードパーティの SSH クライアントのいずれかを使用します。

シリアル コンソールは、SSH 認証鍵を使用してユーザーを認証します。具体的には、SSH 公開鍵をプロジェクトまたはインスタンスのメタデータに追加し、秘密鍵は接続元のローカルマシンに保存する必要があります。gcloud ツールと Google Cloud Console を使用すると、SSH 認証鍵は自動でプロジェクトに追加されます。サードパーティのクライアントを使用している場合は、SSH 認証鍵を手動で追加しなければならない場合があります。

Console

  1. Google Cloud Console で、[VM インスタンス] ページに移動します。

    [VM インスタンス] ページに移動

  2. 接続先のインスタンスをクリックします。
  3. [リモート アクセス] で、[シリアル コンソールに接続] をクリックして、デフォルト ポート(ポート 1)に接続します。
  4. 別のシリアルポートに接続する場合は、[シリアル コンソールに接続] ボタンの横にある下矢印をクリックして、必要に応じてポート番号を変更します。
  5. Windows インスタンスの場合は、ボタンの横にあるプルダウン メニューを開いてポート 2 へ接続し、シリアル コンソールにアクセスします。

gcloud

gcloud コマンドライン ツールの gcloud compute connect-to-serial-port サブコマンドを使用して接続します。このとき、instance-name は、アクセスするシリアル コンソールのインスタンス名に置き換えます。

gcloud compute connect-to-serial-port instance-name

デフォルトでは、connect-to-serial-port コマンドはシリアル コンソールのポート 1 に接続します。Windows VM インスタンスに接続する場合は、代わりにポート 2 に接続します。

gcloud compute connect-to-serial-port instance-name \
    --port 2

その他のポートに接続するには、--port フラグを使用して別のポート番号を割り当てます。ポート番号には、1 以上 4 以下を指定できます。ポート番号の詳細については、シリアルポート番号についてをご覧ください。

その他の SSH クライアント

サードパーティの SSH クライアントでも、それが TCP ポート 9600 に接続できるのであれば、インスタンスのシリアル コンソールに接続できます。

たとえば、次の SSH コマンドを使用すると、プロジェクト ID が myproject のプロジェクトのインスタンス example-instance のデフォルト シリアルポート(1)に、ユーザー名 jane で接続します。インスタンスはゾーン us-central1-f 内にあります。また、private-ssh-key-file はインスタンスの秘密 SSH 鍵ファイルで置き換えます。

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane@ssh-serialport.googleapis.com
 

より具体的には、インスタンスのシリアル コンソールに接続するには、ログインとアドレス情報を次のように指定します。

project-id.zone.instance-name.username.options@ssh-serialport.googleapis.com

以下を置き換えます。

  • project-id: このインスタンスのプロジェクト ID。
  • zone: インスタンスのゾーン。
  • instance-name: インスタンスの名前。
  • username: インスタンスへの接続に使用しているユーザー名。通常、これはローカルマシンのユーザー名です。
  • options: この接続に対して指定できる追加オプション。たとえば、特定のシリアルポートや、後述する任意の詳細オプションを指定できます。ポート番号には 1~4 を指定できます。ポート番号の詳細については、シリアルポート番号についてをご覧ください。省略した場合は、シリアルポート 1 に接続します。

Windows VM インスタンスに接続する場合は、次のコマンドを使用してポート 2 経由で接続します。

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

サードパーティの SSH クライアントを使用して接続できない場合は、gcloud compute connect-to-serial-port コマンドに --dry-run コマンドライン オプションを付けて実行します。自動的に実行される SSH コマンドを確認して、コマンドとオプションを比較できます。

安全な接続の設定

gcloud コマンドライン ツール以外のサードパーティの SSH クライアントを使用し、Google のシリアルポート サーバーの SSH 認証鍵を確認することで、なりすまし攻撃や中間者攻撃を防ぐことができます。サーバーの SSH 認証鍵を確認するようにシステムを設定するには、次の手順を実行します。

  1. Google のシリアルポート サーバーの SSH 認証鍵をダウンロードします。
  2. 既知のホストファイルを開きます。通常は ~/.ssh/known_hosts にあります。
  3. サーバーの SSH 認証鍵の内容を、鍵の先頭に ssh-serialport.googleapis.com を付加して追加します。たとえば、サーバーの認証鍵が ssh-rsa AAAAB3NzaC1yc... となっている場合、~/.ssh/known_hosts は次のような形にする必要があります。

    ssh-serialport.googleapis.com ssh-rsa AAAAB3NzaC1yc...

Google は、セキュリティ上の理由により、Google シリアルポート サーバーの SSH 認証鍵を変更することがあります。クライアントがサーバーキーを認証できない場合は、すぐに接続の動作を中止し、前記の手順で新しい Google シリアルポート サーバーの SSH 認証鍵をダウンロードします。

ホストキーを更新しても引き続きクライアントでホスト認証エラーが発生する場合は、シリアルポートへの接続手順を中止し、Google サポートにお問い合わせください。ホスト認証が失敗している接続では、認証情報を入力しないでください。

シリアル コンソールからの接続解除

シリアル コンソールから接続を解除するには:

  1. ENTER キーを押します。
  2. ~.」(チルダとピリオド)を入力します。

その他のコマンドを検索するには、~? を入力します。または、SSH のマニュアル ページを調べることができます。

man ssh

次のいずれかのコマンドを使用して切断しないでください。

  • CTRL+ALT+DELETE キーの組み合わせまたは他の類似した組み合わせ。シリアル コンソールは PC キーボードのキーの組み合わせを認識しないため、このような組合せは機能しません。

  • exit または logout コマンド。ゲストはネットワークまたはモデムの接続を認識しないため、これらのコマンドは機能しません。このコマンドを使用すると、コンソールが閉じてから再び開き、セッションに接続された状態が維持されます。セッションに対して exit コマンドと logout コマンドを有効にする場合は、on-dtr-low オプションを設定します。

ログイン プロンプトを使用したシリアル コンソールへの接続

完全に起動したインスタンスの問題や、インスタンスが過去のシングル ユーザーモードを起動した後で発生する問題をトラブルシューティングしようとしている場合は、シリアル コンソールにアクセスしようとしたときに、ログイン情報を求めるプロンプトが表示される場合があります。

デフォルトでは、Google が提供するシステム イメージは、ローカル ユーザーにパスワード ベースのログインを許可するよう構成されていません。インスタンスが実行しているイメージにシリアルポートのログインが事前に構成されている場合は、仮想マシンのインスタンスにローカル パスワードを設定し、シリアル コンソールにログインできます。

ローカル パスワードの設定

仮想マシンのインスタンス上でユーザーのローカル パスワードを設定し、そのパスワードを使ってそのインスタンスのシリアル コンソールにログインできるようにするには、次の手順に従います。

  1. インスタンスに接続します。ここで、instance-name は実際のインスタンス名に置き換えます。

    gcloud compute ssh instance-name
  2. インスタンスで、次のコマンドを使用してローカル パスワードを作成します。このコマンドは、現在ログインしているユーザーのパスワードを設定します。

    sudo passwd $(whoami)
  3. プロンプトに従ってパスワードを作成します。

  4. 次に、インスタンスからログアウトして、シリアル コンソールに接続します。

  5. プロンプトが表示されたら、ログイン情報を入力します。

他のシリアルポートのログインの設定

ほとんどの Linux オペレーティング システムでは、デフォルトによりポート 1 でログイン プロンプトが有効になっています。しかし、ポート 1 に出力されるロギングデータや他の情報がポートの処理能力を超えることがあります。そのような場合は、次のコマンドのいずれかをインスタンスで実行して、ポート 2(ttyS1)など別のポートでログイン プロンプトを有効にできます。インスタンスの利用可能なポートのリストについては、シリアルポート番号についてをご覧ください。

シリアル コンソール ログインとデフォルトのポートが事前構成された OS イメージの一覧を下表に示します。

OS ログイン プロンプトのデフォルト ポート サービス管理
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 オペレーティングシステムでは、次のコマンドを実行します。

  1. 既存の ttyS0.conf ファイルのコピーに ttyS1 の変更を加え、新しく /etc/init/ttyS1.conf ファイルを作成してそれを反映させます。次に例を示します。

    • Ubuntu 14.04 の場合:

      sudo sh -c "sed -e s/ttyS0/ttyS1/g < /etc/init/ttyS0.conf > /etc/init/ttyS1.conf"
    • 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"
  2. 再起動せずに ttyS1 でログイン プロンプトを開始します。

    sudo start ttyS1

sysvinit

sysvinit を使用する Linux オペレーティング システムの場合は、次の一連のコマンドを実行します。

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

シリアルポート番号について

仮想マシン インスタンスには、それぞれ 4 つのシリアルポートがあります。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 コマンドを送信するには、次の手順に従います。

  1. ENTER キーを押します。
  2. ~B を入力します(チルダと大文字の B)。
  3. Magic SysRq コマンドを入力します。

シリアル コンソール監査ログの表示

Compute Engine により、インスタンスのシリアル コンソールの接続と接続解除を行ったユーザーを追跡する監査ログが提供されます。ログを表示するには、ログビューアの権限を持っているか、プロジェクトの閲覧者または編集者である必要があります。

  1. Google Cloud Console の [ログ] ページに移動します。

    [ログ] ページに移動

  2. プルダウン メニューを展開して [GCE VM Instance] を選択します。
  3. 検索バーに「ssh-serialport.googleapis.com」と入力して、Enter を押します。
  4. 監査ログのリストが表示されます。ログにはシリアル コンソールとの接続と切断が記録されています。任意のエントリを展開して詳細情報を表示します。

    シリアル コンソールの監査ログ。

監査ログでは、次の操作ができます。

  1. protoPayload プロパティを展開します。
  2. methodName を探して、このログが適用されるアクティビティ(接続リクエストまたは接続解除リクエスト)を確認します。たとえば、このログでシリアル コンソールからの接続解除が追跡される場合、メソッド名は "google.ssh-serialport.v1.disconnect" になります。同様に、接続ログには "google.ssh-serialport.v1.connect" と記録されます。監査ログエントリは、シリアル コンソールでの各セッションの開始時と終了時に記録されます。

ログタイプに応じてさまざまな監査ログプロパティがあります。たとえば、接続に関する監査ログには接続ログに固有のプロパティ、切断に関する監査ログには切断に固有のプロパティがあります。また、監査ログの一部のプロパティは、この 2 つのログタイプ間で共有されます。

シリアル コンソールのすべてのログ

プロパティ
requestMetadata.callerIp 接続元の IP アドレスとポート番号。
serviceName ssh-serialport.googleapis.com
resourceName 関連するシリアル コンソールを示すための、プロジェクト ID、ゾーン、インスタンス名、シリアルポート番号を含む文字列。たとえば、projects/myproject/zones/us-east1-a/instances/example-instance/SerialPort/2 は、インスタンス example-instance(COM2 または /dev/ttyS1 とも呼ばれる)のポート番号 2 です。
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
status.code

エラーを最もよく表す標準的な Google API エラーコード。表示される可能性のあるエラーコードは次のとおりです。

status.message 人が読める形式の、このエントリのメッセージ。

インタラクティブ シリアル コンソール アクセスを無効にする

インタラクティブ シリアル コンソール アクセスを無効にするには、特定のインスタンスまたはプロジェクトのメタデータを変更するか、インタラクティブ シリアル コンソール アクセスを無効にする組織ポリシーを組織の一部である 1 つ以上のプロジェクトのすべての VM インスタンスに設定します。

特定のインスタンスまたはプロジェクトのインタラクティブ シリアル コンソールを無効にする

プロジェクトのオーナー、編集者、compute.instanceAdmin.v1 の役割を付与されたユーザーは、特定のインスタンスまたはプロジェクトのメタデータを変更して、シリアル コンソールへのアクセスを無効にできます。シリアル コンソール アクセスを有効にする場合と同様に、serial-port-enable メタデータを FALSE に設定します。

serial-port-enable=FALSE

たとえば、gcloud コマンドライン ツールを使用して、このメタデータを次のように特定のインスタンスに適用できます。

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

gcloud コマンドライン ツールを使用してポリシーを設定するには、resource-manager enable-enforce コマンドを実行します。ここで、organization-id は実際の組織 ID に置き換えます。例: 1759840282

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

API

API でポリシーを設定するには、次の URL に POST リクエストを行います。ここで、organization-name は実際の組織名に置き換えます。例: organizations/1759840282

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

リクエストの本文には、policy オブジェクトに次の制約を設定します。

"constraint": "constraints/compute.disableSerialPortAccess"

次に例を示します。

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

このポリシーは直ちに有効になるため、この組織配下のプロジェクトでは、シリアル コンソールへのインタラクティブ アクセスが許可されなくなります。

ポリシーを一時的に無効にするには、disable-enforce コマンドを使用します。

gcloud alpha 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 alpha resource-manager org-policies disable-enforce \
    --project project-id compute.disableSerialPortAccess

enable-enforce コマンドに同じ値を適用すると、このポリシーの強制適用を有効にできます。

API

API では、次の URL に対して POST リクエストを行い、プロジェクトのインタラクティブ シリアル コンソール アクセスを有効にできます。このとき、project-id はプロジェクト ID で置き換えます。

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

リクエストの本文には、次の制約を設定した policy オブジェクトを含めます。

"constraint": "constraints/compute.disableSerialPortAccess"

次に例を示します。

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

ヒントとアドバイス

  • 標準の SSH クライアントで接続できず、gcloud compute connect-to-serial-port で接続できる場合は、gcloud compute connect-to-serial-port--dry-run コマンドライン オプションを指定して実行してみてください。本来実行されるはずの SSH コマンドを確認して、使用しているコマンドとのオプションの違いを比較できます。

  • ビットレート(ボーレート)の設定では、stty 9600 などの任意の値を設定できますが、通常は実効レートが強制的に 115,200 bps(約 11.5 kB/sec)に設定されます。これは、多くの公開イメージではデフォルトで 9,600 などの低速なビットレートがシリアル コンソールに設定され、起動に時間がかかるためです。

  • OS イメージによっては、シリアルポートのデフォルト値では都合が悪い場合があります。たとえば CentOS 7 では、stty icrnl がコンソールの Enter キーのデフォルトで、これは CR(別名 ^M)を送信します。パスワードの設定を開始するまで bash シェルによってこれがマスクされる場合があり、password: プロンプトで動作が停止したように見える原因がわからず首をかしげることになります。

  • 公開イメージによっては、特定の方法でシェルをポートに接続しようとしたときに、デフォルトで無効になるジョブ コントロール キーがあります。これらのキーの例として、^Z^C が挙げられます。この問題は、setsid コマンドで修正できる場合もありますが、修正できない場合は、job control is disabled in this shell メッセージが表示されたら、割り込みが必要なコマンドを実行しないように注意してください。

  • ウィンドウのサイズをシステムに通知すると、bash やエディタがウィンドウを適切に管理できます。サイズを通知しなければ、bash やエディタは使用可能な行数と列数の不正確な想定に基づいてディスプレイを操作しようとするため、ディスプレイの動作に異常をきたすことがあります。設定を確認するには、stty rows Y cols X コマンドと stty -a フラグを使用します。たとえば、ウィンドウが 120 文字 × 60 行の場合は、stty rows 60 cols 120 となります。

  • SSH を使用してマシン A からマシン B に接続し、さらにマシン C などに接続してネストされた SSH セッションを作成した場合、チルダ(~)コマンドで切断やシリアル ブレーク信号の送信などを行う際は、適切な SSH クライアントに達するのに十分な数のチルダをコマンドに追加する必要があります。1 つのチルダの後に続くコマンドはマシン A 上の SSH クライアントによって解釈され、2 つの連続したチルダ(Enter~~)はマシン B 上のクライアントによって解釈されるというように動作します。Enter キーは SSH の最も内側の宛先まで渡されるため、押す必要があるのは 1 回のみです。これは、チルダのエスケープ機能を備えた SSH クライアントを利用するときに例外なく当てはまります。

    必要なチルダの数がわからなくなった場合は、Enter キーを押した後、インスタンスがチルダをエコーバックするまで 1 度に 1 回ずつチルダキーを押します。このときチェーンの終わりに到達したので、ネストの最も奥の SSH クライアントにチルダコマンドを送信するには、入力した回数より 1 少ない数のチルダが必要なことがわかります。

詳細オプション

最大接続数の管理

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

リプレイ オプションの設定

デフォルトでは、シリアル コンソールに接続するたびに、データの最後の 10 行が別の SSH クライアントに表示されたかどうかに関係なく、その 10 行のリプレイを受信します。この設定を変更して返される行数と内容を管理するには、次のオプションを指定します。

  • replay-lines=N: N にリプレイする行数を設定します。たとえば、N が 50 の場合は、コンソール出力の最後の 50 行が含まれます。
  • replay-bytes=N: 直近の N バイトをリプレイします。Nnew に設定して、クライアントにまだ送信されていないすべての出力をリプレイすることもできます。
  • replay-from=N: ユーザーが指定した絶対バイト インデックス以降の出力をリプレイします。getSerialPortOutput リクエストを行うことで、シリアル コンソール出力の現在のバイト インデックスを取得できます。replay-from を設定すると、他のすべてのリプレイ オプションは無視されます。

gcloud コマンドライン ツールを使用して、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 コマンドによる接続解除を有効にできます。

gcloud コマンドライン ツールで、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 オプションを有効にすると、インスタンスを再起動しているとき、オペレーティング システムが起動中にシリアルポートをリセットするため、インスタンスで 1 回以上接続の切断が発生する可能性があります。

on-dtr-low オプションのデフォルトの設定は none です。デフォルトの設定 none を使用すると、シリアル コンソールから接続を解除せずにインスタンスを再起動できますが、コンソールは exit コマンドや logout コマンドなどの通常の方法を使っても、Ctrl+D などの通常のキーの組み合わせを使用しても接続が切断されなくなります。

次のステップ