PostgreSQL Peer 인증 오류 완벽 해결 가이드 – pg_hba.conf 설정의 모든 것

PostgreSQL에 접속하려는데 “사용자 postgres의 peer 인증을 실패했습니다” 오류가 발생하셨나요? 이 오류는 PostgreSQL 초보자부터 숙련자까지 가장 많이 겪는 문제 중 하나입니다. 오늘은 이 오류의 원인과 해결 방법을 단계별로 완벽하게 정리해드립니다.


오류 메시지 전문

psql: 치명적오류: 사용자 "postgres"의 peer 인증을 실패했습니다.
psql: FATAL: Peer authentication failed for user "postgres"

또는

FATAL: Ident authentication failed for user "postgres"


문제 발생 원인 – Peer 인증이란?

Peer 인증 방식의 이해

PostgreSQL의 peer 인증은 운영체제의 사용자 계정과 PostgreSQL 사용자 계정이 일치해야만 접속을 허용하는 방식입니다.

예시:

  • OS 사용자가 myuser라면 PostgreSQL 사용자도 myuser여야 함
  • OS 사용자가 root인데 PostgreSQL에 postgres로 접속 시도 → 실패!

pg_hba.conf 파일이란?

pg_hba.conf는 **”host-based authentication”**의 약자로, PostgreSQL 서버가 클라이언트의 접속을 어떻게 인증할지 결정하는 핵심 설정 파일입니다.

주요 역할:

  • 어떤 사용자가 어떤 데이터베이스에 접속할 수 있는지 정의
  • 접속 방법(로컬/원격)에 따른 인증 방식 지정
  • IP 주소 기반 접속 제한
  • 보안 정책 설정


해결 방법 1 – pg_hba.conf 파일 수정 (권장)

가장 확실하고 일반적인 해결 방법입니다.

1단계: pg_hba.conf 파일 위치 찾기

PostgreSQL 버전과 설치 방법에 따라 경로가 다릅니다.

일반적인 경로:

# Ubuntu / Debian
/etc/postgresql/[버전]/main/pg_hba.conf

# 예시
/etc/postgresql/9.5/main/pg_hba.conf
/etc/postgresql/12/main/pg_hba.conf
/etc/postgresql/14/main/pg_hba.conf

# CentOS / RHEL / Fedora
/var/lib/pgsql/[버전]/data/pg_hba.conf

# 예시
/var/lib/pgsql/9.6/data/pg_hba.conf
/var/lib/pgsql/12/data/pg_hba.conf

# macOS (Homebrew)
/usr/local/var/postgres/pg_hba.conf
/opt/homebrew/var/postgres/pg_hba.conf

정확한 위치 확인 방법:

# PostgreSQL에 접속 가능한 경우
psql -U postgres -c "SHOW hba_file"

# 또는 find 명령어 사용
sudo find / -name pg_hba.conf 2>/dev/null

# 또는 데이터 디렉토리 확인
sudo -u postgres psql -c "SHOW data_directory"

2단계: 파일 백업 (필수!)

수정 전 반드시 원본을 백업하세요:

# Ubuntu / Debian
sudo cp /etc/postgresql/12/main/pg_hba.conf /etc/postgresql/12/main/pg_hba.conf.backup

# CentOS / RHEL
sudo cp /var/lib/pgsql/12/data/pg_hba.conf /var/lib/pgsql/12/data/pg_hba.conf.backup

# 백업 확인
ls -l /etc/postgresql/12/main/pg_hba.conf*

3단계: pg_hba.conf 파일 열기

# Ubuntu / Debian
sudo vi /etc/postgresql/12/main/pg_hba.conf
# 또는
sudo nano /etc/postgresql/12/main/pg_hba.conf

# CentOS / RHEL
sudo vi /var/lib/pgsql/12/data/pg_hba.conf

4단계: 인증 방식 변경

파일 하단에 다음과 같은 설정이 있습니다:

수정 전 (기본 설정):

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     peer

# IPv4 local connections:
host    all             all             127.0.0.1/32            ident

# IPv6 local connections:
host    all             all             ::1/128                 ident

수정 후 (권장 설정):

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     md5

# IPv4 local connections:
host    all             all             127.0.0.1/32            md5

