alpacon exec

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

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

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

옵션 (Options)#

  -h, --help                    exec 명령어에 대한 도움말 출력
  -u, --username string         사용자 이름 지정
  -g, --groupname string        그룹 이름 지정
      --env=KEY[=VALUE]         'KEY'를 'VALUE'로 설정하거나, 현재 셸의 환경 변수에서 'KEY' 값을 읽음 (반복 가능)
      --file string             명령줄 대신 서버의 이 경로에 있는 스크립트를 검증된 파일로 실행
      --file-from string        --file 경로 대신 이 로컬 경로에서 스크립트 내용을 읽음
      --interpreter string      --file로 지정한 스크립트 실행에 사용할 인터프리터 (기본값 "/bin/bash")
      --reuse-days int          --file 승인을 재사용할 수 있는 기간을 1~366일로 요청
      --work-session string     이 명령을 작업 세션에 연결 ('work-session use' 설정보다 우선)
      --detach                  완료를 기다리지 않고 명령 제출 후 즉시 반환
      --wait                    검토자가 sudo 요청을 승인할 때까지 재시도 (타임아웃 시 종료)
      --wait-approval string    --wait와 동일하지만 대기 시간을 직접 지정 (예: 30m, 기본값 5m); --wait를 암시적으로 포함
      --output string           출력 형식: table 또는 json (기본값 "table")

하위 명령어#

alpacon exec ls             최근 원격 명령 실행 이력 조회
alpacon exec logs JOB_ID    --detach로 제출한 명령의 결과 조회

exec ls#

최근 원격 명령 실행 이력을 최신순으로 보여줍니다. 기존 alpacon event 목록 기능이 이 명령어로 옮겨왔고, 플래그는 그대로입니다.

alpacon exec ls [flags]

별칭: ls, list

  -h, --help            ls 명령어에 대한 도움말 출력
  -s, --server string   서버 이름으로 필터링
  -t, --tail int        최신순으로 표시할 명령 항목 수 (기본값 25)
  -u, --user string     요청한 사용자로 필터링

최근 25건 조회:

alpacon exec ls

서버와 사용자로 좁혀서 조회:

alpacon exec ls --tail 10 --server my-server --user admin

--tail은 지정한 개수만큼 항목을 반환합니다. 예를 들어 --tail 250은 항목 250개를 반환합니다.

예제#

서버에서 명령 실행:

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

원격 명령에 환경 변수 전달:

alpacon exec --env="KEY1=VALUE1" --env="KEY2=VALUE2" my-server -- printenv KEY1

명령줄이나 감사 로그에 남기지 않고 현재 셸에서 시크릿 값 읽기:

alpacon exec --env="PGPASSWORD" db-server -- psql -h localhost -U app -c 'SELECT 1'

그래도 명령줄에 시크릿이 남아 있으면(시크릿 성격의 KEY=VALUE, -pSecret123처럼 패스워드가 포함된 플래그, 패스워드가 포함된 connection string 등) 서버가 실행 전에 command_inline_credential로 명령을 거부합니다. 시크릿은 --env로 옮기세요.

검증된 파일 실행#

--file을 사용하면 명령줄을 직접 입력하지 않고 대상 서버에 이미 있는 스크립트를 실행할 수 있습니다. 검토자는 실행할 스크립트의 바이트를 확인합니다. 플랫폼은 검토자가 확인한 바이트와 서버에서 실행할 바이트가 같도록 보장합니다.

--file PATH에는 대상 서버에 있는 스크립트의 절대 경로를 지정합니다. CLI는 기본적으로 로컬에서도 서버와 같은 경로에 있는 스크립트 내용을 읽습니다. 로컬 파일의 경로가 다르면 --file-from LOCAL_PATH로 지정합니다. 어느 쪽이든 로컬 사본이 서버의 파일과 바이트 단위로 동일해야 하며, 다르면 에이전트가 실행을 거부합니다. --interpreter PATH는 스크립트를 실행할 인터프리터를 지정하며(기본값 /bin/bash), 반드시 절대 경로여야 합니다. 스크립트 인자는 -- 뒤에 붙입니다. --file을 사용할 때는 명령줄이나 --env를 함께 지정할 수 없습니다.

승인은 지정한 서버에서 지정한 계정과 인자로 실행하는 바이트에만 적용됩니다. 파일 자체를 포괄적으로 승인하는 것은 아닙니다. 검토자는 이를 상시 승인(standing)으로 지정할 수 있습니다. 바이트가 바뀌지 않으면 재실행할 때 다시 검토받지 않아도 되지만, 하나라도 바뀌면 다시 검토해야 합니다.

--reuse-days N으로 상시 승인을 1~366일 동안 재사용하도록 요청할 수 있습니다. 승인자가 재사용 허용 여부를 결정합니다. 워크스페이스의 파일 실행 승인 허용 기간이 N일보다 짧으면 서버가 요청을 거부하고, CLI는 더 짧은 --reuse-days 값으로 다시 제출하라고 안내합니다. 이 플래그를 생략하면 상시 승인은 워크스페이스의 허용 기간까지 유효하며, 기간 제한이 없으면 무기한 유효합니다. --reuse-days는 --file과 함께 사용해야 합니다.

검토자는 스크립트 내용과 함께 인자도 확인하므로, 시크릿을 인자나 스크립트 자체에 넣지 마세요. 대신 스크립트가 실행 시점에 서버의 환경 변수나 파일에서 시크릿을 읽도록 하세요. 스크립트에 자격 증명이 포함되면 명령줄에 포함된 경우와 마찬가지로 서버가 실행을 거부합니다. 스크립트 크기는 64 KB로 제한됩니다.

검토자가 내용을 확인할 수 있는 스크립트를 서버에서 바이트 단위로 검증해 실행합니다.

alpacon exec --file /opt/deploy.sh root@prod-web -- --fast

로컬 사본을 다른 경로에서 읽고 인터프리터를 지정합니다.

alpacon exec --file /opt/deploy.sh --file-from ./deploy.sh --interpreter /bin/sh prod-web

승인을 30일 동안 재사용하도록 요청합니다.

alpacon exec --file /opt/deploy.sh --reuse-days 30 root@prod-web -- --fast

비동기 실행#

--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 관리를 참고하세요.