PostgreSQL 'Peer authentication failed' 에러

1. 개요 (Incident Overview)

이 글은 Proxmox VE 환경의 LXC(Linux Container)에 PostgreSQL을 설치한 직후, Spring Boot 백엔드 애플리케이션에 DB를 연동하려는 과정에서 발생한 접속 거부 장애에 대한 사후 분석(Postmortem) 문서입니다.

초기 설치를 무사히 마치고 접속을 시도했을 때, 아래와 같은 치명적인(FATAL) 에러가 발생하며 DB 연동이 전면 차단되었습니다.

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  Peer authentication failed for user "<DB_USERNAME>"

단순한 비밀번호 누락인 줄 알았던 이 에러는, PostgreSQL의 고유한 ‘인증 방식(Authentication) 메커니즘’ 과 ‘접속 프로토콜(Socket vs TCP/IP)’ 에 대한 이해 부족에서 비롯되었습니다. 본 회고록은 당시의 문제 해결 흐름, 원인 분석, 그리고 보안을 고려한 최종 타임라인을 상세히 기록합니다.

2. 핵심 내용 및 원인 분석 (Root Cause Analysis)

2-1. ‘Peer Authentication’의 공식적인 의미

PostgreSQL 공식 문서(Chapter 20. Client Authentication)에 따르면, Peer 인증은 다음과 같이 정의됩니다.

“The peer authentication method works by obtaining the client’s operating system user name from the kernel and using it as the allowed database user name.”

Peer 인증 방법은 클라이언트 시스템 커널로부터 현재 로그인한 OS 사용자 이름을 얻어와, 이를 데이터베이스 사용자 이름으로 허용할지 검사하는 방식으로 작동합니다.

이 상황을 보안요원(인증 시스템) 에 비유할 수 있습니다. PostgreSQL의 보안 지침서 역할을 하는 메인 설정 파일은 pg_hba.conf 입니다.

• 나의 시도: “보안요원님! 저 튼튼한 비밀번호 만들었어요! 들여보내 주세요!”

• 보안요원 (pg_hba.conf의 Peer 룰): “손님, 저희 클럽 ‘도보 정문’은 비밀번호는 안 봅니다. 오직 손님 가슴에 달린 리눅스 OS 명찰(현재 로그인한 커널 계정명) 이 <DB_USERNAME>과 정확히 일치하는지만 검사합니다. 명찰이 다르면 입장 불가입니다.”

즉, 우분투의 기본 로그인 유저(예: <OS_USERNAME>) 상태, 혹은 백엔드 애플리케이션을 실행하는 데몬 유저 상태에서 로컬 접속을 시도하면, 리눅스 명찰과 DB 명찰이 불일치하므로 인증에 즉시 실패하는 구조였습니다.

2-2. 삽질의 기록 (What Went Wrong)

이 원리를 정확히 인지하지 못해 발생했던 두 가지 논리적 오류입니다.

• 오류 1: 무작정 비밀번호만 강제로 부여하기

  • “비밀번호가 없어서 튕겨냈겠지?”라고 오판하여 아래 명령어로 강제 암호화를 시도했습니다.

  • ALTER USER <DB_USERNAME> with encrypted password '<SECURE_PASSWORD>';

  • 결과: 보안요원은 애초에 정문에서 비밀번호를 검사할 권한(설정)이 없었기 때문에 여전히 입장이 거부되었습니다.

• 오류 2: 엉뚱한 버전의 설정 파일 매핑 (pg_ident.conf)

  • OS 유저와 DB 유저 이름이 다르면 매핑해주면 된다는 단편적인 지식으로 pg_ident.conf 파일을 열어 <OS_USERNAME> <DB_USERNAME> 형태의 장부를 작성했습니다.

  • 결과: 메인 파일인 pg_hba.conf에 map=<MAP_NAME> 옵션을 주어 “이 장부를 참고해라!”라고 지시하지 않아 실패했습니다.

3. 완벽 해결 방법 3가지 및 보안성 평가

문제를 해결하기 위해 검토했던 3가지 접근 방식과 보안 관점의 평가입니다.

방법 A. 인증 방식을 비밀번호(scram-sha-256)로 전면 수정 (정공법)

보안요원의 정문 검사 규칙 자체를 ‘명찰(OS 유저명)‘에서 ‘비밀번호’로 바꿔주는 정석입니다.

/etc/postgresql/<VERSION>/main/pg_hba.conf 파일을 열어 local 접속 설정을 변경합니다.