# IPv6 local connections:
host    all             all             ::1/128                 md5

핵심 변경사항:

  • peer → md5 (비밀번호 인증)
  • ident → md5 (비밀번호 인증)

5단계: PostgreSQL 서비스 재시작

Ubuntu / Debian:

# PostgreSQL 버전 확인
pg_lsclusters

# 재시작
sudo systemctl restart postgresql

# 또는 버전 지정
sudo systemctl restart postgresql@12-main

# 상태 확인
sudo systemctl status postgresql

CentOS / RHEL:

# PostgreSQL 9.6 이상
sudo systemctl restart postgresql-12

# 상태 확인
sudo systemctl status postgresql-12

# PostgreSQL 9.6 미만
sudo service postgresql-9.5 restart

macOS:

# Homebrew로 설치한 경우
brew services restart postgresql

# 또는
pg_ctl restart -D /usr/local/var/postgres

6단계: 접속 테스트

# postgres 사용자로 접속
psql -U postgres

# 비밀번호 입력 프롬프트가 나오면 성공!
# 비밀번호: postgres (기본값) 또는 설정한 비밀번호


pg_hba.conf 파일 구조 상세 설명

기본 형식

TYPE    DATABASE    USER    ADDRESS    METHOD

각 필드 설명

1. TYPE (연결 유형)

타입설명사용 예시
localUnix 소켓 연결 (로컬)psql -U postgres
hostTCP/IP 연결 (암호화 안 됨)psql -h localhost -U postgres
hostsslTCP/IP 연결 (SSL 필수)원격 보안 접속
hostnosslTCP/IP 연결 (SSL 불가)내부 네트워크

2. DATABASE (데이터베이스)

all             # 모든 데이터베이스
mydb            # 특정 데이터베이스만
mydb,testdb     # 여러 데이터베이스
@filename       # 파일에서 읽기

3. USER (사용자)

all             # 모든 사용자
postgres        # 특정 사용자만
user1,user2     # 여러 사용자
+group_name     # 그룹 내 모든 사용자
@filename       # 파일에서 읽기

4. ADDRESS (주소)

# local 타입에서는 사용 안 함
127.0.0.1/32            # 로컬 IPv4
::1/128                 # 로컬 IPv6
192.168.1.0/24          # 특정 네트워크
0.0.0.0/0               # 모든 IPv4 (주의!)
::/0                    # 모든 IPv6 (주의!)
192.168.1.100           # 특정 IP (단일)

5. METHOD (인증 방식)

방식설명보안 수준사용 시나리오
trust인증 없음 (누구나 접속)⚠️ 매우 낮음개발 환경만
reject접속 거부🔒 차단특정 IP 차단
md5비밀번호 (MD5 해시)🔐 보통일반 운영 환경
scram-sha-256비밀번호 (강력한 해시)🔒 높음권장 (PG 10+)
password비밀번호 (평문)⚠️ 낮음사용 금지
peerOS 사용자 일치 필요🔐 보통로컬 관리
identIdent 서버 확인🔐 보통레거시
certSSL 클라이언트 인증서🔒 매우 높음엔터프라이즈
gssKerberos 인증🔒 높음기업 환경

실전 설정 예제

예제 1: 개발 환경 (로컬 전용)

# 로컬에서는 비밀번호만으로 접속
local   all             all                                     md5
host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5

# 외부 접속 차단
host    all             all             0.0.0.0/0               reject

예제 2: 운영 환경 (보안 강화)

# 관리자는 로컬에서만 접속 가능
local   all             postgres                                scram-sha-256

# 애플리케이션 사용자는 특정 IP에서만 접속
host    myapp_db        app_user        192.168.1.100/32        scram-sha-256

# 내부 네트워크 허용
host    all             all             192.168.1.0/24          scram-sha-256

# 나머지 모두 차단
host    all             all             0.0.0.0/0               reject

예제 3: 복합 환경 (개발 + 운영)

# 로컬 개발: 간편 접속
local   all             all                                     trust

# 로컬호스트 TCP: 비밀번호 필요
host    all             all             127.0.0.1/32            md5

# 사무실 네트워크: 비밀번호 필요
host    all             all             10.0.0.0/8              md5

# VPN 네트워크: 강력한 인증
host    all             all             172.16.0.0/16           scram-sha-256

