Zimbra에서 "TLS를 시작할 수 없습니다: SSL 핸드셰이크 실패" 오류를 해결하는 방법

이 메시지는 Unable to start TLS: SSL handshake failed클라이언트와 서버가 암호화된 연결을 시작하는 협상을 완료하지 못했음을 의미합니다. Zimbra에서 이 메시지는 여러 곳에서 발생할 수 있습니다. 자주 나타나는 변형 메시지 중 하나는 zmcontrol statusLDAP 마스터에 대한 연결에서 인증서 검증에 실패했다는 내용입니다. 메일 클라이언트나 SMTP 릴레이에서도 공용 메일 포트에서 핸드셰이크 문제가 발생했다고 보고할 수 있습니다.

해결 방법은 어떤 연결에 실패했는지에 따라 다릅니다. 먼저 주변 로그 라인에서 서비스와 호스트 이름을 확인하십시오. 그런 다음 인증서, 발급 체인, 시스템 시계 및 TLS 엔드포인트를 확인하십시오. 첫 번째 조치로 TLS를 비활성화하는 것은 피하십시오. TLS 비활성화는 증상을 가릴 뿐만 아니라 내부 메일 서버 통신을 약화시키거나 중단시킬 수 있습니다.

변경하기 전에 알아야 할 사항

TLS 는 네트워크 연결을 암호화하는 프로토콜입니다. TLS 핸드셰이크 는 두 시스템이 암호화 매개변수에 동의하고 서버 인증서를 검증하는 초기 교환 과정입니다. STARTTLS는 일반 프로토콜 연결로 시작하여 양쪽에서 요청할 때 TLS로 전환됩니다. LDAP와 SMTP 모두 STARTTLS를 사용할 수 있으므로 이 오류만으로는 어떤 서비스가 실패했는지 정확히 파악할 수 없습니다.

복구 명령을 실행하기 전에 Zimbra 버전, 단일 노드 설치인지 다중 노드 설치인지 여부, 오류가 발생하는 정확한 명령 또는 클라이언트, 그리고 해당 오류를 둘러싼 전체 로그 라인을 기록해 두십시오. 인증서 배포 또는 서비스 재시작은 유지 관리 기간에 예약하십시오. 인증서 파일과 구성을 편집하기 전에 백업을 만들어 두십시오.

• Zimbra 릴리스 버전에 필요한 계정 및 권한으로 관리자 명령을 실행하십시오.
• 개인 키, 비밀번호 또는 수정되지 않은 메일 로그를 티켓이나 공개 포럼에 붙여넣지 마십시오.
• 어떤 엔드포인트에서 오류가 발생했는지 확인하고 해당 엔드포인트의 인증서를 점검하기 전까지는 LDAP 보안 플래그 또는 프로토콜 설정을 변경하지 마십시오.

1단계: 실패한 TLS 연결을 식별합니다.

먼저 문제를 재현하고 전체 메시지를 확인하십시오. Zimbra가 서비스 상태를 확인할 때 해당 메시지가 나타나고 "..."와 같은 문구가 포함되어 있다면 when connecting to ldap master내부 LDAP TLS 문제를 조사하십시오. 메일 클라이언트에서만 SMTP 전송에 실패하는 경우, 공용 SMTP 엔드포인트와 클라이언트의 호스트 이름, 포트 및 암호화 모드를 조사하십시오.

su - zimbra
zmcontrol status

최근 Zimbra 로그에서 동일한 타임스탬프를 확인하십시오. 대부분의 설치 환경에서 기본 로그는 입니다 /var/log/zimbra.log. 서버에 구성된 로그 위치를 사용하십시오.

grep -Ei 'Unable to start TLS|SSL handshake|certificate|ldap|STARTTLS' /var/log/zimbra.log | tail -n 80

프로세스 이름, 원격 호스트, 포트, 그리고 인증서 검증 실패, 만료된 인증서, 알 수 없는 발급자 또는 프로토콜 경고와 같은 OpenSSL 관련 세부 정보를 확인하십시오. 이러한 세부 정보는 인증서 신뢰 문제와 네트워크 또는 프로토콜 불일치를 구분하는 데 도움이 됩니다.

내부 LDAP 오류가 발생하는 경우, 이 서버가 사용하도록 구성된 LDAP 호스트를 확인하십시오. 로컬 구성 키를 개별적으로 조회하고 해당 호스트 이름을 DNS 및 서버 인증서와 비교하십시오.

