직렬 콘솔을 사용한 문제 해결

Linux Windows

이 페이지에서는 인스턴스의 직렬 콘솔에 대한 대화형 액세스를 사용 설정하여 부팅 및 네트워킹 문제를 디버그하고 고장 난 인스턴스의 문제를 해결하고 GRUB(GRand Unified Bootloader)와 상호작용하고 기타 문제해결 작업을 수행하는 방법을 설명합니다.

가상 머신(VM) 인스턴스에는 4개의 가상 직렬 포트가 있습니다. 직렬 포트와의 상호작용은 입력 및 출력이 완전한 텍스트 모드라는 점과 그래픽 인터페이스 또는 마우스 지원이 없다는 점에서 터미널 창과 유사합니다. 인스턴스의 운영체제, BIOS, 기타 시스템 수준의 항목은 종종 직렬 포트에 출력을 쓰고 프롬프트의 명령어나 답변과 같은 입력을 허용할 수 있습니다. 일반적으로 이러한 시스템 수준의 항목은 첫 번째 직렬 포트(포트 1)를 사용하고 직렬 포트 1은 종종 직렬 콘솔이라고도 합니다.

직렬 콘솔에 대해 어떤 명령어도 실행하지 않고 직렬 포트 출력을 보기만 하려는 경우 getSerialPortOutput 메서드를 호출하거나 Cloud Logging을 사용하여 인스턴스가 직렬 포트에 작성한 정보를 읽을 수 있습니다(직렬 포트 로그 보기 참조). 하지만 SSH를 통해 인스턴스에 액세스할 때 문제가 발생하거나 완전히 부팅되지 않은 인스턴스 문제를 해결해야 할 경우 직렬 콘솔에 대한 대화형 액세스를 사용 설정하면 인스턴스의 모든 직렬 포트에 연결하고 상호작용할 수 있습니다. 예를 들어 직접 명령어를 실행하고 직렬 포트의 프롬프트에 응답할 수 있습니다.

직렬 포트를 사용 설정 또는 사용 중지하면 메타데이터 서버에서 허용하는 모든 부울 값을 사용할 수 있습니다. 자세한 내용은 부울 값 설정을 참조하세요.

시작하기 전에

아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인하는 프로세스입니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음과 같이 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.

이 태스크에 필요한 권한

이 작업을 수행하려면 다음과 같은 권한이 있어야 합니다.

특정 VM에 대화형 액세스를 사용 설정하는 경우 VM에 대한 compute.instances.setMetadata
프로젝트의 모든 VM에 대화형 액세스를 사용 설정하는 경우 프로젝트에 대한 compute.projects.setCommonInstanceMetadata
인스턴스의 서비스 계정에 대한 iam.serviceAccountUser 역할

직렬 콘솔에서 대화형 액세스 사용 설정

개별 VM 인스턴스 또는 전체 프로젝트에서 대화형 직렬 콘솔 액세스를 사용 설정할 수 있습니다.

프로젝트에서 액세스 사용 설정

프로젝트에서 대화형 직렬 콘솔 액세스를 사용 설정하면 해당 프로젝트에 포함된 모든 VM 인스턴스에서 대화형 직렬 콘솔 액세스가 사용 설정됩니다.

기본적으로 대화형 직렬 포트는 사용 중지되어 있습니다. 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 메서드에 요청을 보내고 값이 TRUE인 serial-port-enable 키를 제공합니다.

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

VM 인스턴스에서 액세스 사용 설정

특정 인스턴스에서 대화형 직렬 콘솔 액세스를 사용 설정할 수 있습니다. 인스턴스별 설정이 있는 경우에는 이 설정이 프로젝트 수준 설정보다 우선합니다. 또한 프로젝트 수준에서 액세스가 사용 설정되어 있더라도 serial-port-enable을 TRUE 대신 FALSE으로 설정하면 특정 인스턴스의 액세스를 사용 중지할 수 있습니다. 마찬가지로 프로젝트에서 액세스가 명시적으로 또는 기본적으로 사용 중지되어 있더라도 하나 이상의 인스턴스에서 액세스를 사용 설정할 수 있습니다.

