From 2e9f4aa30f5d6a9a33a1ac49334b79a150776811 Mon Sep 17 00:00:00 2001 From: Ian Barwick Date: Wed, 16 Jul 2014 07:57:00 +0900 Subject: [PATCH] Convert QUICKSTART file to markdown format Less effort for more consistent formatting (at least the way github renders it). --- QUICKSTART.rst => QUICKSTART.md | 92 ++++++++++++++++----------------- 1 file changed, 45 insertions(+), 47 deletions(-) rename QUICKSTART.rst => QUICKSTART.md (81%) diff --git a/QUICKSTART.rst b/QUICKSTART.md similarity index 81% rename from QUICKSTART.rst rename to QUICKSTART.md index 26a73924..45ed38a9 100644 --- a/QUICKSTART.rst +++ b/QUICKSTART.md @@ -1,4 +1,3 @@ -======================== repmgr: Quickstart guide ======================== @@ -13,12 +12,12 @@ setup and Linux/UNIX system administration. For a more detailed tutorial covering setup on a variety of different systems, see the README.rst file. Conceptual Overview -=================== +------------------- repmgr provides two binaries: - - ``repmgr``: a command-line client to manage replication and repmgr configuration - - ``repmgrd``: an optional daemon process which runs on standby nodes to monitor + - `repmgr`: a command-line client to manage replication and repmgr configuration + - `repmgrd`: an optional daemon process which runs on standby nodes to monitor replication and node status Each PostgreSQL node requires a repmgr configuration file; additionally @@ -28,7 +27,7 @@ database. Requirements -============ +------------ repmgr works with PostgreSQL 9.0 and later. All server nodes must be running the same PostgreSQL major version, and preferably should be running the same minor @@ -39,7 +38,7 @@ PostgreSQL. rsync must also be installed. Installation -============ +------------ repmgr must be installed on each PostgreSQL server node. @@ -62,15 +61,15 @@ repmgr must be installed on each PostgreSQL server node. Configuration ------------- -* Server configuration +### Server configuration -Password-less SSH logins must be enabled for the database system user (typically ``postgres``) +Password-less SSH logins must be enabled for the database system user (typically `postgres`) between all server nodes to enable repmgr to copy required files. -* PostgreSQL configuration +### PostgreSQL configuration The master PostgreSQL node needs to be configured for replication with the -following settings:: +following settings: wal_level = 'hot_standby' # minimal, archive, hot_standby, or logical archive_mode = on # allows archiving to be done @@ -80,7 +79,7 @@ following settings:: hot_standby = on # "on" allows queries during recovery Note that repmgr expects a default of 5000 wal_keep_segments, although this -value can be overridden when executing the ``repmgr`` client. +value can be overridden when executing the `repmgr` client. Additionally, repmgr requires a dedicated PostgreSQL superuser account and a database in which to store monitoring and replication data. The @@ -88,10 +87,10 @@ database can in principle be any database, including the default postgres one, however it's probably advisable to create a dedicated repmgr database. -* repmgr configuration +### repmgr configuration - Each PostgreSQL node requires a repmgr configuration file containing - identification and database connection information:: +Each PostgreSQL node requires a repmgr configuration file containing +identification and database connection information: cluster=test node=1 @@ -99,14 +98,14 @@ one, however it's probably advisable to create a dedicated repmgr database. conninfo='host=repmgr_node1 user=repmgr_usr dbname=repmgr_db' pg_bindir=/path/to/postgres/bin -* ``cluster``: common name for the replication cluster; this must be the same on all nodes -* ``node``: a unique, abitrary integer identifier -* ``name``: a unique, human-readable name -* ``conninfo``: a standard conninfo string enabling repmgr to connect to the +* `cluster`: common name for the replication cluster; this must be the same on all nodes +* `node`: a unique, abitrary integer identifier +* `name`: a unique, human-readable name +* `conninfo`: a standard conninfo string enabling repmgr to connect to the control database; user and name must be the same on all nodes, while other - parameters such as port may differ. The ``host`` parameter *must* be a hostname + parameters such as port may differ. The `host` parameter *must* be a hostname resolvable by all nodes on the cluster. -* ``pg_bindir``: (optional) location of PostgreSQL binaries, if not in the default $PATH +* `pg_bindir`: (optional) location of PostgreSQL binaries, if not in the default $PATH Note that the configuration file should not be stored inside the PostgreSQL data directory. @@ -117,13 +116,12 @@ about each node are inserted into the repmgr database (for details see below). Replication setup and monitoring -================================ +-------------------------------- For the purposes of this guide, we'll assume the database user will be -``repmgr_usr`` and the database will be ``repmgr_db``, and that the following +`repmgr_usr` and the database will be `repmgr_db`, and that the following environment variables are set on each node: - - $HOME: the PostgreSQL system user's home directory - $PGDATA: the PostgreSQL data directory @@ -133,14 +131,14 @@ Master setup 1. Configure PostgreSQL - - create user and database:: + - create user and database: CREATE ROLE repmgr_usr LOGIN SUPERUSER; CREATE DATABASE repmgr_db OWNER repmgr_usr; - configure postgresql.conf for replication (see above) - - update pg_hba.conf:: + - update pg_hba.conf: host repmgr_usr repmgr_db 192.168.1.0/24 trust host replication all 192.168.1.0/24 trust @@ -148,7 +146,7 @@ Master setup Restart the PostgreSQL server after making these changes. -2. Create the repmgr configuration file:: +2. Create the repmgr configuration file: $ cat $HOME/repmgr/repmgr.conf cluster=test @@ -157,7 +155,7 @@ Master setup conninfo='host=repmgr_node1 user=repmgr_usr dbname=repmgr_db' pg_bindir=/path/to/postgres/bin -3. Register the master node with repmgr:: +3. Register the master node with repmgr: $ repmgr -f $HOME/repmgr/repmgr.conf --verbose master register [2014-07-04 10:43:42] [INFO] repmgr mgr connecting to master database @@ -170,7 +168,7 @@ Master setup Slave/standby setup ------------------- -1. Use repmgr to clone the master:: +1. Use repmgr to clone the master: $ repmgr -f $HOME/repmgr/repmgr.conf -D $PGDATA -d repmgr_db -U repmgr_usr -R postgres --verbose standby clone 192.168.1.2 Opening configuration file: ./repmgr.conf @@ -189,14 +187,14 @@ Slave/standby setup [2014-07-04 10:53:21] [NOTICE] for example : /etc/init.d/postgresql start -R is the database system user on the master node. At this point it does not matter - if the ``repmgr.conf`` file is not found. + if the `repmgr.conf` file is not found. This will clone the PostgreSQL database files from the master, and additionally - create an appropriate ``recovery.conf`` file. + create an appropriate `recovery.conf` file. 2. Start the PostgreSQL server -3. Create the repmgr configuration file:: +3. Create the repmgr configuration file: $ cat $HOME/repmgr/repmgr.conf cluster=test @@ -205,7 +203,7 @@ Slave/standby setup conninfo='host=repmgr_node2 user=repmgr_usr dbname=repmgr_db' pg_bindir=/path/to/postgres/bin -4. Register the master node with repmgr:: +4. Register the master node with repmgr: $ repmgr -f $HOME/repmgr/repmgr.conf --verbose standby register Opening configuration file: /path/to/repmgr/repmgr.conf @@ -222,19 +220,19 @@ Slave/standby setup Monitoring ---------- -``repmgrd`` is a management and monitoring daemon which runs on standby nodes -and which and can automate remote actions. It can be started simply with e.g.:: +`repmgrd` is a management and monitoring daemon which runs on standby nodes +and which and can automate remote actions. It can be started simply with e.g.: repmgrd -f $HOME/repmgr/repmgr.conf --verbose > $HOME/repmgr/repmgr.log 2>&1 -or alternatively:: +or alternatively: repmgrd -f $HOME/repmgr/repmgr.conf --verbose --monitoring-history > $HOME/repmgr/repmgrd.log 2>&1 which will track advance or lag of the replication in every standby in the -``repl_monitor`` table. +`repl_monitor` table. -Example log output:: +Example log output: [2014-07-04 11:55:17] [INFO] repmgrd Connecting to database 'host=localhost user=repmgr_usr dbname=repmgr_db' [2014-07-04 11:55:17] [INFO] repmgrd Connected to database, checking its state @@ -250,38 +248,38 @@ Example log output:: Failover -------- -To promote a standby to master, on the standby execute e.g.:: +To promote a standby to master, on the standby execute e.g.: repmgr -f $HOME/repmgr/repmgr.conf --verbose standby promote repmgr will attempt to connect to the current master to verify that it is not available (if it is, repmgr will not promote the standby). -Other standby servers need to be told to follow the new master with:: +Other standby servers need to be told to follow the new master with: repmgr -f $HOME/repmgr/repmgr.conf --verbose standby follow -See file ``autofailover_quick_setup.rst`` for details on setting up +See file `autofailover_quick_setup.rst` for details on setting up automated failover. repmgr database schema -====================== +---------------------- repmgr creates a small schema for its own use in the database specified in each node's conninfo configuration parameter. This database can in principle -be any database. The schema name is the global ``cluster`` name prefixed -with ``repmgr_``, so for the example setup above the schema name is -``repmgr_test``. +be any database. The schema name is the global `cluster` name prefixed +with `repmgr_`, so for the example setup above the schema name is +`repmgr_test`. The schema contains two tables: -* ``repl_nodes`` +* `repl_nodes` stores information about all registered servers in the cluster -* ``repl_monitor`` +* `repl_monitor` stores monitoring information about each node -and one view, ``repl_status``, which summarizes the latest monitoring information +and one view, `repl_status`, which summarizes the latest monitoring information for each node.