zmlocalconfig ldap_url
zmlocalconfig ldap_master_url
zmlocalconfig ldap_starttls_supported
zmlocalconfig ldap_starttls_required

키 가용성 및 출력은 Zimbra 버전 및 노드 역할에 따라 다를 수 있습니다. 이러한 값은 진단용 읽기이므로 출력에 나타난다고 해서 값을 변경하지 마십시오. Zimbra 설명서에서는 LDAP STARTTLS 설정의 역할에 대해 설명하고 내부 TLS를 활성화 상태로 유지하는 것을 권장합니다. 자세한 내용은 Zimbra TLS 및 STARTTLS 로컬 구성 값을 참조하십시오 .

2단계: 시스템 시계, DNS 및 연결 가능성을 확인합니다.

인증서 유효성 검사는 서버의 시계에 따라 달라집니다. 시계가 실제 시간과 크게 차이가 나면 유효한 인증서가 유효하지 않거나 만료된 것으로 표시될 수 있습니다. Zimbra 호스트와 연결에 관련된 모든 LDAP 마스터 또는 복제본의 시간을 확인하십시오.

date -u
getent hosts ldap.example.com

구성 또는 로그에서 찾은 LDAP 호스트 이름으로 교체하십시오 ldap.example.com. 해당 호스트 이름이 예상 서버 주소로 확인되는지, 그리고 구성된 LDAP 포트가 호스트 방화벽 및 네트워크를 통해 접근 가능한지 확인하십시오. 다중 노드 설치 환경에서는 워크스테이션뿐만 아니라 오류가 기록된 Zimbra 노드에서 실제 LDAP 노드로 테스트해야 합니다.

클라이언트용 SMTP STARTTLS 연결의 경우, Zimbra의 SMTP 문제 해결 가이드에서는 OpenSSL을 사용하여 25번 포트를 테스트하는 방법을 보여줍니다. 587번 포트 또한 STARTTLS를 사용한 메시지 전송에 일반적으로 사용됩니다. 메일 클라이언트에 구성된 호스트 이름과 포트를 사용하십시오.

openssl s_client -starttls smtp -connect mail.example.com:587 -servername mail.example.com -showcerts

포트 25의 SMTP를 사용하려면 587를 로 바꾸십시오 25. 포트 465는 암시적 TLS를 사용하므로 해당 포트를 테스트할 때는 를 추가하지 마십시오 -starttls smtp. TCP 연결이 성공했다고 해서 인증서가 신뢰할 수 있거나 클라이언트가 올바른 보안 모드를 사용하고 있다는 것을 보장하는 것은 아닙니다. Zimbra의 SMTP 및 OpenSSL 문제 해결 가이드를 참조하십시오 .

3단계: Zimbra가 실제로 배포한 인증서를 검사합니다.

인증서는 서버에 대한 서명된 신원 확인 문서입니다. 인증서는 클라이언트가 사용하는 호스트 이름에 대해 유효해야 하고, 유효 기간 내에 있어야 하며, 연결하는 구성 요소가 신뢰하는 인증 기관으로 연결되어야 합니다. 브라우저에서는 인증서가 올바르게 보일 수 있지만, LDAP, Postfix 또는 프록시 노드에는 다른 인증서가 배포될 수 있습니다.

Zimbra 관리자로서 Zimbra가 배포되었다고 보고하는 인증서를 확인하십시오.

/opt/zimbra/bin/zmcertmgr viewdeployedcrt

나열된 각 인증서의 주체 또는 주체 대체 이름(SAN), 발급자, 만료일 및 서비스를 확인하십시오. SAN에는 LDAP 또는 메일 연결에 실제로 사용되는 호스트 이름이 포함되어야 합니다. 또한 다중 서버 배포의 모든 노드에 예상되는 인증서와 인증서 체인이 있는지 확인하십시오. Zimbra는 배포된 인증서 보기가 서버에서 로컬로 수행되므로 관련 노드 각각에서 검사를 실행해야 한다고 안내합니다.

원본 인증서 파일이 있는 경우 배포 전에 파일의 날짜와 이름을 확인하십시오.

openssl x509 -in /tmp/commercial.crt -noout -dates -subject -issuer -ext subjectAltName

