alpacon exec

대화형 터미널 세션을 열지 않고 원격 서버에서 직접 명령을 실행합니다. 일회성 명령, 자동화 스크립트 실행 또는 서버에서 출력을 가져오는 데 유용합니다.

alpacon exec [flags] [USER@]SERVER [--] COMMAND...

모든 플래그는 서버 이름 앞에 위치해야 하며, 서버 이름 이후는 전부 원격 명령으로 처리됩니다. --를 사용하면 원격 명령을 명시적으로 구분할 수 있어, 원격 명령의 플래그(-U, -d 등)가 alpacon 플래그로 해석되지 않습니다.

옵션 (Options)

  -h, --help                    exec 명령어에 대한 도움말 출력
  -u, --username string         사용자 이름 지정
  -g, --groupname string        그룹 이름 지정
      --work-session string     이 명령을 작업 세션에 연결 ('work-session use' 설정보다 우선)
      --detach                  완료를 기다리지 않고 명령 제출 후 즉시 반환
      --wait                    검토자가 sudo 요청을 승인할 때까지 재시도 (타임아웃 시 종료)
      --output string           출력 형식: table 또는 json (기본값 "table")

하위 명령어

alpacon exec logs JOB_ID    --detach로 제출한 명령의 결과 조회

예제

서버에서 명령 실행:

alpacon exec my-server ls -la /var/log

특정 사용자로 실행:

alpacon exec admin@my-server cat /etc/hostname
alpacon exec -u admin my-server cat /etc/hostname

특정 그룹으로 실행:

alpacon exec -g developers my-server whoami

--를 사용해 원격 명령에 플래그 전달:

alpacon exec root@db-server -- docker exec postgres psql -U myproject -d myproject
alpacon exec my-server -- grep -r "pattern" /var/log

여러 명령 실행(따옴표는 &&가 로컬 셸에서 해석되는 것을 방지합니다):

alpacon exec my-server -- "df -h && free -m"

셸 메타문자(;, |, &, $)는 먼저 로컬 셸에서 해석되므로, 서버로 보내려면 원격 명령을 따옴표로 감싸야 합니다. 전달된 메타문자는 원격 셸에서 다시 해석되며, 리터럴 문자로 전달하려면 원격 셸도 해석하지 않도록 안쪽에 따옴표를 한 번 더 사용하세요:

alpacon exec my-server -- "echo 'hello;world'"

특정 작업 세션에 명령 연결:

alpacon exec --work-session 11111111-2222-3333-4444-555555555555 my-server -- df -h

비동기 실행

--detach를 사용하면 명령 완료를 기다리지 않고 제출 후 즉시 반환합니다. CLI는 Job submitted: JOB_ID를 stdout에 출력합니다(--output json 사용 시 {"job_id": "..."}).

alpacon exec --detach web-server -- apt-get update

이후 alpacon exec logs로 결과를 조회합니다:

alpacon exec logs a1b2c3d4-5678-abcd-ef01-234567890abc

JOB_ID는 UUID여야 합니다. 명령이 아직 실행 중이면 현재 상태를 출력하고 종료 코드 0으로 종료됩니다. 나중에 다시 실행해 완료 여부를 확인하세요.

종료 코드 (Exit codes)

원격 명령의 종료 코드가 그대로 전파되므로, alpacon exec는 서버에서 실행된 명령과 동일한 코드로 종료됩니다.

종료 코드 3은 작업 세션 게이트에 의해 명령이 거부되었음을 의미합니다(예: 활성 세션 없음, 세션에 대상 서버 미포함). --output json 사용 시 기계가 읽을 수 있는 진단이 stderr에 출력됩니다. 에러 코드는 게이트 에러를 참고하세요.

종료 코드 4는 sudo 명령이 승인 대기 상태임을 의미합니다. Alpacon 콘솔에서 승인한 후 다시 실행하거나, --wait를 사용해 승인될 때까지 대기하세요. --output json 사용 시 CLI는 stdout에 {"status": "pending_approval", ...}를 출력합니다.

작업 세션 요구 사항

브라우저 로그인으로 인증한 경우, alpacon exec를 실행하려면 command 기능을 포함한 활성 작업 세션이 필요합니다. 토큰 인증(API 토큰 또는 서비스 토큰)은 이 요구 사항을 우회합니다.

연결할 세션은 --work-session 플래그, ALPACON_WORK_SESSION 환경 변수, alpacon work-session use로 지정한 활성 세션 순으로 결정됩니다.

MFA 인증

시스템 계정으로 명령을 실행할 때(예: root@my-server), 워크스페이스 인증 설정에 따라 추가 MFA 인증이 필요할 수 있습니다. CLI MFA 흐름은 alpacon websh와 동일합니다. 자세한 내용은 websh MFA 인증을 참고하세요.

API 토큰 ACL

API 토큰을 사용할 때, 실행하려는 각 명령에 대한 ACL 규칙이 토큰에 있어야 합니다. 대화형 websh 세션은 명령 ACL의 제한을 받지 않지만, exec 명령은 항상 매칭되는 ACL 규칙이 필요합니다.

# Allow the commands this token can run on servers
alpacon token acl command add my-token --command="df *"
alpacon token acl command add my-token --command="cat /etc/hostname"

와일드카드 패턴에 대한 자세한 내용은 토큰 ACL 관리를 참고하세요.

최종 수정: