🚨 Jenkins "fatal: SSH error: data could not be sent to remote host" 오류 해결 방법

Jenkins에서 SSH를 통해 원격 서버에 데이터를 전송할 때 발생하는 오류입니다.

일반적으로 SSH 연결 문제, 인증 오류, 방화벽 설정, SSH 키 문제 등이 원인일 수 있습니다.

---

✅ 1. 기본적인 SSH 연결 확인

먼저, Jenkins 서버에서 원격 서버로 SSH 접속이 정상적으로 되는지 확인합니다.

ssh -v <username>@<remote_host>

📌 -v 옵션을 사용하면 디버깅 정보를 출력하여 문제 원인을 찾을 수 있음.

🔹 SSH 연결이 실패하는 경우

• 비밀번호 인증 오류: SSH 키 대신 비밀번호가 필요할 수 있음.
• 포트 문제: SSH 기본 포트(22)가 아닌 다른 포트 사용 가능.
• 방화벽/네트워크 문제: 방화벽이 SSH 트래픽을 차단할 수 있음.

👉 해결 방법:

ssh -p <PORT> <username>@<remote_host>

• SSH 포트가 다를 경우, -p 옵션을 추가하여 테스트.

---

✅ 2. Jenkins에서 SSH 키 인증 확인

Jenkins는 기본적으로 SSH 키 기반 인증을 사용합니다.
SSH 키가 정상적으로 설정되어 있는지 확인합니다.

🔹 2.1 Jenkins 서버에서 SSH 키 존재 여부 확인

ls -l /var/lib/jenkins/.ssh/id_rsa

• 파일이 없다면 SSH 키가 설정되지 않은 것 → SSH 키를 새로 생성해야 함.

🔹 2.2 SSH 키가 없다면 새로 생성

ssh-keygen -t rsa -b 4096 -C "jenkins@yourdomain.com"

• 파일 경로: /var/lib/jenkins/.ssh/id_rsa
• 프롬프트가 뜨면 그냥 Enter (비밀번호 없이 설정)

🔹 2.3 원격 서버에 공개 키 복사

Jenkins 서버의 공개 키(id_rsa.pub)를 원격 서버의 ~/.ssh/authorized_keys에 추가해야 합니다.

ssh-copy-id -i /var/lib/jenkins/.ssh/id_rsa.pub <username>@<remote_host>

📌 SSH 비밀번호 없이 접속되는지 확인

ssh <username>@<remote_host>

• 비밀번호 없이 SSH 접속되면 정상 작동.

---

✅ 3. Jenkins SSH Agent 설정 확인

Jenkins에서 SSH 연결을 할 때, SSH Agent 플러그인을 사용하여 SSH 키를 로드하는 경우 설정을 확인해야 합니다.

🔹 3.1 SSH Agent 플러그인 설치 확인

1. Jenkins 관리자 페이지 이동
   Jenkins 관리 → 플러그인 관리 → 설치된 플러그인
2. SSH Agent Plugin이 설치되어 있는지 확인
   • 없다면 설치 후 Jenkins 재시작.

🔹 3.2 SSH Credentials 추가

1. Jenkins 관리 → 자격 증명 → (Global 또는 프로젝트 스코프 선택) → SSH Username with Private Key 추가
2. Private Key 경로를 Jenkins SSH 키로 설정 (/var/lib/jenkins/.ssh/id_rsa)
3. Passphrase 없음(Empty) 설정
4. 저장 후 다시 빌드 실행

---

✅ 4. Jenkins Job에서 SSH 실행 시 Permission 문제 해결

Jenkins Job을 실행할 때, Jenkins 사용자의 SSH 키 권한이 잘못되었을 수 있음.

🔹 4.1 SSH 키 파일 권한 수정

sudo chown -R jenkins:jenkins /var/lib/jenkins/.ssh
sudo chmod 700 /var/lib/jenkins/.ssh
sudo chmod 600 /var/lib/jenkins/.ssh/id_rsa

• Jenkins 사용자가 키를 읽을 수 있도록 권한 설정
• chmod 600으로 개인 키의 권한을 제한하여 보안 강화

---

✅ 5. Jenkins Pipeline에서 SSH 명령 실행하기

Jenkins Pipeline에서 SSH를 사용할 경우, SSH Agent 또는 SSH Pipeline Step을 사용하여 실행할 수 있습니다.

🔹 방법 1: SSH Agent 사용 (SSH Credentials 활용)

pipeline {
    agent any
    stages {
        stage('SSH to Remote Host') {
            steps {
                sshagent(['jenkins-ssh-key-id']) {
                    sh 'ssh -o StrictHostKeyChecking=no user@remote_host "ls -la"'
                }
            }
        }
    }
}

📌 주의: jenkins-ssh-key-id는 Jenkins Credential에서 생성한 SSH Key ID입니다.

---

🔹 방법 2: 직접 SSH 명령 실행

pipeline {
    agent any
    stages {
        stage('Run SSH Command') {
            steps {
                sh 'ssh -i /var/lib/jenkins/.ssh/id_rsa user@remote_host "ls -l /home/user"'
            }
        }
    }
}

📌 옵션 -i 를 통해 Jenkins의 SSH 키를 명시적으로 지정 가능.

---

✅ 6. SSH 연결 오류 관련 추가 해결 방법

🔹 6.1 Known Hosts 문제 해결

Jenkins에서 처음으로 SSH 접속 시 "host verification failed" 오류가 발생할 수 있음.

👉 해결 방법: StrictHostKeyChecking=no 옵션 사용

ssh -o StrictHostKeyChecking=no <username>@<remote_host>

또는 /etc/ssh/ssh_config 파일에 다음을 추가:

Host *
    StrictHostKeyChecking no

---

🔹 6.2 방화벽 및 네트워크 문제 확인

방화벽이 SSH 트래픽을 차단하는 경우, 방화벽 설정을 확인해야 합니다.

✅ 원격 서버에서 SSH 포트 열려 있는지 확인

sudo netstat -tulnp | grep 22

👉 SSH 서비스가 실행 중인지 확인

✅ 방화벽에서 SSH 허용

sudo ufw allow 22/tcp

📌 AWS의 경우, 보안 그룹(Security Group)에서 포트 22를 허용해야 함.

---

🚀 최종 해결 가이드

문제원인해결 방법

SSH 접속 불가	SSH 키 또는 비밀번호 문제	ssh -v user@remote_host로 디버깅
Permission Denied	SSH 키 권한 문제	chmod 600 ~/.ssh/id_rsa
SSH 키 없음	Jenkins에 SSH 키가 설정되지 않음	/var/lib/jenkins/.ssh/id_rsa 추가
Jenkins에서 SSH 실행 실패	Jenkins 사용자 권한 부족	sudo chown -R jenkins:jenkins ~/.ssh
Host Verification Failed	Host Key 체크 문제	StrictHostKeyChecking=no 설정

이제 위 단계를 순서대로 진행하면 Jenkins에서 SSH 연결 문제를 해결할 수 있습니다! 🚀