ssh

ssh는 암호화된 SSH 연결로 원격 시스템에 로그인하거나 명령을 실행하고, TCP·Unix socket·X11 연결을 전달하는 OpenSSH 클라이언트다.

접속 대상은 보통 [user@]hostname으로 지정한다. 반복해서 쓰는 사용자, 포트, 키, jump host 설정은 ~/.ssh/config에 두면 명령을 짧게 유지할 수 있다.

OpenSSH 클라이언트 패키지만 설치한다.

sudo apt update
sudo apt install openssh-client

sudo dnf install openssh-clients

macOS에는 시스템 SSH 클라이언트가 포함되어 있다. Homebrew 버전이 별도로 필요하면 공식 openssh formula를 설치한다.

brew install openssh

Windows 10 build 1809 이상과 지원되는 Windows Server에서는 OpenSSH Client를 Optional Feature로 설치할 수 있다. 관리자 PowerShell에서 실행한다.

Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH.Client*'
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

Microsoft의 안정 OpenSSH 설치 가이드는 winget 대신 Windows Optional Feature 방식을 안내한다. 검색되는 beta 패키지를 일반 클라이언트 설치 경로로 대체하지 않는다.

ssh -V

ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface]
    [-b bind_address] [-c cipher_spec] [-D [bind_address:]port]
    [-E log_file] [-e escape_char] [-F configfile] [-I pkcs11]
    [-i identity_file] [-J destination] [-L address]
    [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option]
    [-P tag] [-p port] [-R address] [-S ctl_path]
    [-W host:port] [-w local_tun[:remote_tun]]
    destination [command [argument ...]]
ssh -Q query_option

• ssh [<switches>…] destination [command [argument …]]
• destination: [user@]hostname 또는 ssh://[user@]hostname[:port] 형식의 접속 대상
• command [argument …]: 로그인 shell 대신 원격에서 실행할 명령과 인자

• -p port: 원격 SSH server port 지정
• -l login_name: 로그인 사용자 지정
• -i identity_file: public key 인증에 사용할 identity file 지정
• -F configfile: 기본 사용자 config 대신 별도 client config 사용
• -o option: ssh_config keyword를 명령행에서 지정
• -J destination: jump host를 거쳐 최종 대상에 연결
• -4, -6: IPv4 또는 IPv6만 사용

• -t: pseudo-terminal 강제 할당. 여러 번 쓰면 local terminal이 없어도 강제
• -T: pseudo-terminal 할당 비활성화
• -N: 원격 명령을 실행하지 않음. port forwarding 전용 연결에 유용
• -n: standard input을 /dev/null로 연결
• -f: 명령 실행 직전에 background로 전환
• -v: 진단 로그를 자세히 출력. 최대 -vvv
• -q: warning과 diagnostic message를 줄임
• -C: compression 요청
• -A: authentication agent forwarding 활성화
• -X, -Y: X11 forwarding 활성화

• -L [bind_address:]port:host:hostport: local listener로 들어온 연결을 SSH server 쪽에서 host:hostport로 연결
• -R [bind_address:]port:host:hostport: SSH server의 remote listener로 들어온 연결을 client 쪽에서 host:hostport로 연결
• -D [bind_address:]port: local dynamic application-level port forwarding. SOCKS4/SOCKS5 proxy처럼 동작
• -W host:port: client standard input/output을 SSH channel을 통해 host:port로 전달
• -w local_tun[:remote_tun]: client/server의 tunnel device forwarding 요청

• -G: Host와 Match 평가 후 최종 client configuration 출력
• -Q query_option: 지원하는 cipher, key, MAC 등 algorithm 목록 질의
• -O ctl_cmd: multiplexing master process에 check, forward, cancel, exit, stop 등의 control command 전달
• -S ctl_path: connection sharing control socket 경로 지정

# 현재 사용자 이름으로 접속
ssh server.example.com
 
# 사용자와 port 지정
ssh -p 2222 deploy@server.example.com
 
# 별도 identity file 사용
ssh -i ~/.ssh/id_ed25519_work deploy@server.example.com
 
# 원격 명령 실행
ssh deploy@server.example.com uname -a

ssh -J ops@bastion.example.com deploy@app.internal.example

같은 경로를 반복해서 사용한다면 ~/.ssh/config에 ProxyJump를 지정한다.

로컬 127.0.0.1:8080 접속을 SSH server가 접근할 수 있는 db.internal.example:80으로 전달한다.

ssh -N -L 127.0.0.1:8080:db.internal.example:80 user@bastion.example.com

기존에 사용하던 일반 표기:

ssh -L PORT1:HOSTNAME:PORT2 user@hostB

여기서 PORT1은 local listening port이고, HOSTNAME:PORT2는 hostB 쪽에서 연결할 목적지다.