# 변경 전 (정문: 명찰 검사)
local   all             all                                peer

# 변경 후 (정문: 최신 암호화 비밀번호 검사)
local   all             all                                scram-sha-256

🛡️ [보안 평가]: 적극 권장

scram-sha-256은 패킷 스니핑 방어가 가능한 강력한 챌린지-리스폰스 방식입니다.

방법 B. 로컬 소켓 대신 TCP/IP 네트워크(LXC IP)로 접속하기 (나의 실제 해결책)

pg_hba.conf의 로컬 설정을 뜯어고치지 않고, 접속 프로토콜 자체를 네트워크(TCP/IP) 룰을 타게 하는 우회 방식입니다.

# 백엔드 설정 (예: application.yml) 시, LXC의 IP를 명시
spring:
  datasource:
    url: jdbc:postgresql://<LXC_IP>:5432/<DB_NAME>
    username: <DB_USERNAME>
    password: <SECURE_PASSWORD>

[실제 해결의 비밀]:

사실 제가 이 장애를 돌파했던 진짜 방법이 바로 이것이었습니다. 정문(Unix Socket, local)에서 명찰 검사에 걸려 번번이 튕겨 나갔지만, 백엔드 애플리케이션(application.yml)에 DB 주소로 LXC 컨테이너에 할당된 실제 IP를 기재했습니다.

LXC IP를 명시하는 순간, 통신 방식이 소켓(도보)에서 TCP/IP(차량)로 변경됩니다. 차를 타고 ‘외부 주차장 게이트(host 룰)‘로 진입하자, DB가 정상적으로 “비밀번호를 대시오(md5 또는 scram-sha-256)“라고 요구했고, 미리 세팅해 둔 튼튼한 비밀번호가 작동하여 연동에 성공한 것입니다.

🛡️ [보안 평가]: 권장 (실무 표준 구성)

로컬 환경(127.0.0.1)이든 외부 환경(LXC IP)이든 IP 주소를 명시하면 ‘Unix 소켓(local)’ 이 아닌 ‘네트워크(host)’ 룰을 탑니다. 네트워크 접속은 비밀번호 인증을 요구하도록 설정되어 있으므로, 백엔드 서버와 DB 서버를 분리하는 실무 아키텍처에서 가장 정석적인 방법이라고 합니다.

방법 C. 관리자 권한으로 내 명찰을 위장하기 (긴급 유지보수용)

sudo -u <DB_USERNAME> psql

🚨 [보안 평가]: 애플리케이션 단에서 절대 사용 금지

운영체제 최고 권한(root 등)을 이용해 명찰을 위조하는 행위입니다. 해킹 시 DB뿐 아니라 서버 전체가 장악되므로 백엔드 코드나 스크립트에 절대 포함되어서는 안 됩니다.

4. 결론: 최종 타임라인의 재구성

사실 실제 장애가 발생하고 연동을 마쳤던 것은 몇 달 전의 일이었고, 이 글은 당시 명확히 이해하지 못했던 해결의 실마리를 최근에 다시 서버에 접속해 검토(Review)하며 작성한 사후 분석입니다.

수개월이 지난 뒤 리눅스 콘솔을 열어 다시 로그와 설정 파일을 교차 검증해 본 결과, 타임라인의 진실은 다음과 같았습니다.

1. 에러 발생: 최고 관리자 권한으로 DB 비밀번호를 세팅했으나, 정작 백엔드 앱에서는 Peer authentication failed 에러가 발생함.

2. 우연한 해결: 백엔드 환경 설정(application.yml)에 DB 접속 주소로 LXC 컨테이너의 IP 주소를 기재하여 접속.

3. 원리 파악(현재): LXC IP를 통한 접속은 TCP/IP 통신이므로, 깐깐한 도보 정문(local 소켓의 peer 룰) 대신 기본적으로 암호화 인증(md5 등)이 허용된 주차장 게이트(host 네트워크 룰)를 타게 되어 연동에 성공했다는 것을 뒤늦게 깨달음.

결과적으로 실무 표준이자 보안상으로도 안전한 ‘방법 B’를 통해 문제가 해결되었습니다. 단순한 접속 에러라도 그 이면에 있는 접속 프로토콜(Socket vs TCP/IP)의 차이와 인증 룰의 작동 방식을 명확히 규명하고 넘어갈 수 있었던 회고였습니다.

---