예시 경로를 평가하려는 인증서 파일로 바꾸십시오. SAN이 누락되었거나, 리프 또는 중간 인증서가 만료되었거나, 호스트 이름이 잘못되었거나, 다른 서버에 발급된 인증서인 경우 유효성 검사가 실패할 수 있습니다.

4단계: 개인 키와 인증서 체인을 확인합니다.

인증서 체인은 클라이언트가 서버 인증서를 신뢰할 수 있는 기관까지 추적할 수 있도록 하는 발급자 인증서 집합입니다. 체인 파일에 중간 인증서가 누락되었거나 잘못된 체인이 포함된 경우, 최상위 인증서가 최신 상태이더라도 클라이언트가 서버 접속을 거부할 수 있습니다. 또한 인증서와 개인 키는 반드시 일치하는 쌍이어야 합니다.

상용 인증서의 경우 Zimbra의 인증서 도구에서 검증 단계를 제공합니다. 설치 환경 및 인증 기관에 맞게 파일 경로를 조정하십시오.

/opt/zimbra/bin/zmcertmgr verifycrt comm   /opt/zimbra/ssl/zimbra/commercial/commercial.key   /tmp/commercial.crt   /tmp/ca_chain.crt

인증서와 개인 키가 일치하고 인증서 체인이 유효한 것으로 확인된 경우에만 진행하십시오. 검증에 실패한 후에는 인증서를 배포하지 마십시오. 인증 기관에서 제공하는 중간 체인과 사용 중인 Zimbra 버전에 맞는 체인 형식을 사용하십시오. 관련 없는 루트 인증서를 추측하거나 추가하여 체인을 구성하지 마십시오.

Zimbra의 인증서 가이드에는 CA 체인을 포함한 검증 및 배포 순서가 설명되어 있습니다( Zimbra 인증서 설치 및 CLI 도구 참조 ). 또한 인증서 체인 문제 해결 페이지에서는 발급자 체인 검증 오류에 대한 설명도 제공합니다( Zimbra 인증서 체인 안내 참조) .

5단계: 인증서를 수정하고 안전하게 배포합니다.

인증서 만료, 잘못된 키, 중간 키 누락 또는 호스트 이름 불일치 등의 문제가 확인되면 배포 전에 올바른 파일을 확보하거나 생성하십시오. 사용 중인 Zimbra 버전 및 인증서 유형에 맞는 절차를 따르십시오. 상용 인증서의 경우, 문서화된 명령은 일반적으로 다음과 같은 형식을 따릅니다.

/opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt

설치된 릴리스에 설명된 정확한 명령 구문과 권한을 사용하십시오. Zimbra CLI는 MTA, LDAP 및 프록시와 같은 구성 요소에 대한 인증서를 설치할 수 있으므로 배포로 인해 여러 서비스에 영향을 줄 수 있습니다. 다중 노드 환경에서는 LDAP 마스터를 포함하여 모든 관련 서버에 인증서가 올바르게 배포되었는지 확인하십시오.

검증된 배포 후, 릴리스 절차에 따라 필요한 경우 예정된 유지 관리 기간 동안 Zimbra 서비스를 다시 시작하고 서비스 상태 및 배포된 인증서를 확인하십시오.

su - zimbra
zmcontrol restart
zmcontrol status
/opt/zimbra/bin/zmcertmgr viewdeployedcrt

재시작하면 서비스가 중지되었다가 다시 시작되는 동안 메일 및 웹 액세스가 중단됩니다. 사용량이 많은 운영 서버에서 함부로 실행하지 마십시오. Zimbra 인증서 가이드에는 zmcontrol restart배포 후 사용 방법과 결과 확인 방법이 설명되어 있습니다 viewdeployedcrt.

6단계: TLS를 비활성화하지 않고 LDAP 신뢰 구성을 확인합니다.

인증서 자체는 검증되었지만 Zimbra의 LDAP 클라이언트에서 여전히 거부되는 경우, LDAP 신뢰 자료와 오류가 발생한 노드를 점검하십시오. Zimbra의 보관된 MTA 문제 해결 노트에는 /opt/zimbra/conf/caLDAP STARTTLS 실패의 가능한 원인으로 유효하지 않은 CA 체인, 만료된 CA 인증서 및 예기치 않은 파일이 나열되어 있습니다. 이는 진단 단서로 활용하고 파일을 삭제해서는 안 됩니다. 디렉터리를 정상 백업 또는 버전별 지침과 비교하고 변경하기 전에 내용을 보존하십시오.