콘솔

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.
VM 인스턴스 페이지로 이동
액세스를 사용 설정할 인스턴스를 클릭합니다.
수정을 클릭합니다.
원격 액세스 섹션에서 직렬 포트 연결 사용 설정 체크박스를 전환합니다.
변경사항을 저장합니다.

gcloud

Google Cloud CLI를 사용하여 instances add-metadata 명령어를 입력하고 instance-name을 인스턴스 이름으로 바꿉니다.

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

REST

API에서 serial-port-enable 키와 값이 TRUE인 instances().setMetadata 메서드로 요청을 보냅니다.

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

직렬 콘솔에 연결

인스턴스의 직렬 콘솔에 대한 대화형 액세스를 사용 설정하면 직렬 콘솔로 연결할 수 있습니다.

Compute Engine은 각 Google Cloud 리전마다 전역 직렬 콘솔 게이트웨이와 리전 직렬 콘솔 게이트웨이를 제공합니다. 전역 또는 리전 게이트웨이를 사용하여 VM의 직렬 콘솔에 연결할 수 있지만 신뢰성 향상을 위해 리전 게이트웨이를 사용하는 것이 좋습니다.

Google Cloud 콘솔을 사용하여 직렬 콘솔에 연결하면 리전 직렬 콘솔에 자동으로 연결됩니다. Google Cloud CLI를 사용하는 경우 리전 또는 전역 게이트웨이 중에서 선택할 수 있습니다. 다른 SSH 클라이언트를 통한 연결은 전역 게이트웨이만 지원합니다.

직렬 콘솔은 SSH 키로 사용자를 인증합니다. 특히 공개 SSH 키를 프로젝트 또는 인스턴스 메타데이터에 추가하여 연결하려는 로컬 머신에 비공개 키를 저장해야 합니다. gcloud CLI 및 Google Cloud 콘솔이 SSH 키를 자동으로 프로젝트에 추가합니다. 타사 클라이언트를 사용하는 경우 SSH 키를 수동으로 추가해야 할 수 있습니다.

콘솔

VM의 리전 직렬 콘솔에 연결하려면 다음을 수행합니다.

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.
VM 인스턴스 페이지로 이동
연결하려는 인스턴스를 클릭합니다.
원격 액세스에서 직렬 콘솔에 연결을 클릭하여 기본 포트(포트 1)에 연결합니다.
다른 직렬 포트에 연결하려면 직렬 콘솔에 연결 버튼 옆의 아래쪽 화살표를 클릭하고 포트 번호를 알맞게 변경합니다.
Windows 인스턴스의 경우 버튼 옆의 드롭다운 메뉴를 열어 포트 2에 연결한 후 직렬 콘솔에 액세스합니다.

gcloud

VM의 리전 또는 전역 직렬 콘솔에 연결하려면 다음 명령어 중 하나를 사용합니다.

권장: VM의 리전별 직렬 콘솔에 연결하려면 gcloud compute connect-to-serial-port 명령어를 사용하고 --location 플래그를 포함합니다.
```
gcloud compute connect-to-serial-port VM_NAME \
  --location=REGION \
  --port=PORT_NUMBER
```
VM의 전역 직렬 콘솔에 연결하려면 gcloud compute connect-to-serial-port 명령어를 사용하고 --location 플래그를 생략합니다.
```
gcloud compute connect-to-serial-port VM_NAME \
  --port=PORT_NUMBER
```

다음을 바꿉니다.

VM_NAME: 직렬 콘솔을 연결할 VM의 이름입니다.
REGION: 직렬 콘솔을 연결할 VM의 리전입니다.
PORT_NUMBER: 연결할 포트 번호입니다. Linux VM의 경우 1, Windows VM의 경우 2를 사용합니다. 포트 번호에 대한 자세한 내용은 직렬 포트 번호 지정 이해를 참조하세요.

참고: 기본 포트 번호는 1입니다.

기타 SSH 클라이언트

클라이언트를 통해 TCP 포트 9600에 연결되어 있는 경우에만 기타 제3자 SSH 클라이언트를 사용하여 인스턴스의 직렬 콘솔에 연결할 수 있습니다.

