SSH Gateway

SSH Gateway를 경유하여 원격 서버에 명령을 실행하고 파일을 전송하는 CLI 도구입니다.

기능

• SSH Gateway를 경유한 원격 서버 명령 실행 (실시간 스트리밍 출력)
• 여러 호스트 병렬 실행 (Gateway 인증 1회 + 내부 fan-out)
• Gateway 경유 SCP 파일 업로드/다운로드 (바이너리 무결성 보장)
• Kerberos 인증 (kinit) 지원
• 원격 명령어 타임아웃으로 프로세스 hang 방지
• 호스트 허용 목록으로 접속 제한

설치

npm install
npm run build
npm link        # gw-ssh 명령어 글로벌 등록

설정

config.json 생성

{
  "gatewayConnection": "[email protected]:22",
  "gatewayPassword": "your-password",
  "kinitPassword": "your-kerberos-password",
  "allowedHosts": ["server1", "server2"],
  "commandTimeoutSec": 300,
  "serverInfo": {
    "user": "default-ssh-user",
    "logPaths": {
      "app": "/var/log/app"
    }
  }
}

설정 파일 경로 지정

# 방법 1: 환경변수 (~/.zshrc 등에 추가)
export CONFIG_FILE=/path/to/config.json

# 방법 2: --config 옵션
gw-ssh -c /path/to/config.json <command>

설정 옵션

키	설명	기본값
gatewayConnection	Gateway SSH 연결 (user@host:port)	필수
gatewayPassword	Gateway SSH 비밀번호	필수
kinitPassword	Kerberos 인증 비밀번호 (미설정 시 kinit 생략)	-
allowedHosts	접속 허용 호스트 목록	[] (모두 허용)
commandTimeoutSec	원격 명령어 타임아웃 (초). GNU timeout으로 래핑	300
serverInfo	서버 메타 정보 (user, logPaths 등)	{}

환경변수

변수	설명
CONFIG_FILE	config.json 파일 경로
DEBUG	디버그 로그 활성화 (true/false)

사용법

명령 실행

gw-ssh exec <host> <command> [-u user] [-j jobs] [--buffered]

# 단일 호스트
gw-ssh exec server1 "hostname"
gw-ssh exec server1 "uptime" -u appuser

# 로그 조회
gw-ssh exec server1 "tail -100 /var/log/app/app.log"
gw-ssh exec server1 "grep ERROR /var/log/app/app.log | tail -20"

-u를 생략하면 serverInfo.user 값을 사용합니다.

여러 호스트 병렬 실행

<host> 에 쉼표로 구분한 CSV 를 넘기면 자동으로 병렬 모드로 동작합니다. Gateway 인증/Kerberos ticket 은 1회만 수행되고, gateway→target 구간에서 fan-out 됩니다.

# 3개 호스트에서 동시에 실행 (기본 동시성 5)
gw-ssh exec server1,server2,server3 "hostname && uptime"
# [server1] server1
# [server1]  15:02:31 up 42 days, ...
# [server2] server2
# [server2]  15:02:31 up 12 days, ...
# [server3] server3
# [server3]  15:02:31 up  7 days, ...
# ✓ 3/3 성공

# 동시성 제한 변경 (gateway 부하 고려해 3~10 권장)
gw-ssh exec h1,h2,h3,h4,h5,h6,h7,h8 "uptime" -j 10

# 호스트별로 출력을 모아 순서대로 표시 (스트리밍 대신 버퍼드 모드)
gw-ssh exec h1,h2 "cat /etc/hostname" --buffered

일부 호스트만 실패하면 종료 코드 1 로 실패 요약이 stderr 에 출력됩니다.

파일 업로드

gw-ssh upload <host> <remotePath> [options] [-u user] [-j jobs]

# 텍스트 내용 직접 업로드
gw-ssh upload server1 /tmp/hello.txt --content "hello world"

# 로컬 파일 업로드 (바이너리 포함 - gzip, zip, 실행파일 등)
gw-ssh upload server1 /tmp/app.tar.gz --file ./app.tar.gz

# 여러 호스트에 같은 파일 동시 배포 (CSV 지정 시 병렬 모드)
gw-ssh upload server1,server2,server3 /tmp/app.tar.gz --file ./app.tar.gz

다중 호스트 업로드 시 로컬→gateway 전송은 1회, gateway→각 target 은 병렬로 fan-out. 파일이 크거나 호스트 수가 많을수록 로컬 대역폭 절감 효과가 큼.

파일 다운로드

gw-ssh download <host> <remotePath> [options] [-u user] [-j jobs]

# 표준 출력으로 내용 확인
gw-ssh download server1 /etc/hosts

# 로컬 파일로 저장
gw-ssh download server1 /etc/hosts -o ./downloaded-hosts.txt

# 바이너리 파일도 무결성 유지 (gzip, zip, 실행파일 등)
gw-ssh download server1 /var/app/release.tar.gz -o ~/Downloads/release.tar.gz

# 여러 호스트에서 동시에 다운로드 — -o 에 디렉토리 지정, 파일명 앞에 호스트 접두
gw-ssh download server1,server2 /var/log/app.log -o ~/Downloads/
# → ~/Downloads/server1-app.log
# → ~/Downloads/server2-app.log

-o 는 단일 호스트일 때 파일 경로, 다중 호스트일 때 이미 존재하는 디렉토리 경로여야 합니다.

다중 호스트 다운로드에서 일부 호스트만 실패한 경우, 성공한 호스트의 파일은 -o 디렉토리에 그대로 남습니다. 전체 rollback 이 필요하면 수동 삭제.

설정 확인

gw-ssh config

연결 테스트

gw-ssh status

보안

• config.json에 민감한 정보(비밀번호)가 포함되므로 git에 커밋하지 마세요
• allowedHosts로 접속 가능한 서버를 제한합니다
• Base64 인코딩 + 셸 인젝션 방지 패턴으로 명령어 안전성 확보
• 예외 발생 시에도 SSH 세션 자동 정리

라이선스

MIT