# SSL 필수 원격 접속
hostssl all             all             0.0.0.0/0               scram-sha-256

# SSL 없는 원격 차단
hostnossl all           all             0.0.0.0/0               reject

예제 4: 특정 사용자/DB 제한

# postgres 슈퍼유저는 로컬에서만
local   all             postgres                                peer
host    all             postgres        127.0.0.1/32            reject

# 읽기 전용 사용자는 어디서나
host    all             readonly_user   0.0.0.0/0               md5

# 특정 DB는 특정 사용자만
host    production_db   prod_user       192.168.1.0/24          scram-sha-256

# 테스트 DB는 개발팀만
host    test_db         +developers     10.0.0.0/8              md5

# 나머지 모두 거부
host    all             all             0.0.0.0/0               reject

해결 방법 2 – sudo를 사용한 접속

pg_hba.conf 수정 없이 임시로 접속하는 방법입니다.

peer 인증 활용

# postgres OS 사용자로 전환 후 접속
sudo -i -u postgres
psql

# 또는 한 줄로
sudo -u postgres psql

# 특정 데이터베이스 지정
sudo -u postgres psql -d mydatabase

장점:

  • 파일 수정 불필요
  • 보안 유지
  • 즉시 접속 가능

단점:

  • sudo 권한 필요
  • 매번 sudo 입력 필요
  • 애플리케이션에서 사용 불가

해결 방법 3 – PostgreSQL 사용자 비밀번호 설정

peer/ident에서 md5로 변경 후 비밀번호를 설정해야 합니다.

비밀번호 설정 방법

# 1. sudo로 PostgreSQL 접속
sudo -u postgres psql

# 2. 비밀번호 설정
ALTER USER postgres WITH PASSWORD 'your_strong_password';

# 3. 종료
\\q

# 4. 비밀번호로 접속 테스트
psql -U postgres -h localhost
# Password: (비밀번호 입력)

새 사용자 생성

-- 새 사용자 생성 (비밀번호 포함)
CREATE USER myuser WITH PASSWORD 'mypassword';

-- 데이터베이스 생성
CREATE DATABASE mydb OWNER myuser;

-- 권한 부여
GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;

-- 연결 테스트
\\c mydb myuser

해결 방법 4 – trust 방식 사용 (개발 전용)

⚠️ 경고: 운영 환경에서는 절대 사용 금지!

개발 환경에서만 임시로 사용하는 방법입니다.

# pg_hba.conf
local   all             all                                     trust
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust

trust 방식의 위험성:

  • 누구나 비밀번호 없이 접속 가능
  • 데이터 유출 위험
  • 운영 환경 사용 시 심각한 보안 문제

원격 접속 설정 (추가)

로컬이 아닌 다른 서버에서 접속할 때 필요한 설정입니다.

1단계: postgresql.conf 수정

# 파일 열기
sudo vi /etc/postgresql/12/main/postgresql.conf

# 또는 CentOS
sudo vi /var/lib/pgsql/12/data/postgresql.conf

수정 내용:

# 수정 전
#listen_addresses = 'localhost'

# 수정 후 (모든 IP에서 접속 허용)
listen_addresses = '*'

# 또는 특정 IP만
listen_addresses = '192.168.1.100,127.0.0.1'

2단계: pg_hba.conf에 원격 IP 추가

# 특정 IP 허용
host    all             all             192.168.1.100/32        md5

# 특정 네트워크 허용
host    all             all             192.168.1.0/24          md5

# 모든 IP 허용 (주의!)
host    all             all             0.0.0.0/0               md5

3단계: 방화벽 설정

Ubuntu / Debian:

# PostgreSQL 포트 열기 (기본 5432)
sudo ufw allow 5432/tcp

# 특정 IP만 허용
sudo ufw allow from 192.168.1.100 to any port 5432

CentOS / RHEL:

# firewalld 사용
sudo firewall-cmd --permanent --add-port=5432/tcp
sudo firewall-cmd --reload

# 특정 IP만 허용
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.100" port protocol="tcp" port="5432" accept'
sudo firewall-cmd --reload

4단계: 원격 접속 테스트

# 다른 서버에서 접속
psql -h 192.168.1.100 -U postgres -d mydatabase