예를 들어 다음 SSH 명령어는 프로젝트 ID가 myproject인 프로젝트에서 이름이 example-instance이고 사용자 이름이 jane인 인스턴스의 기본 직렬 포트(1)에 연결됩니다. 인스턴스는 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

제3자 SSH 클라이언트를 사용하여 연결하는 데 문제가 있는 경우 --dry-run 명령줄 옵션으로 gcloud compute connect-to-serial-port 명령어를 실행하여 자동으로 실행된 SSH 명령어를 확인할 수 있습니다. 그 다음 사용 중인 명령어와 옵션을 비교할 수 있습니다.

보안 연결 설정

Google Cloud CLI가 아닌 제3자 SSH 클라이언트를 사용하는 경우 Google의 직렬 포트 서버 SSH 키를 확인하여 명의 도용 또는 중간자 공격으로부터 보호되는지 확인할 수 있습니다. 서버 SSH 키를 확인하도록 시스템을 설정하려면 다음 단계를 완료하세요.

Google의 직렬 포트 서버 SSH 키를 다운로드합니다.
알려진 호스트 파일을 엽니다. 일반적인 위치는 ~/.ssh/known_hosts입니다.
키 앞에 ssh-serialport.googleapis.com을 추가하여 서버 SSH 키의 콘텐츠를 추가합니다. 예를 들어 서버 키에 ssh-rsa AAAAB3NzaC1yc... 행이 있으면 ~/.ssh/known_hosts에 다음 행이 있어야 합니다.
```
ssh-serialport.googleapis.com ssh-rsa AAAAB3NzaC1yc...
```

보안상의 이유로 Google은 Google 직렬 포트 서버의 SSH 키를 변경할 수 있습니다. 클라이언트가 서버 키 인증에 실패하는 경우 즉시 연결 시도를 종료하고 이전 단계를 완료하여 새 Google 직렬 포트 서버 SSH 키를 다운로드합니다.

호스트 키를 업데이트한 후에도 클라이언트에서 호스트 인증 오류가 계속 수신되면 직렬 포트에 대한 연결 시도를 중지하고 Google 지원에 문의하세요. 호스트 인증이 실패한 연결에 대해 어떠한 사용자 인증도 제공해서는 안 됩니다.

직렬 콘솔에서 연결 해제

직렬 콘솔에서 연결을 해제하려면 다음을 수행합니다.

ENTER 키를 누릅니다.
~.(물결표시와 마침표)을 입력합니다.

~?을 입력하거나 SSH의 설명 페이지를 검토하여 다른 명령어를 탐색할 수 있습니다.

man ssh

다음과 같은 메서드를 사용하여 연결 해제를 시도하지 마세요.

CTRL+ALT+DELETE 키 조합 또는 기타 유사 조합. 직렬 콘솔이 PC 키보드 조합을 인식하지 못하기 때문에 이 메서드는 작동하지 않습니다.
게스트가 네트워크 또는 모뎀 연결을 인식하지 못하기 때문에 exit 또는 logout 명령어는 작동하지 않습니다. 이 명령어를 사용하면 콘솔이 닫혔다가 다시 열리고, 사용자는 세션에 연결된 상태로 유지됩니다. 세션에 exit 및 logout 명령어를 사용 설정하려는 경우 on-dtr-low 옵션을 설정하여 이를 사용 설정할 수 있습니다.

로그인 프롬프트로 직렬 콘솔에 연결

완전히 부팅된 VM에 발생한 문제를 해결하거나 VM이 이전 단일 사용자 모드를 부팅한 후 발생하는 문제를 해결하려고 하는 경우 직렬 콘솔에 액세스를 시도할 때 로그인 정보를 입력하라는 메시지가 표시될 수 있습니다.

기본적으로 Google 제공 Linux 시스템 이미지는 로컬 사용자에게 비밀번호 기반 로그인을 허용하도록 구성되어 있지 않습니다. 하지만 Google 제공 Windows 이미지는 로컬 사용자에게 비밀번호 기반 로그인을 허용하도록 구성되어 있습니다.

