ssh_config / ~/.ssh/config

OpenSSH 클라이언트가 접속 대상별 기본값을 읽는 사용자 설정 파일이다.

ssh는 명령행 옵션, 사용자 설정 파일 ~/.ssh/config, 시스템 전역 설정 파일 /etc/ssh/ssh_config 순서로 값을 읽고, 각 파라미터는 먼저 얻은 값을 우선 사용한다.

• Linux / macOS 사용자 설정: ~/.ssh/config
• Linux / macOS 시스템 전역 설정: /etc/ssh/ssh_config
• Windows OpenSSH 사용자 설정: C:\Users\<User>\.ssh\config
• Windows OpenSSH 시스템 전역 설정: C:\ProgramData\ssh\ssh_config

Host pattern
    Keyword value
    Keyword value
 
Host another-host
    Keyword value

• Host: 아래 선언들을 특정 별칭 또는 패턴에만 적용
• #: 주석
• 공백 또는 = 형식으로 Keyword value 지정 가능
• 더 구체적인 Host 블록을 먼저 두고, Host * 같은 전역 기본값은 뒤쪽에 두는 편이 안전하다

• Host: 접속 별칭 또는 패턴. 예: Host github, Host *.internal
• HostName: 실제 접속할 DNS 이름 또는 IP
• User: 기본 로그인 사용자
• Port: 기본 SSH 포트
• IdentityFile: 사용할 개인 키 경로
• ServerAliveInterval: keepalive 패킷 전송 간격(초)
• ServerAliveCountMax: keepalive 실패 허용 횟수
• Include: 별도 설정 파일 포함

connection multiplexing은 첫 번째 SSH 연결을 재사용해 후속 접속 속도를 높이고 인증 반복을 줄이는 방식이다.

• ControlMaster
  • yes: 현재 세션이 master가 되어 control socket을 열고 다른 세션이 재사용 가능
  • no: 재사용하지 않음. 기본값
  • auto: 기존 master가 있으면 재사용하고, 없으면 일반 연결
  • ask, autoask: 재사용 전 ssh-askpass 확인
• ControlPath
  • master 연결을 찾거나 여는 control socket 경로
  • 충돌 방지를 위해 최소한 %h, %p, %r 또는 %C를 포함하는 편이 좋다
  • 다른 사용자가 쓰기 가능한 디렉터리는 피하는 편이 안전하다
• ControlPersist
  • master 연결을 백그라운드에 얼마나 유지할지 결정
  • no: 첫 세션 종료 시 같이 종료
  • yes 또는 0: 명시적으로 닫을 때까지 계속 유지
  • 10m, 1h 같은 시간값: 유휴 상태가 해당 시간에 도달하면 자동 종료

ControlPath에서 자주 쓰는 토큰:

• %h: 원격 호스트명
• %p: 원격 포트
• %r: 원격 사용자
• %C: %l%h%p%r 기반 해시. 경로가 길어지기 쉬운 환경에서 유용
• %%: 문자 % 자체

Host web-prod
    HostName 203.0.113.10
    User deploy
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 30
    ServerAliveCountMax 3

Host *.corp
    User ops
    IdentityFile ~/.ssh/id_ed25519_work
    ControlMaster auto
    ControlPath ~/.ssh/controlmasters/%C
    ControlPersist 10m

Host win-jump
    HostName jump.example.com
    User admin
    Port 22
    IdentityFile C:\Users\Alice\.ssh\id_ed25519
    ServerAliveInterval 30
    ServerAliveCountMax 3

Host gitlab-work
    HostName gitlab.example.com
    User git
    Port 2222
    IdentityFile C:\Users\Alice\.ssh\id_work_ed25519
 
Host bastion
    HostName 198.51.100.20
    User ec2-user

• Linux / macOS에서는 mkdir -p ~/.ssh/controlmasters && chmod 700 ~/.ssh/controlmasters처럼 control socket 디렉터리를 미리 만드는 편이 관리하기 쉽다.
• Windows에서도 사용자 설정 경로는 보통 %USERPROFILE%\.ssh\config에 대응한다.
• native Windows OpenSSH에서 multiplexing 동작 여부는 사용 중인 OpenSSH 빌드와 환경에 따라 차이가 있을 수 있으므로, 우선 기본 파라미터부터 적용하고 ControlMaster 계열은 실제 접속으로 검증하는 편이 안전하다.

• 별칭이 적용되지 않으면 ssh -G alias로 최종 해석 결과를 확인
• 특정 호스트 블록보다 앞쪽에서 같은 파라미터가 이미 설정되면 뒤쪽 값이 적용되지 않을 수 있음
• Bad owner or permissions 오류가 나면 ~/.ssh 및 개인 키 권한을 점검
• ControlPath가 너무 길면 %C를 사용해 경로를 줄이는 편이 낫다
• multiplexing 연결 종료는 ssh -O exit alias로 수행 가능

man ssh_config

SSH client configuration files
 
1. command-line options
2. user's configuration file (~/.ssh/config)
3. system-wide configuration file (/etc/ssh/ssh_config)
 
For each parameter, the first obtained value will be used.
 
ControlMaster
    Enables the sharing of multiple sessions over a single network connection.
 
ControlPath
    Specify the path to the control socket used for connection sharing.
 
ControlPersist
    Specifies that the master connection should remain open in the background
    after the initial client connection has been closed.

• ssh
• ssh-keygen
• ssh-add
• sshd_config

• codex:: 2026-07-02 Added ~/.ssh/config reference with ControlMaster, ControlPath, ControlPersist, and Windows/Linux examples.