SSH Agent 사용법

SSH Agent는
사용자 로그인 session(세션) 동안 ssh 키에 대한 암호를 유지하여
사용자가 한번만 암호를 입력하게 해줌.

https://levelup.gitconnected.com/ssh-agent-explained-cf947034e63d

macOS SSH Agent 특징

• macOS는 SSH Agent가 기본적으로 launchd를 통해 자동 실행 됨
• Keychain과 통합되어 있어 다른 OS보다 편리한 특성을 가짐: --apple-use-keychain 를 통한 macOS 전용기능

SSH Agent는 사용자 로그인 세션 동안 ssh 키에 대한 암호를 유지하여 사용자가 한번만 암호를 입력하게 해줌.

• session (로그인~로그오프) 동안 password caching.
• 한번은 입력해줘야 함.

macOS의 Keychain 은 이를 더욱 확장해서, 다른 세션에서도 암호를 유지해줌

• 재부팅/재로그인 해도 유지.
• 편리함과 보안은 trade-off 관계임.

---

참고: Ubuntu

SSH Agent를 기본으로 가지고 있으나, 자동실행되지 않음.

• 수동으로 eval "$(ssh-agent -s)"를 실행해야 함 (~/.zshrc` 등을 통해 세션 시작시 자동으로 동작하게 하는게 일반적)
• Keychain 없음.

---

참고: Windows

Windows10 이후 OpenSSH가 기본으로 포함됨.

• SSH Agent는 Windows 서비스 형태로 동작: ssh-agent
• 서비스 시작하려면 관리자 권한 필요.
• 서비스에서 자동시작으로 설정되면 자동으로 시작됨.

---

1. SSH Agent 기본 확인

# SSH Agent 실행 여부 확인
echo $SSH_AUTH_SOCK

echo $SSH_AGENT_PID


# Agent에 등록된 키 확인
ssh-add -l

• echo $SSH_AUTH_SOCK
  • 최신 macOS에선 launchd 를 통해 SSH Agent가 자동동작함.
    • /private/tmp/com.apple.launchd.E3VaEHPZOu/Listener와 같은 출력.
    • com.apple.launchd를 위에서도 확인 가능.
  • Ubuntu의 경우 eval $(ssh-agent -s)를 수행하고 난 이후라면
    • /tmp/ssh-XXX/agent.12345 와 같은 출력이 나옴.
• echo $SSH_AGENT_PID
  • 최신 macOS에선 launchd 를 통해 SSH Agent가 자동동작함.
    • 때문에 아무 것도 출력되지 않음 (SSH Agent를 단독으로 수동 실행시켜야 출력됨)
  • Ubuntu의 경우 eval $(ssh-agent -s)를 수행하고 난 이후라면
    • 12345 와 같은 PID (Process ID)가 출력됨.
• SSH Agent에 등록된 키가 없을 경우 The agent has no identities.로 보임.
  • macOS에선 Keychain을 사용할 경우, 매번 키 등록이 필요 없음 (키와 패스워드 모두 유지).
  • Ubuntu등의 Linux에선 다른 세션에선 키 추가해야함.
  • 등록된 키가 있으면 256 SHA256:xxx... ~/.ssh/id_ed25519 (ED25519) 등의 출력.
  • 만약 SSH Agent가 실행되고 있지 않다면 Could not open a connection to your authentication agent. 을 확인할 수 있음.

---

참고: Windows

cmd prompt에서 다음과 같이 확인 가능 (서비스가 실행된 이후)

echo %SSH_AUTH_SOCK%
\\.\pipe\openssh-ssh-agent

echo %SSH_AGENT_PID%
(비어있음 - 서비스로 관리)

ssh-add -l
The agent has no identities.  # 수동으로 키 추가 필요

 

위의 명령어의 결과가 %~% 로 그대로 출력되는 경우 제대로 수행되지 않음을 의미함.

다음으로 확인할 수 있으며 다음은 ssh-agent가 제대로 실행되지 않음을 의미함

$ sc query ssh-agent
SERVICE_NAME: ssh-agent
        종류               : 10  WIN32_OWN_PROCESS
        상태              : 1  STOPPED
        WIN32_EXIT_CODE    : 1077  (0x435)
        SERVICE_EXIT_CODE  : 0  (0x0)
        검사점         : 0x0
        WAIT_HINT          : 0x0

---

2. SSH 키를 Agent에 추가

2-1. 기본 추가

# 키를 Agent에 추가
ssh-add ~/.ssh/id_ed25519
ssh-add ~/.ssh/id_rsa

# 모든 기본 키 자동 추가 
ssh-add

• SSH Agent를 사용할 키만 등록하는 것을 추천함.

ssh-add는 다음의 기본 키들만을 자동으로 추가함:

• ~/.ssh/id_rsa
• ~/.ssh/id_dsa
• ~/.ssh/id_ecdsa
• ~/.ssh/id_ed25519
• ~/.ssh/id_xmss

이 외의 다른 이름의 키는 직접 명시적으로 추가해야 함.

---

참고: Windows

다음의 두가지 중 하나로 처리함.

# Windows에서 경로 표기 (두 방법 모두 가능)
ssh-add %USERPROFILE%\.ssh\id_ed25519
ssh-add ~/.ssh/id_ed25519

---

2-2. macOS Keychain에 저장 (권장)

macOS에서는 다음과 같이 Keychain에 키를 추가하면 세션 간에도 키가 유지됨 (매우 편리)

# Keychain에 저장하여 재부팅 후에도 유지
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
ssh-add --apple-use-keychain ~/.ssh/id_rsa

---

3. SSH Config로 자동 로드 설정

SSH Config(~/.ssh/config)는 SSH 클라이언트의 설정 파일임

• 각 호스트별로 사용할 키 파일, 사용자명, 포트 등의 연결 옵션을 미리 정의할 수 있음
• 참고로 Windows의 경우엔 %USERPROFILE%\.ssh\config에 있음.

이 파일에서 SSH Agent 관련 설정(AddKeysToAgent, UseKeychain 등)을 지정할 경우,
SSH 연결시 자동으로 키가 Agent에 추가되고 Keychain에 저장됨.

# SSH config 파일 편집
vi ~/.ssh/config
# nano ~/.ssh/config # vim이 없을 경우.
# notepad %USERPROFILE%\.ssh\config # Windows의 경우.

 

기본 자동 로드 설정:

Host *
    AddKeysToAgent yes
    UseKeychain yes    # macOS에서만 사용가능.
    IdentitiesOnly yes

 

위는 모든 Host(Host *)에서 키를 자동으로 추가해주는 설정임 (가장 편리하나 비추천).

• AddKeysToAgent yes:
  • 처음 사용하는 키도 SSH 연결시 자동으로 추가
• UseKeychain yes:
  • 키의 패스워드를 Keychain에 저장: macOS전용
  • 재부팅하고 나서도 패스워드 입력이 필요하지 않음.
• IdentitiesOnly yes: SSH config에 지정된 키만 사용
  • Agent에 있는 다른 키들을 시도하지 않음.

SSH Config에 위와 같이 설정할 경우,
ssh-add를 안해줘도
세션 중에 한번이라도 연결이 되면,
SSH Agent가 자동으로 관리를 해줌 (AddKeysToAgent yes인 경우).

IdentitiesOnly yes이면
지정된 IdentityFile만 SSH Agent가 관리함.

아래와 같이 특정 Host별 설정 하는 것을 추천.

Host github.com-user
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    AddKeysToAgent yes
    UseKeychain yes
    IdentitiesOnly yes

Host github.com-tester
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa
    AddKeysToAgent yes
    UseKeychain no # 이 키는 KeyChain사용 안함.
    IdentitiesOnly yes

• 각 계정별로 다르게 지정할 수 있음.
• 한 장비에서 여러 github 계정을 가지고, 각기 다른 프로젝트에 들어갈 경우에 해당함.

---

4. SSH Agent 관리 명령어

4-1. 키 확인 및 관리

# 등록된 키 목록 (간단)
ssh-add -l

# 등록된 키 목록 (상세)
ssh-add -L

# Keychain에서 기본 키(`id`로 시작하는) 자동 로드
ssh-add --apple-load-keychain

# 모든 키 제거
ssh-add -D

# 특정 키만 제거
ssh-add -d ~/.ssh/id_ed25519

---

4-2. 키 수명 설정

임시 키인 경우에 사용할 것

• Keychain과 같이 쓰지 않는 것이 일반적임.

# 1시간 후 자동 제거
ssh-add -t 3600 ~/.ssh/id_ed25519

# 기본 수명으로 추가 (세션 종료시까지)
ssh-add ~/.ssh/id_ed25519

---

4-3. Agent 시작시키기

macOS는 자동 시작(launchd에서 관리)

 

Ubuntu의 경우

# SSH Agent 수동 시작
eval "$(ssh-agent -s)"

# 프로세스 확인
ps aux | grep ssh-agent

 

Windows의 경우

# SSH Agent 서비스 시작 (관리자 권한 필요)
net start ssh-agent

# 자동 시작 설정, 수동시작은 start=demand로, 사용안함은 start=disabled
sc config ssh-agent start=auto

# 서비스 상태 확인
sc query ssh-agent

• services.msc로 서비스 관리자 실행하여 gui로 확인 가능.

---

참고: sc (Windows Service Controller)

sc는 Windows Service Controller의 줄임말로, CLI에서 Windows 서비스를 제어하는 명령어.

 

주요 기능

• 서비스 시작/중지: sc start/stop [서비스명]
• 서비스 설정: sc config [서비스명] start=auto
• 서비스 조회: sc query [서비스명]
  • sc query state=active : 현재 실행 중인 서비스 (all:모든 서비스, inactive: 비활성화된 서비스)
• 서비스 생성/삭제: sc create/delete [서비스명]

자주 사용하는 명령어

sc query ssh-agent          # 상태 확인
sc start ssh-agent           # 서비스 시작
sc stop ssh-agent            # 서비스 중지
sc config ssh-agent start=auto  # 자동 시작 설정

---

5. macOS Keychain 통합 활용

5-1. Keychain Access 앱에서 확인

1. Keychain Access 앱 실행
2. 로그인 키체인 선택
3. SSH 검색하여 등록된 키 확인

5-2. Keychain에 저장된 SSH키들을 SSH Agent에 로딩하기

ssh-add --apple-load-keychain

---

6. 자동화 설정

Keychain이 정상동작할 경우 macOS에서는 필요없음 (회사정책으로 막힌다면... 그건 회사 관리자랑 애기).

아래의 shell script는 Ubuntu(리눅스)에 해당함.

아래의 스크립트를 추가해두면, 최초로 터미널 시작시에는 키별로 암호를 물어봐서 등록해둠.
이후로는 물어보지 않음. (컴퓨터 재시작하면 다시 물어보게 됨)

6-1. .zshrc 또는 .bash_profile 설정

# ~/.zshrc 또는 ~/.bash_profile 편집
vi ~/.zshrc
# vi ~/.bash_provile
# nano ~/.zshrc

• 사용하고 있는 shell에 따라 적절한 shell의 설정파일을 열 것.

6-2. 자동 로드 스크립트:

다음을 ~/.zshrc나 ~/.bash_profile에 추가함.

# SSH Agent 동작 확인
if [ -z "$SSH_AUTH_SOCK" ]; then
    echo "Starting SSH Agent..."    
    eval "$(ssh-agent -s)"
fi

# 키가 없으면 자동으로 추가
if ! ssh-add -l >/dev/null 2>&1; then
    echo "Loading SSH keys..."
    ssh-add ~/.ssh/id_ed25519 2>/dev/null
    ssh-add ~/.ssh/id_rsa 2>/dev/null
    # 추가할 키마다 위의 행들을 참고하여 추가.
fi

일부 키들만 지정하여 추가하려면 다음과 같이 해도 된다.

---

6-3. 선택적 키 로드

# SSH 키 로드 함수
function load_ssh_keys() {
    # Agent가 실행 중인지 확인
    if [ -z "$SSH_AUTH_SOCK" ]; then
        echo "Starting SSH Agent..."
        eval "$(ssh-agent -s)"
    fi

    # 각 키가 이미 로드되었는지 확인 후 추가
    if ! ssh-add -l | grep -q "id_ed25519"; then
        echo "Loading id_ed25519..."
        ssh-add ~/.ssh/id_ed25519 2>/dev/null
    fi

    if ! ssh-add -l | grep -q "id_rsa"; then
        echo "Loading id_rsa..."
        ssh-add ~/.ssh/id_rsa 2>/dev/null
    fi

    # 로드된 키 목록 표시
    echo "Loaded SSH keys:"
    ssh-add -l
}

# 터미널 시작시 자동 실행
load_ssh_keys

---

6-4. Keychain 실패(또는 사용 못할 경우)시 수동 로드 (macOS)

다음을 ~/.zshrc에 추가

# Keychain 우선, 실패시 수동 로드
function smart_ssh_load() {
    # Agent 확인
    if [ -z "$SSH_AUTH_SOCK" ]; then
        eval "$(ssh-agent -s)"
    fi

    # Keychain에서 먼저 시도
    ssh-add --apple-load-keychain 2>/dev/null

    # Keychain에 없으면 수동 추가
    if ! ssh-add -l >/dev/null 2>&1; then
        echo "Keychain load failed, adding keys manually..."
        ssh-add ~/.ssh/id_ed25519 2>/dev/null
        ssh-add ~/.ssh/id_rsa 2>/dev/null
    fi
}

smart_ssh_load

 

Windows에서 키를 자동으로 추가하고 싶다면 다음과 같은 ssh-setup.bat을 작성하고,

@echo off
echo Loading SSH keys...

:: SSH Agent가 실행 중인지 확인
sc query ssh-agent | find "RUNNING" >nul
if %errorlevel% neq 0 (
    echo Starting SSH Agent...
    net start ssh-agent >nul 2>&1
)

:: 키가 이미 추가되어 있는지 확인
ssh-add -l >nul 2>&1
if %errorlevel% neq 0 (
    echo Adding SSH keys...
    ssh-add %USERPROFILE%\.ssh\id_ed25519 >nul 2>&1
    ssh-add %USERPROFILE%\.ssh\id_rsa >nul 2>&1
    if %errorlevel% equ 0 (
        echo SSH keys loaded successfully.
    ) else (
        echo Failed to load SSH keys.
    )
) else (
    echo SSH keys already loaded.
)

timeout /t 2 >nul

이 배치 파일을 Windows 시작프로그램 폴더에 복사:explorer shell:startup 을 수행시 열리는 폴더.

---

7. 기타

7-1. 권한 문제

.ssh의 키들에 대한 권한을 다음과 같이 수정해 준다.

# SSH 디렉토리 권한 수정
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/id_*.pub
chmod 644 ~/.ssh/config

 

Windows는 다음과 같음:

# 파일 권한 확인 및 수정 (관리자 권한)
icacls %USERPROFILE%\.ssh\id_ed25519 /inheritance:r
icacls %USERPROFILE%\.ssh\id_ed25519 /grant:r %USERNAME%:F

7-2. Agent 재시작.

macOS

# launchd 서비스 재시작 (드물게 필요)
launchctl stop com.openssh.ssh-agent
launchctl start com.openssh.ssh-agent

 

Ubuntu

# Agent 재시작
killall ssh-agent 
eval "$(ssh-agent -s)"

 

Windows

# SSH Agent 서비스 재시작
net stop ssh-agent
net start ssh-agent

---

같이 보면 좋은 자료들

2023.12.27 - [utils/git and github] - [ssh-keygen] ssh 관련 private key와 public key 생성하기.

[ssh-keygen] ssh 관련 private key와 public key 생성하기.

2023.12.27 - [utils/git and github] - [github] ssh 키 등록하기.

[github] ssh 키 등록하기.

2024.05.21 - [utils/git and github] - [Git] git 설치 후 우선 해줘야 하는 작업들

[Git] git 설치 후 우선 해줘야 하는 작업들

---