VM이 직렬 포트 로그인으로 사전 구성된 이미지를 실행 중인 경우 메시지가 나타나면 직렬 콘솔에 로그인할 수 있도록 VM에서 로컬 비밀번호를 설정해야 합니다. 로컬 비밀번호는 VM에 연결한 후에 또는 시작 스크립트를 사용해 설정할 수 있습니다.

시작 스크립트를 사용한 로컬 비밀번호 설정

시작 스크립트를 사용하면 VM이 생성되는 동안 또는 이후에 직렬 콘솔에 연결할 수 있는 로컬 비밀번호를 설정할 수 있습니다.

다음 안내에서는 VM 생성 이후에 로컬 비밀번호를 설정하는 방법을 설명합니다.

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.

VM 인스턴스로 이동
로컬 비밀번호를 추가할 VM을 선택합니다.
수정을 클릭합니다.
Linux
1. 메타데이터 > 자동화 섹션으로 이동합니다.
2. VM에 기존 시작 스크립트가 있는 경우 복사하여 안전한 위치에 붙여넣습니다.
3. 다음 시작 스크립트를 추가합니다.
```
#!/bin/bash
useradd USERNAME
echo USERNAME:PASSWORD | chpasswd
usermod -aG google-sudoers USERNAME
```
  다음을 바꿉니다.
  - USERNAME: 추가할 사용자 이름
  - PASSWORD: 사용자 이름의 비밀번호. 일부 운영체제에서는 비밀번호 길이와 복잡성을 최소화해야 할 수 있으므로 간단한 비밀번호는 피하세요.
Windows
1. 커스텀 메타데이터 섹션으로 이동합니다.
2. VM에 기존 시작 스크립트가 있는 경우 이를 복사하여 안전한 곳에 붙여넣습니다.
3. 항목 추가를 클릭합니다.
4. 키 필드에 windows-startup-script-cmd을 입력합니다.
5. 값 필드에 다음 스크립트를 입력합니다.
```
net user USERNAME PASSWORD /ADD /Y
net localgroup administrators USERNAME /ADD
```
  다음을 바꿉니다.
  - USERNAME: 추가할 사용자 이름
  - PASSWORD: 사용자 이름의 비밀번호
저장을 클릭합니다.
VM을 재부팅하려면 재설정을 클릭합니다. 자세한 내용은 VM 재설정을 참조하세요.
직렬 콘솔에 연결합니다.
메시지가 나타나면 로그인 정보를 입력합니다.
사용자를 만든 후 VM에서 시작 스크립트를 삭제합니다.

VM에서 `passwd`을 사용한 로컬 비밀번호 설정

다음 안내는 사용자가 지정된 비밀번호를 사용하여 VM의 직렬 콘솔에 로그인할 수 있도록 VM에서 로컬 비밀번호를 설정하는 방법에 대해 설명합니다.

VM에 연결합니다. 여기에서 instance-name을 인스턴스의 이름으로 바꿉니다.
```
gcloud compute ssh instance-name
```
VM에서 다음 명령어로 로컬 비밀번호를 만듭니다. 이렇게 하면 현재 로그인된 사용자의 비밀번호가 설정됩니다.
```
sudo passwd $(whoami)
```
메시지에 따라 비밀번호를 만듭니다.
그런 다음 인스턴스에서 로그아웃하고 직렬 콘솔에 연결합니다.
메시지가 나타나면 로그인 정보를 입력합니다.

다른 직렬 포트에서 로그인 설정

로그인 프롬프트는 대부분의 Linux 운영체제에서 기본으로 포트 1에서 사용 설정되어 있습니다. 하지만 포트 1은 종종 데이터 로깅으로 과부하가 걸려 다른 정보가 포트에 출력될 수 있습니다. VM에서 다음 명령어 중 하나를 실행하면 포트 2(ttyS1)와 같은 다른 포트에서 대신 로그인 프롬프트를 사용 설정하도록 선택할 수 있습니다. 직렬 포트 번호 지정 이해에서 VM에 사용할 수 있는 포트 목록을 확인할 수 있습니다.

다음 표는 직렬 콘솔 로그인 및 기본 포트로 사전 구성된 이미지 목록입니다.

운영체제	기본으로 로그인 프롬프트가 있는 포트	서비스 관리
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