간단한 LDAP STARTTLS 프로브의 경우, OpenLDAP 클라이언트는 계정 자격 증명을 제공하지 않고도 StartTLS를 요구하고 루트 DSE에 쿼리할 수 있습니다.

ldapsearch -x -ZZ -H ldap://ldap.example.com:389 -b "" -s base namingContexts

실제 배포 환경에서 사용하는 LDAP 호스트와 포트를 사용하십시오. OpenLDAP 도구는 -ZZStartTLS를 요청하며, 설정 실패를 오류로 처리합니다. 이 프로브가 신뢰 또는 인증서 관련 메시지와 함께 실패하는 경우, LDAP 엔드포인트에서 반환된 인증서를 배포된 인증서 및 클라이언트에서 사용 가능한 CA 신뢰 설정과 비교하십시오. 한 노드에서는 테스트가 성공하지만 다른 노드에서는 실패하는 경우, DNS, CA 파일 또는 로컬 구성의 차이점을 조사하십시오.

7단계: 인증서 확인을 마친 후에만 프로토콜 호환성을 고려하십시오.

클라이언트와 서버가 TLS 프로토콜 버전 또는 암호화 스위트에 대해 합의하지 못하면 핸드셰이크가 실패할 수 있습니다. 이는 구형 클라이언트, 사용자 지정 보안 강화 또는 버전별 기본값으로 인해 발생할 수 있습니다. 최신 OpenSSL 클라이언트를 사용하여 엔드포인트를 테스트하고 Zimbra의 TLS 설정에서 정확한 제품 버전을 확인하십시오. 이전 버전의 프로토콜 명령을 최신 설치 환경에 복사하지 마십시오. 암호화 및 프로토콜 구성은 릴리스 간에 변경될 수 있습니다.

SSLv3를 활성화하거나, 검증을 약화시키거나, LDAP STARTTLS를 전역적으로 비활성화하여 오류를 "해결"하지 마십시오. Zimbra 포럼의 한 게시글에는 LDAP STARTTLS를 비활성화하는 과거 해결 방법이 나와 있지만, 다른 답변자가 보안 기능을 비활성화하는 것은 안전한 인증서 복구 방법이 아니라고 정확하게 경고했습니다. Zimbra의 로컬 구성 관련 안내에서도 프로세스 간 TLS와 LDAP STARTTLS를 활성화된 상태로 유지할 것을 권장합니다. 이러한 변경은 Zimbra 지원팀의 지시가 있는 경우에만 엄격하게 통제된 임시 진단 목적으로 사용하고, 즉시 안전한 설정으로 복원하십시오.

수리 완료 확인 방법

• zmcontrol status만약 LDAP TLS 오류가 실패 원인이었다면, 해당 오류 없이 완료됩니다.
• 해당 LDAP 또는 SMTP 엔드포인트는 예상대로 만료되지 않은 인증서와 완전한 발급자 체인을 제공합니다.
• 동일한 호스트 및 네트워크 경로에서 수행한 테스트는 의도한 TLS 모드로 성공적으로 완료되었습니다.
• Zimbra 로그에는 더 이상 테스트 시 인증서 확인 또는 핸드셰이크 오류가 표시되지 않습니다.
• SMTP의 경우 양방향으로 테스트 메시지를 보내고 관련 큐 또는 로그에서 전달 여부를 확인하십시오.

오류가 계속 발생하는 경우, 전체 오류 메시지, Zimbra 릴리스 버전, 영향을 받는 서비스 및 호스트 이름, 인증서 날짜 및 SAN, 검증 출력, 관련 로그 라인을 수집하십시오. 공유하기 전에 개인 키, 자격 증명, 사용자 주소 및 민감한 호스트 정보는 삭제하십시오. 정확한 오류 메시지는 증상일 뿐 완전한 진단이 아니며, 주변 서비스 이름과 OpenSSL 오류 원인을 통해 적절한 해결 방법을 결정할 수 있습니다.

참고: Zimbra의 공개 인증서 및 TLS 페이지에는 여러 릴리스에 대한 자료가 포함되어 있으며, 일부 문제 해결 페이지는 명시적으로 보관 처리되었습니다. 여기에 제시된 명령은 문서화된 CLI 패턴을 따르지만, 인증서 경로, 권한 및 재시작 요구 사항은 설치된 Zimbra 버전의 문서를 참조하여 확인해야 합니다. 2026년 10월 6일 검토 완료.