'\" t
.\"     Title: walmgr
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 03/13/2012
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "WALMGR" "1" "03/13/2012" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
walmgr \- tools for managing WAL\-based replication for PostgreSQL\&.
.SH "SYNOPSIS"
.sp
.nf
walmgr\&.py <config\&.ini> command
.fi
.SH "DESCRIPTION"
.sp
It is both admin and worker script for PostgreSQL PITR replication\&.
.SH "QUICK START"
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Set up passwordless ssh authentication from master to slave
.sp
.if n \{\
.RS 4
.\}
.nf
master$ test \-f ~/\&.ssh/id_dsa\&.pub || ssh\-keygen \-t dsa
master$ cat ~/\&.ssh/id_dsa\&.pub | ssh slave cat \e>\e> \&.ssh/authorized_keys
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Configure paths
.sp
.if n \{\
.RS 4
.\}
.nf
master$ edit master\&.ini
slave$ edit slave\&.ini
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Make sure that walmgr\&.py executable has same pathname on slave and master\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Start archival process and create a base backup
.sp
.if n \{\
.RS 4
.\}
.nf
master$ \&./walmgr\&.py master\&.ini setup
master$ \&./walmgr\&.py master\&.ini backup
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Note: starting from PostgreSQL 8\&.3 the archiving is enabled by setting
archive_mode GUC to on\&. However changing this parameter requires the
server to be restarted\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
Prepare postgresql\&.conf and pg_hba\&.conf on slave and start replay
.sp
.if n \{\
.RS 4
.\}
.nf
master$ scp $PGDATA/*\&.conf slave:
slave$ \&./walmgr\&.py slave\&.ini restore
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
For debian based distributions the standard configuration files are located
in /etc/postgresql/x\&.x/main directory\&. If another scheme is used the postgresql\&.conf
and pg_hba\&.conf should be copied to slave full_backup directory\&. Make sure to
disable archive_command in slave config\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqwalmgr\&.py restore\*(Aq moves data in place, creates recovery\&.conf and starts postmaster
in recovery mode\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
In\-progress WAL segments can be backup by command:
.sp
.if n \{\
.RS 4
.\}
.nf
master$ \&./walmgr\&.py master\&.ini sync
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
If need to stop replay on slave and boot into normal mode, do:
.sp
.if n \{\
.RS 4
.\}
.nf
slave$ \&./walmgr\&.py slave\&.ini boot
.fi
.if n \{\
.RE
.\}
.RE
.SH "GENERAL OPTIONS"
.sp
Common options to all walmgr\&.py commands\&.
.PP
\-h, \-\-help
.RS 4
show this help message and exit
.RE
.PP
\-q, \-\-quiet
.RS 4
make program silent
.RE
.PP
\-v, \-\-verbose
.RS 4
make program more verbose
.RE
.PP
\-n, \-\-not\-really
.RS 4
Show what would be done without actually doing anything\&.
.RE
.SH "MASTER COMMANDS"
.SS "setup"
.sp
Sets up postgres archiving, creates necessary directory structures on slave\&.
.SS "sync"
.sp
Synchronizes in\-progress WAL files to slave\&.
.SS "syncdaemon"
.sp
Start WAL synchronization in daemon mode\&. This will start periodically synching the in\-progress WAL files to slave\&.
.sp
The following parameters are used to drive the syncdaemon: loop_delay \- how long to sleep between the synchs\&. use_xlog_functions \- use record based shipping to synchronize in\-progress WAL segments\&.
.SS "stop"
.sp
Deconfigures postgres archiving\&.
.SS "periodic"
.sp
Runs periodic command, if configured\&. This enables to execute arbitrary commands on interval, useful for synchronizing scripts, config files, crontabs etc\&.
.SS "listbackups"
.sp
List backup sets available on slave node\&.
.SS "backup"
.sp
Creates a new base backup from master database\&. Will purge expired backups and WAL files on slave if keep_backups is specified\&. During a backup a lock file is created in slave completed_wals directory\&. This is to prevent simultaneous backups and resulting corruption\&. If running backup is terminated, the BACKUPLOCK file may have to be removed manually\&.
.SS "restore <set> <dst>"
.sp
EXPERIMENTAL\&. Attempts to restore the backup from slave to master\&.
.SH "SLAVE COMMANDS"
.SS "boot"
.sp
Stop log playback and bring the database up\&.
.SS "pause"
.sp
Pauses WAL playback\&.
.SS "continue"
.sp
Continues previously paused WAL playback\&.
.SS "listbackups"
.sp
Lists available backups\&.
.SS "backup"
.sp
EXPERIMENTAL\&. Creates a new backup from slave data\&. Log replay is paused, slave data directory is backed up to full_backup directory and log replay resumed\&. Backups are rotated as needed\&. The idea is to move the backup load away from production node\&. Usable from postgres 8\&.2 and up\&.
.SS "restore [src][dst]"
.sp
Restores the specified backup set to target directory\&. If specified without arguments the latest backup is \fBmoved\fR to slave data directory (doesn\(cqt obey retention rules)\&. If src backup is specified the backup is copied (instead of moving)\&. Alternative destination directory can be specified with dst\&.
.SH "CONFIGURATION"
.SS "Common settings"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBjob_name\fR
.RS 4
.sp
Optional\&. Indentifies this script, used in logging\&. Keep unique if using central logging\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlogfile\fR
.RS 4
.sp
Where to log\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBuse_skylog\fR
.RS 4
.sp
Optional\&. If nonzero, skylog\&.ini is used for log configuration\&.
.RE
.SS "Master settings"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBpidfile\fR
.RS 4
.sp
Pid file location for syncdaemon mode (if running with \-d)\&. Otherwise not required\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBmaster_db\fR
.RS 4
.sp
Database to connect to for pg_start_backup() etc\&. It is not a good idea to use dbname=template if running syncdaemon in record shipping mode\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBmaster_data\fR
.RS 4
.sp
Master data directory location\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBmaster_config\fR
.RS 4
.sp
Master postgresql\&.conf file location\&. This is where archive_command gets updated\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBmaster_restart_cmd\fR
.RS 4
.sp
The command to restart master database, this used after changing archive_mode parameter\&. Leave unset, if you cannot afford to restart the database at setup/stop\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave\fR
.RS 4
.sp
Slave host and base directory\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave_config\fR
.RS 4
.sp
Configuration file location for the slave walmgr\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBcompleted_wals\fR
.RS 4
.sp
Slave directory where archived WAL files are copied\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBpartial_wals\fR
.RS 4
.sp
Slave directory where incomplete WAL files are stored\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBfull_backup\fR
.RS 4
.sp
Slave directory where full backups are stored\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBconfig_backup\fR
.RS 4
.sp
Slave directory where configuration file backups are stored\&. Optional\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBloop_delay\fR
.RS 4
.sp
The frequency of syncdaemon updates\&. In record shipping mode only incremental updates are sent, so smaller interval can be used\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBuse_xlog_functions\fR
.RS 4
.sp
Use pg_xlog functions for record based shipping (available in 8\&.2 and up)\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBcompression\fR
.RS 4
.sp
If nonzero, a \-z flag is added to rsync cmdline\&. Will reduce network traffic at the cost of extra CPU time\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBperiodic_command\fR
.RS 4
.sp
Shell script to be executed at specified time interval\&. Can be used for synchronizing scripts, config files etc\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBcommand_interval\fR
.RS 4
.sp
How ofter to run periodic command script\&. In seconds, and only evaluated at log switch times\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBhot_standby ===\fR
.RS 4
.sp
Boolean\&. If set to true, walmgr setup will set wal_level to hot_standby (9\&.0 and newer)\&.
.RE
.SS "Sample master\&.ini"
.sp
.if n \{\
.RS 4
.\}
.nf
[wal\-master]
logfile              = master\&.log
pidfile              = master\&.pid
master_db            = dbname=template1
master_data          = /var/lib/postgresql/8\&.0/main
master_config        = /etc/postgresql/8\&.0/main/postgresql\&.conf
slave                = slave:/var/lib/postgresql/walshipping
completed_wals       = %(slave)s/logs\&.complete
partial_wals         = %(slave)s/logs\&.partial
full_backup          = %(slave)s/data\&.master
loop_delay           = 10\&.0
use_xlog_functions   = 1
compression          = 1
.fi
.if n \{\
.RE
.\}
.SS "Slave settings"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave_data\fR
.RS 4
.sp
Postgres data directory for the slave\&. This is where the restored backup is copied/moved\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave_config_dir\fR
.RS 4
.sp
Directory for postgres configuration files\&. If specified, "walmgr restore" attempts to restore configuration files from config_backup directory\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave_stop_cmd\fR
.RS 4
.sp
Script to stop postmaster on slave\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave_start_cmd\fR
.RS 4
.sp
Script to start postmaster on slave\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave\fR
.RS 4
.sp
Base directory for slave files (logs\&.complete, data\&.master etc)
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave_bin\fR
.RS 4
.sp
Specifies the location of postgres binaries (pg_controldata, etc)\&. Needed if they are not already in the PATH\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBcompleted_wals\fR
.RS 4
.sp
Directory where complete WAL files are stored\&. Also miscellaneous control files are created in this directory (BACKUPLOCK, STOP, PAUSE, etc\&.)\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBpartial_wals\fR
.RS 4
.sp
Directory where partial WAL files are stored\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBfull_backup\fR
.RS 4
.sp
Directory where full backups are stored\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBkeep_backups\fR
.RS 4
.sp
Number of backups to keep\&. Also all WAL files needed to bring earliest
.sp
backup up to date are kept\&. The backups are rotated before new backup is started, so at one point there is actually one less backup available\&.
.sp
It probably doesn\(cqt make sense to specify keep_backups if periodic backups are not performed \- the WAL files will pile up quickly\&.
.sp
Backups will be named data\&.master, data\&.master\&.0, data\&.master\&.1 etc\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBarchive_command\fR
.RS 4
.sp
Script to execute before rotating away the oldest backup\&. If it fails backups will not be rotated\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBslave_pg_xlog\fR
.RS 4
.sp
Set slave_pg_xlog to the directory on the slave where pg_xlog files get written to\&. On a restore to the slave walmgr\&.py will create a symbolic link from data/pg_xlog to this location\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBbackup_datadir\fR
.RS 4
.sp
Set backup_datadir to \fIno\fR to prevent walmgr\&.py from making a backup of the data directory when restoring to the slave\&. This defaults to \fIyes\fR
.RE
.SS "Sample slave\&.ini"
.sp
.if n \{\
.RS 4
.\}
.nf
[wal\-slave]
logfile              = slave\&.log
slave_data           = /var/lib/postgresql/8\&.0/main
slave_stop_cmd       = /etc/init\&.d/postgresql\-8\&.0 stop
slave_start_cmd      = /etc/init\&.d/postgresql\-8\&.0 start
slave                = /var/lib/postgresql/walshipping
completed_wals       = %(slave)s/logs\&.complete
partial_wals         = %(slave)s/logs\&.partial
full_backup          = %(slave)s/data\&.master
keep_backups         = 5
backup_datadir       = yes
.fi
.if n \{\
.RE
.\}