Linux 운영체제의 경우 systemd를 사용합니다.

다음 재부팅까지 서비스를 일시적으로 사용 설정합니다.
```
sudo systemctl start serial-getty@ttyS1.service
```
다음 재부팅부터 서비스를 영구적으로 사용 설정합니다.
```
sudo systemctl enable serial-getty@ttyS1.service
```

upstart

Linux 운영체제의 경우 upstart를 사용합니다.

ttyS1를 반영하도록 기존 ttyS0.conf 파일을 복사 및 수정하여 새 /etc/init/ttyS1.conf 파일을 만듭니다. 예를 들면 다음과 같습니다.
- On 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가 없으므로 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

직렬 포트 번호 지정 이해

각 가상 머신 인스턴스에는 직렬 포트가 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 명령어를 전송하려면 다음 안내를 따르세요.

ENTER 키를 누릅니다.
~B(물결표시와 대문자 B)를 입력합니다.
Magic SysRq 명령어를 입력합니다.

직렬 콘솔 감사 로그 보기

Compute Engine은 인스턴스의 직렬 콘솔에서 누가 연결했고 연결 해제했는지 추적하는 감사 로그를 제공합니다. 로그를 보려면 로그 뷰어에 대한 권한이 있거나 프로젝트 뷰어 또는 편집자여야 합니다.

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
로그 탐색기로 이동
드롭다운 메뉴를 확장하고 GCE VM Instance를 선택합니다.
검색창에 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`	성공적인 연결 요청의 경우 `google.rpc.Code.OK`의 `status.code` 값은 작업이 오류 없이 완료되었음을 나타냅니다. 이 속성의 열거형 값이 `0`이므로 `status.code` 속성은 표시되지 않습니다. 하지만 `google.rpc.Code.OK`의 `status.code` 값을 검사하는 모든 코드는 예상대로 작동합니다.

연결 해제 로그

다음 표에는 연결 해제 로그와 관련된 감사 로그 속성과 값이 나와 있습니다.

속성	값
`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 키를 찾을 수 없습니다. VM 인스턴스에 대한 인증을 받았는지 확인하세요. `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 키를 찾을 수 없습니다. VM 인스턴스에 대한 인증을 받았는지 확인하세요.
google.rpc.Code.UNKNOWN: 요청에 알 수 없는 오류가 발생했습니다. gce-discussion 그룹에서 Google에 연락하거나 버그 신고 양식을 작성할 수 있습니다.

status.message 이 항목에 대해 사람이 읽을 수 있는 메시지입니다.

대화형 직렬 콘솔 액세스 사용 중지

특정 인스턴스 또는 프로젝트에서 메타데이터를 변경하여 대화형 직렬 콘솔 액세스를 사용 중지하거나 조직 정책을 설정하여 조직의 일부인 하나 이상의 프로젝트에 대한 모든 VM 인스턴스의 양방향 직렬 콘솔 액세스를 사용 중지할 수 있습니다.

특정 인스턴스 또는 프로젝트에서 대화형 직렬 콘솔 중지

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에서 정책을 설정하려면 다음 URL에 대한 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

또는 요청 본문에서 enforced 매개변수를 FALSE로 설정하는 API 요청을 생성할 수 있습니다.

{
  "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에서 프로젝트에 대화형 직렬 콘솔 액세스를 사용 설정하려면 다음 URL에 대한 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과 같이 원하는 모든 비트 전송률을 설정할 수 있지만 일반적으로 기능에서 유효한 비율을 115,200bps(~11.5kB/초)로 설정합니다. 이는 많은 공개 이미지가 직렬 콘솔에서 9,600과 같이 느린 비트 전송률로 기본 설정되어 느리게 부팅되기 때문입니다.
일부 OS 이미지는 직렬 포트에 부적절한 기본값이 있습니다. 예를 들어 CentOS 7에서 콘솔의 Enter 키에 대한 stty icrnl 기본값은 CR(^M이라고도 함)을 전송하는 것입니다. Bash 셸은 사용자가 비밀번호를 설정한 후 password: 프롬프트에서 멈춘 것처럼 보이는 이유를 궁금해할 때까지 이를 마스크할 수 있습니다.
일부 공개 이미지에는 특정 방식으로 포트에 셸을 연결할 경우 기본적으로 사용 중지되는 작업 제어 키가 있습니다. 이러한 키의 예는 ^Z 및 ^C입니다. setsid 명령어가 이를 수정할 수 있습니다. 또는 job control is disabled in this shell 메시지가 표시될 경우 방해할 수 있는 명령어를 실행하지 않도록 주의하세요.
시스템에 사용 중인 창의 크기를 알려주고 Bash 및 편집자가 이를 적절히 관리할 수 있도록 하는 것이 유용할 수 있습니다. 그렇지 않으면 Bash 또는 편집자가 사용 가능한 행 및 열 수에 대한 잘못된 가정에 기반하여 디스플레이 조작을 시도할 때 비정상적인 디스플레이 동작이 발생할 수 있습니다. stty rows Y cols X 명령어 및 stty -a 플래그를 사용하여 설정을 확인합니다. 예를 들어 창이 120자 x 60행인 경우 stty rows 60 cols 120입니다.
예를 들어 SSH를 사용하여 머신 A를 머신 B에, 그리고 머신 C(계속됨)에 연결하여 중첩된 SSH 세션을 만들고, 연결 해제 또는 직렬 브레이크 신호를 전송하고자 할 경우 물결표시(~) 명령어를 사용합니다. 올바른 SSH 클라이언트를 가져오려면 충분한 수의 물결표시 문자를 추가해야 합니다. 하나의 물결표시 다음에 오는 명령어는 머신 A의 SSH 클라이언트에서 해석하고, 2개의 연속 물결표시(Enter~~)는 머신 B의 클라이언트에서 해석하며, 이런 식으로 계속됩니다. 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

제3자 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

중단된 출력 처리

각 직렬 포트의 가장 최근 출력 1MiB은 항상 사용 가능하며 일반적으로 SSH 클라이언트는 직렬 포트에서 어떠한 출력도 놓치면 안 됩니다. 어떠한 이유로 인해 SSH 클라이언트가 일정 시간 동안 출력 수신을 중단하지만 연결은 해제하지 않고 1MiB 이상의 새 데이터를 생성한 경우 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

제3자 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와 같은 일반적인 키 조합을 통해 연결 해제되지 않습니다.

다음 단계

getSerialPortOutput API에 대해 자세히 알아보기
VM 인스턴스가 삭제된 후에도 직렬 포트 출력을 보관하고 확인하는 방법 알아보기
추가 문제 해결 팁 읽기
메타데이터 적용에 대해 자세히 알아보기
SSH 키 자세히 알아보기

직렬 콘솔을 사용한 문제 해결

시작하기 전에

Console

gcloud

REST

이 태스크에 필요한 권한

직렬 콘솔에서 대화형 액세스 사용 설정

프로젝트에서 액세스 사용 설정

콘솔

gcloud

REST

VM 인스턴스에서 액세스 사용 설정

콘솔

gcloud

REST

직렬 콘솔에 연결

콘솔

gcloud

기타 SSH 클라이언트

직렬 콘솔에서 연결 해제

로그인 프롬프트로 직렬 콘솔에 연결

시작 스크립트를 사용한 로컬 비밀번호 설정

Linux

Windows

VM에서 passwd을 사용한 로컬 비밀번호 설정

다른 직렬 포트에서 로그인 설정

systemd

upstart

sysvinit

직렬 포트 번호 지정 이해

직렬 브레이크 전송

직렬 콘솔 감사 로그 보기

대화형 직렬 콘솔 액세스 사용 중지

특정 인스턴스 또는 프로젝트에서 대화형 직렬 콘솔 중지

조직 정책을 통해 대화형 직렬 콘솔 액세스 중지

gcloud

REST

프로젝트 수준에서 조직 정책 설정

gcloud

REST

도움말 및 유용한 정보

고급 옵션

최대 연결 제어

재생 옵션 설정

중단된 출력 처리

exit 또는 logout 명령어를 사용하여 연결 해제 사용 설정

다음 단계

VM에서 `passwd`을 사용한 로컬 비밀번호 설정