diff --git a/INSTALL b/INSTALL index 25708478..19e33efc 100644 --- a/INSTALL +++ b/INSTALL @@ -1,72 +1,128 @@ +====== repmgr ====== -To install repmgr and repmgrd follow this steps: +Installation Steps +================== -1) Extract the distribution tar file into the contrib directory of the - PostgreSQL distribution sources -2) Check your primary server is correctly configured -3) Write a suitable repmgr.conf for the node -4) Build repmgr programs -5) Set up trusted copy between postgres accounts (this is only useful for the - STANDBY CLONE case) -6) repmgrd additional steps +To install repmgr and repmgrd follow these steps: +1. Build repmgr programs -Extract the distribution tar file -================================= -cp repmgr.tar.gz ${postgresql_sources}/contrib/. -cd ${postgresql_sources}/contrib -tar xvzf repmgr-1.0.tar.gz +2. Check your primary server is correctly configured +3. Write a suitable repmgr.conf for the node + +4. Set up trusted copy between postgres accounts (this is only useful for + the ``STANDBY CLONE`` case) + +5. repmgrd additional steps + +Build repmgr programs +--------------------- + +Both methods of installation will place the binaries at the same location as your +postgres binaries, such as ``psql``. There are two ways to build it. The second +requires a full PostgreSQL source code tree to install the program directly into. +The first instead uses the PostgreSQL Extension System (PGXS) to install. For +this method to work, you will need the pg_config program available in your PATH. +In some distributions of PostgreSQL, this requires installing a separate +development package in addition to the basic server software. For example, +the RPM packages of PostgreSQL put ``pg_config`` into the ``postgresql-devel`` +package, not the main server one. + +Build repmgr programs - PGXS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using a packaged PostgreSQL build and have ``pg_config`` +available, the package can be built and installed using PGXS instead:: + + tar xvzf repmgr-1.0.tar.gz + cd repmgr + make USE_PGXS=1 + make USE_PGXS=1 install + +This is preferred to building from the ``contrib`` subdirectory of the main +source code tree. + +If you need to remove the source code temporary files from this directory, +that can be done like this:: + + make USE_PGXS=1 clean + +Using a full source code tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this method, the repmgr distribution is copied into the PostgreSQL source +code tree, assumed to be at the ${postgresql_sources} for this example. +The resulting subdirectory must be named ``contrib/repmgr``, without any +version number:: + + cp repmgr.tar.gz ${postgresql_sources}/contrib + cd ${postgresql_sources}/contrib + tar xvzf repmgr-1.0.tar.gz + cd repmgr + make + make install + +If you need to remove the source code temporary files from this directory, +that can be done like this:: + + make clean + +Confirm software was built correctly +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You should now find the repmgr programs available in the subdirectory where +the rest of your PostgreSQL installation is at. You can confirm the software +is available by checking its version:: + + repmgr --version + repmgrd --version + +Note that if you have a RPM install of PostgreSQL 9.0, the entire PostgreSQL +binary directory will not be in your PATH by default. You may need to include +the full path of the binary instead, such as:: + + /usr/pgsql-9.0/bin/repmgr --version + /usr/pgsql-9.0/bin/repmgr --version Check your primary server configuration -======================================= +--------------------------------------- -PostgreSQL should have been previously built and installed on the system +PostgreSQL should have been previously built and installed on the system. Here +is a sample of changes to the postgresql.conf file:: -postgresql.conf ---------------- -listen_addresses='*' -wal_level = 'hot_standby' -archive_mode = on -archive_command = 'cd .' # we can also use exit 0, anything that just do + listen_addresses='*' + wal_level = 'hot_standby' + archive_mode = on + archive_command = 'cd .' # we can also use exit 0, anything that just do # nothing -max_wal_senders = 10 -wal_keep_segments = 5000 # 80 GB required on pg_xlog -hot_standby = on + 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. -NOTE: Is preferred that you have a repmgr user and database and just give -access to that user, also if you put a password to the user you need to create -a .pgpass file -ie: +pg_hba.conf file. One possibility is to trust all connections from the +replication users from all addresses, such as:: -host repmgr repmgr 10.8.0.0/24 trust -host replication all 10.8.0.0/24 trust + host repmgr repmgr 10.8.0.0/24 trust + host replication all 10.8.0.0/24 trust +It is preferred that you have a repmgr user and database and just give +access to that user. If you give a password to the user, you need to create +a .pgpass file for them as well to allow automatic login. Write a suitable repmgr.conf -============================ +---------------------------- It should have these three parameters: -1) cluster: A string (single quoted) that identify the cluster we are on -2) node: An integer that identify our node in the cluster -3) conninfo: A string (single quoted) that teach repmgr how to connect to this - node +1. cluster: A string (single quoted) that identify the cluster we are on +2. node: An integer that identify our node in the cluster -Build repmgr programs -===================== - -make repmgr -make repmgrd - -make install (this will put the binaries on the same location as your postgres -binaries) - +3. conninfo: A string (single quoted) that teach repmgr how to connect to this node Set up trusted copy between postgres accounts --------------------------------------------- @@ -76,7 +132,7 @@ to work, the postgres accounts on each system need to be able to access files on their partner node without a password. First generate a ssh key, using an empty passphrase, and copy the resulting -keys and a maching authorization file to a privledged user on the other system: +keys and a maching authorization file to a privledged user on the other system:: [postgres@db1]$ ssh-keygen -t rsa Generating public/private rsa key pair. @@ -104,12 +160,11 @@ user's account:: Now test that ssh in both directions works (you may have to accept some new known hosts in the process) - repmgrd additional steps ======================== To use the repmgrd (repmgr daemon) to monitor standby so we know how is going the replication and how far they are from primary, you need to execute the -repmgr.sql script in the postgres database. +``repmgr.sql`` script in the postgres database. You also need to add a row for every node in the repl_node table diff --git a/Makefile b/Makefile index cf3124b0..655467ac 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,8 @@ repmgr_OBJS = dbutils.o check_dir.o config.o repmgr.o PG_CPPFLAGS = -I$(libpq_srcdir) PG_LIBS = $(libpq_pgport) +all: repmgrd repmgr + repmgrd: $(repmgrd_OBJS) $(CC) $(CFLAGS) $(repmgrd_OBJS) $(PG_LIBS) $(LDFLAGS) $(LDFLAGS_EX) $(LIBS) -o repmgrd diff --git a/README b/README deleted file mode 100644 index fce962d0..00000000 --- a/README +++ /dev/null @@ -1,156 +0,0 @@ -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 or -then use the -f option to indicate where the repmgr.conf is. -Doesn't need any additional arguments: - -./repmgr standby promote - -That will restart your standby postgresql service - - -* standby follow - -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 or -then use the -f option to indicate where the repmgr.conf is. - -./repmgr standby follow - - -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 -f /home/postgres/repmgr.conf standby promote - -which makes node2 the new master, we then run on node3: -repmgr standby follow - -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. diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..22cf5e35 --- /dev/null +++ b/README.rst @@ -0,0 +1,160 @@ +===================================================== +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 or + then use the -f option to indicate where the repmgr.conf is. + Doesn't need any additional arguments:: + + ./repmgr standby promote + + That will restart your standby postgresql service + +* standby follow + + * 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 or + then use the -f option to indicate where the repmgr.conf is. Example:: + + ./repmgr standby follow + +PREREQUISITES +============= + +Primary must be configured with the following in its ``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``, such as:: + + 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 -f /home/postgres/repmgr.conf standby promote + +Which makes node2 the new master. We then run on node3:: + + repmgr standby follow + +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`` is looked for in the directory repmgrd or repmgr exists. +The configuration file should have 3 lines: + +* cluster : the 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. +