# 포트 지정
psql -h 192.168.1.100 -p 5432 -U postgres


문제 해결 체크리스트

접속이 안 될 때 순서대로 확인하세요:

1차 체크: 기본 사항

☐ PostgreSQL 서비스가 실행 중인가?
   sudo systemctl status postgresql

☐ 올바른 pg_hba.conf 파일을 수정했는가?
   psql -U postgres -c "SHOW hba_file"

☐ 파일 수정 후 서비스를 재시작했는가?
   sudo systemctl restart postgresql

☐ 문법 오류가 없는가?
   sudo -u postgres psql -c "SELECT pg_reload_conf();"

2차 체크: 인증 설정

☐ METHOD가 peer/ident가 아닌 md5/scram-sha-256인가?

☐ 사용자 비밀번호가 설정되어 있는가?
   sudo -u postgres psql -c "\\du"

☐ 접속 시 -h localhost 옵션을 사용했는가?
   psql -U postgres -h localhost (TCP/IP 연결)
   psql -U postgres             (Unix 소켓 연결)

3차 체크: 네트워크 설정

☐ postgresql.conf의 listen_addresses가 올바른가?

☐ 방화벽에서 5432 포트가 열려있는가?
   sudo netstat -tulpn | grep 5432

☐ PostgreSQL이 올바른 포트를 리스닝하는가?
   sudo lsof -i :5432

실전 디버깅 방법

로그 확인

# Ubuntu / Debian
sudo tail -f /var/log/postgresql/postgresql-12-main.log

# CentOS / RHEL
sudo tail -f /var/lib/pgsql/12/data/log/postgresql-*.log

# 또는 PostgreSQL 내에서
sudo -u postgres psql -c "SHOW log_directory;"
sudo -u postgres psql -c "SHOW log_filename;"

상세 로그 활성화

# postgresql.conf 수정
sudo vi /etc/postgresql/12/main/postgresql.conf

# 다음 항목 변경
log_connections = on
log_disconnections = on
log_line_prefix = '%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h '
log_statement = 'all'

# 재시작
sudo systemctl restart postgresql

설정 파일 문법 체크

# pg_hba.conf 유효성 검사
sudo -u postgres pg_ctl reload -D /var/lib/pgsql/12/data/

# 또는 PostgreSQL 내에서
sudo -u postgres psql -c "SELECT pg_reload_conf();"

# 현재 적용된 설정 확인
sudo -u postgres psql -c "SELECT * FROM pg_hba_file_rules;"

보안 권장사항

운영 환경 필수 설정

  1. scram-sha-256 사용 # md5 대신 scram-sha-256 사용 local all all scram-sha-256 host all all 127.0.0.1/32 scram-sha-256
  2. 슈퍼유저 보호 # postgres 슈퍼유저는 로컬에서만 local all postgres peer host all postgres 0.0.0.0/0 reject
  3. IP 화이트리스트 # 허용된 IP만 접속 host all all 192.168.1.0/24 scram-sha-256 host all all 0.0.0.0/0 reject
  4. SSL 강제 # SSL 연결만 허용 hostssl all all 0.0.0.0/0 scram-sha-256 hostnossl all all 0.0.0.0/0 reject

감사 로그 설정

# postgresql.conf
log_connections = on
log_disconnections = on
log_duration = on
log_statement = 'ddl'
log_line_prefix = '%t [%p]: [%l-1] user=%u,db=%d '

마무리 – 해결 방법 요약

가장 빠른 해결책:

# 1. pg_hba.conf 수정
sudo vi /etc/postgresql/12/main/pg_hba.conf

# peer → md5 변경
local   all             all                                     md5

# 2. 재시작
sudo systemctl restart postgresql

# 3. 접속
psql -U postgres -h localhost

상황별 권장 방법:

상황권장 해결책
로컬 개발 환경trust (주의 필요)
로컬 운영 환경md5 또는 scram-sha-256
원격 접속scram-sha-256 + SSL
임시 접속sudo -u postgres psql

이 가이드를 따라하시면 peer 인증 오류를 완벽하게 해결할 수 있습니다. 추가 질문이나 다른 오류가 발생하면 댓글로 공유해주세요!

참고 자료:

댓글 남기기