Barman 시작하기 — 5개 명령어로 첫 백업과 PITR 복구까지

어떻게 Barman인가 — 5분 셋업

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 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이 부르는 이름 vs 네트워크가 부르는 이름의 분리
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이, /var/lib/barman/pg01/streaming/에 WAL이 누적된다.

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 14:30:00"

복원 시점은 base backup 시작 시점 이후, 가장 마지막에 받은 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 한 번을 반드시 돌려보자.

어떻게 Barman인가 — 5분 셋업#

사전 준비 — 두 호스트 lab 환경#

설치 — PGDG 저장소에서 한 줄#

설정 1: PostgreSQL 측 (demo-pg01)#

설정 2: Barman 측 (demo-barman01)#

5개 명령어 시나리오#

1. barman check pg01 — 셋업 검증#

2. barman backup pg01 — 첫 base backup#

3. barman list-backup pg01 — 카탈로그 조회#

4. barman recover — 최신 백업으로 복원#

5. barman recover --target-time — PITR#

일상 운영 — cron 한 줄과 보존 정책#

자주 만나는 에러 빠른 가이드#

정리#

참고 자료#