repmgr daemon
==================================================================
repmgr: Replication Manager for PostgreSQL's clusters
=====================================================

Introduction
============

PostgreSQL 9.0 allow us to have replicated hot standby servers 
which we can query and/or use for high availability.

While the main components of the feature are included with
PostgreSQL, the user is expected to manage the high availability
part of it.

repmgr allows you to monitor and manage your replicated PostgreSQL
databases as a single cluster.

repmgr works in two components:
* repmgr: command program that performs tasks and then exits
* repmgrd: management and monitoring daemon that watches cluster


COMMANDS
========

None of this commands need the repmgr.conf file but they need to be able to
connect to the remote and local database.

You can teach it which is the remote database by using the -h parameter or 
as a last parameter in standby clone and standby follow. If you need to specify
a port different then the default 5432 you can specify a -p parameter.
Standby is always considered as localhost and a second -p parameter will indicate
its port if is different from the default one.

* master register

Registers a master in a cluster, it needs to be executed before any node is 
registered

* standby register

Registers a standby in a cluster, it needs to be executed before any repmgrd 
is executed

* standby clone [node to be cloned] 

Backup via rsync the data directory of the primary. And creates the recovery file
we need to start a new hot standby server.
It doesn't need the repmgr.conf so it can be executed anywhere in the new node.
So, you can step where you want your new data directory and execute:

./repmgr standby clone 10.68.1.161
or from wherever you are
./repmgr -D /path/to/new/data/directory standby clone 10.68.1.161

That will make a backup of the primary then you only need to execute:

pg_ctl -D /your_data_directory_path start


* standby promote 

Allows manual promotion of a specific standby into a new primary in the event of a failover
This needs to be executed on the same directory where the repmgr.conf is in the standby.
Doesn't need any additional arguments:

./repmgr standby promote

That will restart your standby postgresql service


* standby follow [node to be followed] 

Allows the standby to re-point itself to a new primary indicated as a parameter.
This needs to be executed on the same directory where the repmgr.conf is in the standby.

./repmgr standby follow 10.68.1.162


PRE-REQUISITES
==============

Primary must be configured with

postgresql.conf
---------------
listen_addresses='*'
wal_level = 'hot_standby'
archive_mode = on
archive_command = 'cd .'
max_wal_senders = 10
wal_keep_segments = 5000      # 80 GB required on pg_xlog
hot_standby = on

Also you need to add the machines that will participate in the cluster in pg_hba.conf.
ie:
host     all              all         10.8.0.0/24         trust
host     replication      all         10.8.0.0/24         trust


EXAMPLES
========

Suppose we have 3 nodes: node1 (the master), node2 and node3

To make node2 and node3 be standbys of node1, execute this on both nodes (node2 and node3):
repmgr -D /var/lib/postgresql/9.0 standby clone node1

If we lose node1 we can run on node2:
repmgr standby promote 

which makes node2 the new master, we then run on node3:
repmgr standby follow node2

to make node3 follow node2 (rather than node1)

If now we want to add a new node we can a prepare a new server (node4) and run: 
repmgr -D /var/lib/postgresql/9.0 standby clone node2

NOTE: you need to have PGDIR/bin in your path, if you don't want that as a 
permanent setting you can do it this way:

PATH=$PGDIR/bin:$PATH repmgr standby promote


CONFIGURATION FILE
==================

repmgr.conf: This is looked for in the directory repmgrd or repmgr exists
The configuration file should have 3 lines:
cluster : tha name of this cluster
node    : specify the number of this node inside the cluster
conninfo: specify how we can connect to this node's PostgreSQL service 


REPMGR DAEMON
=============

It reads the repmgr.conf file in current directory or as indicated with -f 
parameter looks if the standby is in repl_nodes and if it is not add it.

Before you can run the repmgr daemon (repmgrd) you need to register a master
and at least a standby in a cluster, for that you need to use the MASTER 
REGISTER and STANDBY REGISTER commands.

For example, following last example and assuming that repmgr.conf is in postgres
home directory you will run this on the master:

repmgr -f /home/postgres/repmgr.conf master register

and the same in the standby.

The repmgr daemon creates 2 connections: one to master and other to standby.