cmd_archiver.README

 
 pitrtools
 © COPYRIGHT Command Prompt, Inc.
 May 5, 2013


 cmd_archiver script is used in conjunction with PostgreSQL's native
 archive mode functionality to ship WAL segments to configured standby
 server to replay them.

 * Automatically ship log files to configured standby server
 * Enable/disable archiving without the need to restart PostgreSQL
 * Alert based on failures


Usage:

 cmd_archiver [options] arg1 arg2

 Options:
   -h, --help              Show this help message and exit
   -F FILE, --file=FILE    Archive file
   -C FILE, --config=FILE
                           The name of the archiver config file
   -I, --init              Initialize master environment


Naming conventions:

 Master server can be referred to also as archiver.
 Slave is often called standby.

 All the names are used interchangeably.


The process:

 pitrtools is just a wrapper around standard tools. If you are familiar
 with the process of setting up warm standby, there's not much new to
 learn about what pitrtools does. It simply attempts to make the process
 simpler, so the order of steps to take looks like this:


 On master server

	* Turn on archiving
	* Install helper scripts
	* cmd_archiver -C $CONFIG -I

 On standby server

	* cmd_standby -C $CONFIG -I 
	* cmd_standby -C $CONFIG -B 
	* cmd_standby -C $CONFIG -S


Prerequisites:

 SSH key-based authentication between the master and standby (both ways)
 for `postgres' user must be configured. Note, pitrtools was designed to
 run by `postgres' system user (in fact, any user but root), thus your
 SSH keys must be generated for `postgres' shell user.


Where to put pitrtools files:

 `postgres' user's home directory is a default recommended location, but
 it could be located anywhere as long as `postgres' user can access the
 files.

 Since pitrtools utilities are run by the `postgres' system user make
 sure that proper permissions and ownership are set. 

 For example

 $ chown -R postgres.postgres /var/lib/postgresql/pitrtools


Notes on configuration:

 On master server you need to enable archiving, to do that edit
 the postgresql.conf:


  archive_mode = on
  archive_command = '/var/lib/postgresql/pitrtools/bin/cmd_archiver -C /var/lib/postgresql/pitrtools/etc/cmd_archiver.ini -F %p'

 	-C takes the path to the config file
	-F takes the path (or file) of the archive. 


 Install helper scripts:

	$ psql -U postgres < /var/lib/postgresql/pitrtools/scripts/cmd_standby.sql

 	or

	$ psql -U postgres < /var/lib/postgresql/pitrtools/scripts/cmd_standby.92.sql (for PostgreSQL 9.2)

 After that, initialize master server environment:

	$ pitrtools/bin/cmd_archiver -C pitrtools/etc/cmd_archiver.ini -I

 You are done setting up master server.



More about options:

 --init

  Used to create the appropriate archive/queue file directories.



cmd_archiver.ini options:



 [DEFAULT]
 
 state: online					

	You can change the archiver to offline live, without touching PostgreSQL. 
	When taking the archiver offline, this will cause a nonzero exit status
	to PostgreSQL's archive command on each archive attempt. This is o.k. 
	because PostgreSQL will just queue up the archives while the archiver is
	offline. However, this can cause you to accidently fill up your postgres
	partition, so use with care.

 pgdata: /var/lib/postgresql/9.0/main

	The base database directory. This is the PGDATA on the archiving machine.


 r_archivedir: /var/lib/postgresql/archive

	Where to remotely copy archives. The remote archive directory on standby
	server, i.e. the directory that will accept all WAL segment files to be
	restored by the standby server.

 l_archivedir: /var/lib/postgresql/archive

	The local WAL archive directory. For every standby server a subdirectory
	named after hostname or IP address of the standby will be created. The 
	archiver will queue any WAL files that has failed to transfer to a 
	standby(s) under their respective subdirectories.

	This is also used when you want to archive all files locally. For
	example, if you are using an NFS mount for the standby server to get its
	files.

 includepath: /usr/bin:/bin:/usr/local/bin
 
        Directories to be included in search paths for executables; separated by colons

 rsync_flags: -z

	Optional flags to pass to rsync (compression, etc.)

 rsync_version = 2

	rsync version, run `rsync --version' to see what version you have.
	Expects 2 or 3, if running RHEL5 or similar it is likely 2.
	If you are running something that ships remotely modern software
	it will be 3.

 slaves: 192.168.3.1 or slaves: 192.168.3.1,192.168.4.1

	This is the IP address of the standby server. A hostname/FQDN would work
	as well. It must be a comma separated list for multiple slaves.

 user: postgres

	The UNIX shell user that is using rsync. This is the user that must have
	SSH keys configured between the master and standby.

 ssh_timeout: 10

	The SSH timeout. If it takes > timeout to begin the transfer, the archiver
	will provide a nonzero return and alert per notify_critical.

 queue_user: postgres

	The name of a Unix user that will be running cmd_archiver or
	cmd_queue.  The cmd_queue script will refuse to start if run
	by a different user.

 queue_wait: 5

	Number of seconds the cmd_queue process will sleep between
	tries to ship the accumulated WAL files to the slaves.

 max_queue_workers: 1

	The maximum allowed number of WAL-shipping rsync processes
	that cmd_queue will run in parallel.

 notify_ok: echo OK

	Everything is o.k. so what do we do? This should be full path to a script.
	For example, a nagios alert.

 notify_warning:  echo WARNING

	The same as OK but for warnings.

 notify_critical: echo CRITICAL

	The same as OK but for critical. This is total failure conditions.

 debug: off

	This will provide you a lot of noisy info to wherever you push your
	postgresql logging.

 ssh_debug: off

	Shows more information about SSH session, if set to on.