Publish Over SSH 서버 테스트 접속 실패

Jenkins에서 Publish Over SSH의 Test Configuration을 실행했을 때 에러가 발생했다면, 에러 메시지에 따라 원인이 완전히 다릅니다.

Connection refused, Connection timed out, Auth fail - 각 메시지가 가리키는 원인은 네트워크 계층부터 인증 계층까지 서로 다릅니다. 메시지를 정확히 파악하면 디버깅 시간을 크게 줄일 수 있습니다.

에러 메시지별 진단 및 해결

1. Connection refused

PLAINTEXT

java.net.ConnectException: Connection refused

원인: 대상 서버가 SSH 연결 자체를 거부하고 있습니다. 서버 방화벽, SSH 데몬 미가동, 또는 리스닝 포트 불일치가 주요 원인입니다.

** 진단 명령어:**

명령어	목적
`ping <HOST>`	네트워크 연결 가능 여부 확인
`nc -vz <HOST> 22`	SSH 포트 오픈 여부 확인
`sudo systemctl status sshd`	대상 서버의 SSH 데몬 상태 확인
`ss -tnlp \| grep :22`	SSH 리스닝 포트 확인

** 해결 방법:**

대상 서버에서 SSH 데몬(sshd)이 실행 중인지 확인합니다.
방화벽에서 SSH 포트(기본 22)가 허용되어 있는지 확인합니다.
Jenkins 설정의 Host, Port 값이 올바른지 재확인합니다.

BASH

# 대상 서버에서 sshd 확인 및 시작
sudo systemctl status sshd
sudo systemctl start sshd

# 방화벽에서 SSH 포트 허용
sudo firewall-cmd --add-port=22/tcp --permanent
sudo firewall-cmd --reload

2. Connection timed out

PLAINTEXT

java.net.ConnectException: Connection timed out

** 원인:** 네트워크 경로가 차단(방화벽, 보안그룹)되어 있거나, 라우팅 문제로 요청이 대상 서버에 도달하지 못하고 있습니다. Connection refused와 달리, 서버로부터 어떠한 응답도 받지 못한 상태입니다.

** 진단 명령어:**

명령어	목적
`traceroute <HOST>`	네트워크 경로 추적
`nc -vz -w 5 <HOST> 22`	5초 타임아웃으로 포트 연결 테스트

** 해결 방법:**

네트워크/방화벽 경로를 점검하고 중간 구간 차단을 해제합니다.
대상 서버가 외부에서 접근 가능한지 확인합니다 (공인/사설망, VPN 등).
클라우드 환경이면 보안 그룹(Security Group) 인바운드 규칙을 확인합니다.

3. Permission denied (publickey)

PLAINTEXT

com.jcraft.jsch.JSchException: Auth fail

** 원인:** SSH 공개키 인증에 실패한 상태입니다. 공개키 미등록, 계정 불일치, 키 형식 불일치, 파일 권한 문제가 주요 원인입니다.

** 진단 명령어:**

BASH

# 상세 디버그 모드로 SSH 접속 시도
ssh -i <PRIVATE_KEY> <USER>@<HOST> -vvv

** 해결 절차:**

순서	점검 항목	확인/조치
1	authorized_keys에 공개키 등록	대상 서버의 `~/.ssh/authorized_keys`에 Jenkins 공개키 추가
2	파일 권한 설정	`chmod 600 ~/.ssh/authorized_keys`
3	디렉토리 권한 설정	`chmod 700 ~/.ssh`
4	소유자 설정	`chown -R <user>:<user> ~/.ssh`
5	Jenkins 설정 확인	Private key 내용/경로와 로그인 Username이 올바른지 확인

BASH

# 대상 서버에서 권한 일괄 설정
chmod 700 /home/${USER}/.ssh
chmod 600 /home/${USER}/.ssh/authorized_keys
chown -R ${USER}:${USER} /home/${USER}/.ssh

** 팁:** SSH 디버그 로그(-vvv)에서 Offering public key와 Server accepts key 메시지가 출력되는지 확인하면, 키 인증 단계에서 어디서 실패하는지 정확히 파악할 수 있습니다.

빠른 진단 체크리스트

문제 발생 시 아래 순서대로 점검하면 대부분의 SSH 접속 문제를 해결할 수 있습니다.

순서	점검 항목	명령어
1	네트워크 연결	`ping <HOST>`
2	SSH 포트 오픈	`nc -vz <HOST> 22`
3	SSH 데몬 상태	`systemctl status sshd`
4	SSH 키 인증	`ssh -i <KEY> <USER>@<HOST> -vvv`
5	파일 권한	`ls -la ~/.ssh/`
6	Jenkins Test Configuration	Manage Jenkins > System > SSH Servers