Barman 빠른 시작
어떻게 Barman인가
1편이 "왜 Barman인가"였다면, 이 글은 "어떻게 Barman인가"예요. 1편에서 Barman의 14년 궤적과 아키텍처를 정리했어요. 이번에는 같은 자리에서 한 발짝 더 들어가 두 대의 Rocky Linux 머신을 준비하고, streaming-only 모드로 PostgreSQL을 설정한 뒤, 5개 명령어로 첫 백업과 PITR 복구까지 끝내 봅니다.
이번에 다룰 시나리오를 한 화면에 펼치면 다음과 같습니다.
| 단계 | 명령어 | 의미 |
|---|---|---|
| 1 | barman check pg01 | PG 연결, streaming, 권한 확인 |
| 2 | barman backup pg01 | 첫 base backup |
| 3 | barman list-backup pg01 | 카탈로그 조회 |
| 4 | barman recover pg01 latest <dir> | 최신 백업 복원 |
| 5 | barman recover ... --target-time "..." | 임의 시점 (PITR) 복원 |
읽으면서 따라 할 수 있도록 모든 명령어와 설정 파일 내용을 그대로 옮겨 둡니다.
사전 준비
두 호스트로 lab 환경을 구성합니다.
| 호스트 | 역할 | OS |
|---|---|---|
demo-pg01 | PostgreSQL 17 primary | Rocky Linux 9 |
demo-barman01 | Barman 3.18 서버 | Rocky Linux 9 |
두 호스트가 hostname으로 서로 통신한다고 가정합니다(DNS 또는 /etc/hosts). 단일 머신에서 시험하려면 demo-pg01과 demo-barman01을 모두 localhost로 두고 진행해도 됩니다.
설치
PGDG 저장소에서 설치합니다.
demo-pg01과 demo-barman01 양쪽에 PGDG 저장소를 등록합니다.
sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo dnf -qy module disable postgresql
demo-pg01에서 PostgreSQL 17 설치/초기화:
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable --now postgresql-17
demo-barman01에 Barman 3.18 설치:
sudo dnf install -y barman barman-cli
설치 시 barman 시스템 사용자가 자동 생성되며, 백업 카탈로그 기본 경로는 /var/lib/barman입니다. /etc/cron.d/barman도 함께 깔리므로 별도 systemd timer 설정 없이 cron이 매 분 한 번 barman cron을 돌립니다.
설정 1: PostgreSQL 측 (demo-pg01)
streaming 백업은 PostgreSQL의 replication 프로토콜 위에서 동작하므로, replication user와 replication slot이 필요합니다.
/var/lib/pgsql/17/data/postgresql.conf 핵심 항목:
listen_addresses = '*'
wal_level = replica
max_wal_senders = 10
max_replication_slots = 10
/var/lib/pgsql/17/data/pg_hba.conf에 Barman 측 접속을 열어 둡니다.
# TYPE DATABASE USER ADDRESS METHOD
host replication barman demo-barman01 scram-sha-256
host postgres barman demo-barman01 scram-sha-256
PostgreSQL을 재시작한 후 사용자와 슬롯을 생성합니다.
sudo systemctl restart postgresql-17
sudo -u postgres psql <<'SQL'
CREATE USER barman WITH REPLICATION ENCRYPTED PASSWORD 'changeme';
GRANT EXECUTE ON FUNCTION pg_backup_start(text, boolean) TO barman;
GRANT EXECUTE ON FUNCTION pg_backup_stop(boolean) TO barman;
GRANT EXECUTE ON FUNCTION pg_switch_wal() TO barman;
GRANT EXECUTE ON FUNCTION pg_create_restore_point(text) TO barman;
GRANT pg_read_all_settings, pg_read_all_stats TO barman;
SELECT pg_create_physical_replication_slot('barman');
SQL
실제 운영에서는
changeme을 비밀 관리자(Vault, AWS Secrets Manager 등)로 옮기고.pgpass또는 환경변수로 분리해야 합니다.
설정 2: Barman 측 (demo-barman01)
/etc/barman.conf는 default 값 그대로 두는 편이 무난합니다. 서버별 설정만 추가합니다(default 항목 자체는 별도 글에서 다룹니다).
/etc/barman.d/pg01.conf:
[pg01]
description = "Production PG primary"
conninfo = host=demo-pg01 user=barman dbname=postgres
streaming_conninfo = host=demo-pg01 user=barman
backup_method = postgres
streaming_archiver = on
slot_name = barman
create_slot = manual
retention_policy = RECOVERY WINDOW OF 4 WEEKS
[pg01]은 Barman 서버 라벨이자 서버 식별자입니다. CLI(barman backup pg01), 카탈로그 디렉토리(/var/lib/barman/pg01/...), conf 파일명(pg01.conf)에 같은 값을 씁니다. 실제 호스트네임 demo-pg01과는 별개이며, Barman이 부르는 이름과 네트워크가 부르는 이름을 분리한 것입니다.
conninfo = host=demo-pg01 ...에는 Barman이 PostgreSQL에 접속할 때 사용하는 실제 호스트네임을 지정하므로 라벨과 달라도 자연스럽습니다. backup_method = postgres는 pg_basebackup을 통한 streaming 백업을 뜻하고, streaming_archiver = on은 WAL을 pg_receivewal 방식으로 받도록 설정합니다. slot_name = barman은 앞에서 만든 replication slot을 사용합니다. create_slot = manual로 지정한 이유는 슬롯을 SQL로 이미 만들었으므로 Barman이 자동 생성하지 않게 하기 위해서입니다.
비밀번호는 barman 사용자의 ~/.pgpass로 분리합니다.
sudo -u barman tee ~barman/.pgpass > /dev/null <<'EOF'
demo-pg01:5432:*:barman:changeme
EOF
sudo chmod 600 ~barman/.pgpass
sudo chown barman:barman ~barman/.pgpass
5개 명령어 시나리오
이제부터는 모든 명령어를 barman 사용자로 실행합니다. sudo -i -u barman으로 barman 셸에 들어가거나, 명령어마다 sudo -u barman을 앞에 붙입니다.
1. barman check pg01
셋업을 검증합니다.
sudo -u barman barman check pg01
기대 출력 (요약):
Server pg01:
PostgreSQL: OK
wal_level: OK
replication slot: OK
directories: OK
retention policy settings: OK
pg_basebackup: OK
pg_basebackup compatible: OK
systemid coherence: OK
pg_receivexlog: OK
receive-wal running: OK
archiver errors: OK
한 줄이라도 FAILED가 나오면 그 항목에 셋업 단계의 문제가 있습니다. 가장 자주 보이는 receive-wal running: FAILED는 cron이 아직 한 번도 돌지 않았거나 slot 이름이 어긋났다는 뜻입니다. 한 번 강제로 돌려 두는 편이 빠릅니다.
sudo -u barman barman cron
2. barman backup pg01
첫 base backup을 실행합니다.
sudo -u barman barman backup pg01
기대 출력 (요약):
Starting backup using postgres method for server pg01 in /var/lib/barman/pg01/base/20260504T143012
Backup start at LSN: 0/3000028
Starting backup copy via pg_basebackup for 20260504T143012
Copy done (time: 12 seconds)
Backup size: 41.5 MiB
Backup end at LSN: 0/4000060
Marking backup as DONE
Backup completed (start time: 2026-05-04 14:30:12, elapsed time: 14 seconds)
/var/lib/barman/pg01/base/<timestamp>/ 아래에 base backup이 쌓입니다. WAL은 /var/lib/barman/pg01/streaming/으로 수신된 뒤 /var/lib/barman/pg01/wals/ 아래에 아카이브됩니다.
3. barman list-backup pg01
카탈로그를 조회합니다.
sudo -u barman barman list-backup pg01
기대 출력:
pg01 20260504T143012 - F - 2026-05-04 14:30:26 - Size: 41.5 MiB - WAL Size: 16 MiB
F는 full backup입니다. backup-id는 timestamp 기반(20260504T143012)이며, latest 키워드를 별칭으로 쓸 수 있습니다.
상세 보기:
sudo -u barman barman show-backup pg01 latest
Begin time / End time / Begin LSN / End LSN 등 PITR 타깃을 결정할 때 필요한 값이 모두 여기에 있습니다.
4. barman recover
최신 백업으로 복원합니다.
복원 대상은 빈 디렉토리여야 합니다. PostgreSQL이 새로 기동할 자리를 미리 비워 둡니다.
sudo mkdir -p /var/lib/barman/restore
sudo chown barman:barman /var/lib/barman/restore
sudo -u barman barman recover pg01 latest /var/lib/barman/restore
복원이 끝나면 그 디렉토리 안에 base backup이 풀리고, recovery.signal과 postgresql.auto.conf의 restore_command 항목이 자동 생성됩니다. PostgreSQL을 그 데이터 디렉토리로 띄우면 곧장 기동합니다.
다른 호스트로 직접 복원하려면
--remote-ssh-command "ssh postgres@<host>"를 추가합니다. 이때barman사용자에서 그 호스트의postgres로 SSH 키 기반 접속이 미리 설정되어 있어야 합니다.
5. barman recover --target-time
특정 시점으로 되감는 PITR을 실행합니다.
sudo -u barman barman recover pg01 latest /var/lib/barman/restore \
--target-time "2026-05-04 15:00:00"
복원 시점은 base backup 종료(End time) 이후, 가장 마지막에 받은 WAL 이전 사이여야 합니다. 정확한 경계가 헷갈리면 barman show-backup pg01 latest의 Begin time / End time을 기준으로 잡습니다.
다른 PITR 타깃 옵션도 같은 자리에 지정합니다.
| 옵션 | 의미 |
|---|---|
--target-time | 시점 기준 |
--target-xid | 트랜잭션 ID 기준 |
--target-name | pg_create_restore_point()로 만든 명시적 라벨 |
--target-immediate | base backup 직후 일관성 시점 |
일상 운영
cron 한 줄과 보존 정책을 설정합니다.
설치 시 동봉된 /etc/cron.d/barman이 매 분 barman cron을 실행합니다(WAL 수신과 아카이브 정리 담당). 정기 백업은 별도 cron 한 줄로 잡는 방식이 표준입니다.
# /etc/cron.d/barman-backup — 매일 02:00에 모든 등록 서버 백업
0 2 * * * barman /usr/bin/barman backup all
보존 정책은 서버별 conf 한 줄로 끝납니다.
retention_policy = RECOVERY WINDOW OF 4 WEEKS
# 또는 개수 기반:
# retention_policy = REDUNDANCY 5
RECOVERY WINDOW는 "이 시점부터 N 단위(WEEKS/DAYS) 전까지 PITR이 가능하도록 보장"한다는 의미입니다. 지난 4주 동안 임의 시점으로 되감을 수 있도록 base backup과 WAL을 함께 보존합니다. 정책에서 벗어난 backup은 barman cron이 자동으로 정리합니다.
자주 만나는 에러 빠른 가이드
| 증상 | 원인 | 한 줄 해결 |
|---|---|---|
receive-wal running: FAILED | streaming WAL receiver 미실행 | barman cron 수동 실행, slot 이름/권한 재점검 |
replication slot: FAILED | PG 측 슬롯이 없음 / 이름 불일치 | pg_create_physical_replication_slot('barman') 다시 실행 |
pg_basebackup: FAILED | replication 권한/pg_hba 미흡 | barman 사용자의 REPLICATION 속성 확인, pg_hba에 host replication 행 |
Connection refused | listen_addresses, 방화벽 | postgresql.conf의 listen_addresses = '*', firewalld에서 5432 허용 |
barman check는 한 번에 끝내려 들기보다 "FAIL 한 줄씩 잡아 나가는 도구"로 보면 마음이 편합니다. 위 4개를 해결하면 첫 셋업의 90%가 끝납니다.
정리
| 항목 | 내용 |
|---|---|
| 백업 모델 | streaming-only (SSH 없이 pg_basebackup + replication slot) |
| 카탈로그 위치 | /var/lib/barman/pg01/{base,streaming,wals} |
| 일상 명령어 | barman cron (자동) + barman backup all (cron 1회/일) |
| 검증 명령어 | barman check pg01 — 셋업 직후/이상 발생 시 첫 진단 |
| PITR | barman recover ... --target-time "..." 한 줄 |
| 보존 정책 | RECOVERY WINDOW OF 4 WEEKS 권장 |
백업의 가치는 백업이 아니라 복구에서 결정돼요. 셋업 직후 PITR을 한 번은 반드시 돌려봐요.