SSH server의 loopback 8022 접속을 local network의 service.internal.example:22로 전달한다.

ssh -N -R 127.0.0.1:8022:service.internal.example:22 user@gateway.example.com

기존에 사용하던 일반 표기:

ssh -R local_port:target_host:target_port user@server

이 표기의 local_port는 실제로 SSH server 쪽에서 listen하는 remote port이므로, 새 문서에서는 remote_port로 부르는 편이 명확하다.

local loopback에 SOCKS proxy를 열고 SSH server를 통해 목적지에 연결한다.

ssh -N -D 127.0.0.1:1080 user@gateway.example.com

기존 ssh -N -D port 형식도 동작하지만, 의도하지 않은 외부 노출을 피하려면 127.0.0.1:port처럼 bind address를 명시한다.

# 별칭에 적용될 최종 설정 확인
ssh -G production.example.com
 
# 지원 public key algorithm 확인
ssh -Q key
 
# 자세한 연결 진단
ssh -vvv user@server.example.com

• 사용자별 설정: ~/.ssh/config
• 시스템 전역 설정: /etc/ssh/ssh_config
• Windows 사용자 설정: %USERPROFILE%\.ssh\config
• Windows 시스템 전역 설정: %PROGRAMDATA%\ssh\ssh_config
• 작성법, precedence, ProxyJump, keepalive, connection multiplexing: ssh_config / ~/.ssh/config

• private key에는 passphrase를 설정하고, 필요하면 ssh-agent로 반복 입력을 줄인다.
• -A agent forwarding은 원격 host가 agent socket에 접근할 수 있게 한다. 신뢰하지 않는 중간 host에서는 피하고, 가능하면 -J/ProxyJump를 사용한다.
• host key 변경 경고가 나오면 서버 재설치나 key rotation 여부를 먼저 확인한다. 확인 없이 known_hosts 항목을 삭제하지 않는다.
• remote command에 local 변수나 신뢰할 수 없는 문자열을 결합하면 local shell과 remote shell의 quoting이 겹칠 수 있다. 자동화에서는 인자를 제한하고 quoting을 검토한다.

• Connection timed out: DNS, route, 방화벽, VPN, port 번호를 확인
• Connection refused: 대상 host에는 도달했지만 해당 port에서 sshd가 listen 중인지 확인
• Permission denied (publickey): -vvv로 선택된 사용자와 identity file을 확인하고, server의 authorized_keys와 권한을 점검
• REMOTE HOST IDENTIFICATION HAS CHANGED: 새 host key fingerprint를 별도 채널로 검증한 뒤 ssh-keygen -R로 오래된 항목을 정리
• config가 예상과 다르면 ssh -G destination으로 최종 해석 결과 확인
• forwarding이 열리지 않으면 local port 충돌, server의 AllowTcpForwarding/PermitOpen/GatewayPorts, 방화벽을 확인

• 배포판과 운영체제가 제공하는 OpenSSH version에 따라 지원 option과 기본 algorithm이 다르다.
• 최신 upstream synopsis의 -P tag처럼 오래된 client에 없는 option이 있을 수 있다. 배포 자동화 전 대상 host의 ssh -V와 option 지원 여부를 확인한다.
• 오래된 server가 ssh-rsa 또는 구형 key exchange만 제공할 때 client가 연결을 거부할 수 있다. 전역으로 약한 algorithm을 재활성화하지 말고, 교체 계획이 있는 특정 Host block에만 제한적으로 적용한다.
• Windows OpenSSH는 기본 경로와 agent/service 관리 방식이 Unix 계열과 다르지만, 일반적인 ssh 접속 option과 config keyword는 대부분 공통이다.

아래 내용은 이 저장소 작업 환경의 OpenSSH_8.0p1에서 ssh -?로 확인한 usage다. 최신 upstream manual의 synopsis와 차이가 있을 수 있다.

ssh -?

unknown option -- ?
usage: ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface]
           [-b bind_address] [-c cipher_spec] [-D [bind_address:]port]
           [-E log_file] [-e escape_char] [-F configfile] [-I pkcs11]
           [-i identity_file] [-J [user@]host[:port]] [-L address]
           [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]
           [-Q query_option] [-R address] [-S ctl_path] [-W host:port]
           [-w local_tun[:remote_tun]] destination [command]

• ssh_config / ~/.ssh/config
• ssh-keygen
• ssh-copy-id
• ssh-add
• sshd_config
• Windows SSH
• OpenBSD ssh(1) manual
• OpenSSH Portable
• Install OpenSSH for Windows
• Ubuntu openssh-client package
• Fedora openssh-clients package
• Homebrew openssh formula

• codex:: 2026-07-27 Added current installation guidance, connection and forwarding options, safe examples, configuration links, diagnostics, compatibility notes, and verified local help while preserving existing tunnel command records.