diff --git a/doc/cloning-standbys.sgml b/doc/cloning-standbys.sgml index 2c1fe095..a30add59 100644 --- a/doc/cloning-standbys.sgml +++ b/doc/cloning-standbys.sgml @@ -5,8 +5,8 @@ - cloning - from Barman + cloning + from Barman Cloning a standby from Barman @@ -192,7 +192,7 @@ - Replication slots must be enabled in postgresql.conf` by + Replication slots must be enabled in postgresql.conf by setting the parameter max_replication_slots to at least the number of expected standbys (changes to this parameter require a server restart). diff --git a/doc/configuration-file-settings.sgml b/doc/configuration-file-settings.sgml index 7d868dde..ebf8f17d 100644 --- a/doc/configuration-file-settings.sgml +++ b/doc/configuration-file-settings.sgml @@ -1,4 +1,9 @@ + + repmgr.conf + settings + + Configuration file settings Each repmgr.conf file must contain the following parameters: diff --git a/doc/configuration-file.sgml b/doc/configuration-file.sgml index 5b87dbcc..9c2c1a84 100644 --- a/doc/configuration-file.sgml +++ b/doc/configuration-file.sgml @@ -1,4 +1,9 @@ + + repmgr.conf + location + + Configuration file location repmgr and repmgrd @@ -7,7 +12,7 @@ repmgr.conf must contain a number of required parameters, including the database connection string for the local node and the location of its data directory; other values will be inferred from defaults if - not explicitly supplied. See section `configuration file parameters` + not explicitly supplied. See section for more details. @@ -15,7 +20,7 @@ The configuration file will be searched for in the following locations: - a configuration file specified by the `-f/--config-file` command line option + a configuration file specified by the -f/--config-file command line option @@ -37,10 +42,10 @@ - Note that if a file is explicitly specified with -f/--config-file, - an error will be raised if it is not found or not readable and no attempt will be made to + Note that if a file is explicitly specified with -f/--config-file, + an error will be raised if it is not found or not readable, and no attempt will be made to check default locations; this is to prevent repmgr unexpectedly - reading the wrong file. + reading the wrong configuraton file. diff --git a/doc/event-notifications.sgml b/doc/event-notifications.sgml index 46b327d3..3ab5cadd 100644 --- a/doc/event-notifications.sgml +++ b/doc/event-notifications.sgml @@ -1,12 +1,12 @@ Event Notifications - Each time `repmgr` or `repmgrd` perform a significant event, a record - of that event is written into the `repmgr.events` table together with + Each time &repmgr; or repmgrd perform a significant event, a record + of that event is written into the repmgr.events table together with a timestamp, an indication of failure or success, and further details if appropriate. This is useful for gaining an overview of events affecting the replication cluster. However note that this table has - advisory character and should be used in combination with the `repmgr` + advisory character and should be used in combination with the &repmgr; and PostgreSQL logs to obtain details of any events. @@ -28,8 +28,8 @@ Additionally, event notifications can be passed to a user-defined program or script which can take further action, e.g. send email notifications. - This is done by setting the `event_notification_command` parameter in - `repmgr.conf`. + This is done by setting the event_notification_command parameter in + repmgr.conf. This parameter accepts the following format placeholders: diff --git a/doc/follow-new-primary.sgml b/doc/follow-new-primary.sgml index d1e8f65f..75af0955 100644 --- a/doc/follow-new-primary.sgml +++ b/doc/follow-new-primary.sgml @@ -1,4 +1,9 @@ + + Following a new primary + repmgr standby follow + + Following a new primary Following the failure or removal of the replication cluster's existing primary @@ -22,7 +27,8 @@ - The standby is now replicating from the new primary and `repmgr cluster show` + The standby is now replicating from the new primary and + repmgr cluster show output reflects this: $ repmgr -f /etc/repmgr.conf cluster show diff --git a/doc/install-packages.sgml b/doc/install-packages.sgml index 727a5009..7ef235a0 100644 --- a/doc/install-packages.sgml +++ b/doc/install-packages.sgml @@ -1,32 +1,47 @@ Installing &repmgr; from packages -We recommend installing `repmgr` using the available packages for your -system. + We recommend installing &repmgr; using the available packages for your + system. - RedHat/Fedora/CentOS - - RPM packages for `repmgr` are available via Yum through - the PostgreSQL Global Development Group RPM repository - ( http://yum.postgresql.org/). - Follow the instructions for your distribution (RedHat, CentOS, - Fedora, etc.) and architecture as detailed at yum.postgresql.org. - - - 2ndQuadrant also provides its own RPM packages which are made available - at the same time as each `repmgr` release, as it can take some days for - them to become available via the main PGDG repository. See here for details: - http://repmgr.org/yum-repository.html - - - - Debian/Ubuntu - .deb packages for `repmgr` are available from the - PostgreSQL Community APT repository (http://apt.postgresql.org/ ). - Instructions can be found in the APT section of the PostgreSQL Wiki - (https://wiki.postgresql.org/wiki/Apt ). + + + installation + on Redhat/CentOS/Fedora etc. + + + RedHat/Fedora/CentOS + + RPM packages for &repmgr; are available via Yum through + the PostgreSQL Global Development Group RPM repository + (http://yum.postgresql.org/). + Follow the instructions for your distribution (RedHat, CentOS, + Fedora, etc.) and architecture as detailed there. + + + 2ndQuadrant also provides its + own RPM packages which are made available + at the same time as each &repmgr; release, as it can take some days for + them to become available via the main PGDG repository. See here for details: + http://repmgr.org/yum-repository.html + + + + + installation + on Debian/Ubuntu etc. + + + Debian/Ubuntu + .deb packages for &repmgr; are available from the + PostgreSQL Community APT repository (http://apt.postgresql.org/). + Instructions can be found in the APT section of the PostgreSQL Wiki + (https://wiki.postgresql.org/wiki/Apt). + + + diff --git a/doc/install-requirements.sgml b/doc/install-requirements.sgml index d9cd6191..00d02a66 100644 --- a/doc/install-requirements.sgml +++ b/doc/install-requirements.sgml @@ -7,17 +7,14 @@ - From version 4.0, repmgr is compatible with all PostgreSQL versions from 9.4, including PostgreSQL 10. - - - PostgreSQL 9.3 is supported by repmgr 3.3. + From version 4.0, repmgr is compatible with all PostgreSQL versions from 9.3, including PostgreSQL 10. + Note that some &repmgr; functionality is not available in PostgreSQL 9.3 and PostgreSQL 9.4. - -If upgrading from `repmgr 3`, please see the separate upgrade guide -`doc/upgrading-from-repmgr3.md`. - + + If upgrading from &repmgr; 3.x, please see the section . + @@ -26,42 +23,44 @@ If upgrading from `repmgr 3`, please see the separate upgrade guide - `repmgr` must be installed on each server in the replication cluster. + &repmgr; must be installed on each server in the replication cluster. If installing repmgr from packages, the package version must match the PostgreSQL version. If installing from source, repmgr must be compiled against the same major version. - A dedicated system user for `repmgr` is *not* required; as many `repmgr` and - `repmgrd` actions require direct access to the PostgreSQL data directory, - these commands should be executed by the `postgres` user. + A dedicated system user for &repmgr; is *not* required; as many &repmgr; and + repmgrd actions require direct access to the PostgreSQL data directory, + these commands should be executed by the postgres user. - - Passwordless `ssh` connectivity between all servers in the replication cluster + Passwordless ssh connectivity between all servers in the replication cluster is not required, but is necessary in the following cases: - if you need `repmgr` to copy configuration files from outside the PostgreSQL - data directory (in which case `rsync` is also required) + if you need &repmgr; to copy configuration files from outside the PostgreSQL + data directory (in which case rsync is also required) - to perform switchover operations + to perform switchover operations - when executing `repmgr cluster matrix` and `repmgr cluster crosscheck` + + when executing repmgr cluster matrix + and repmgr cluster crosscheck + - We recommend using a session multiplexer utility such as `screen` or - `tmux` when performing long-running actions (such as cloning a database) - on a remote server - this will ensure the `repmgr` action won't be prematurely - terminated if your `ssh` session to the server is interrupted or closed. + We recommend using a session multiplexer utility such as screen or + tmux when performing long-running actions (such as cloning a database) + on a remote server - this will ensure the &repmgr; action won't be prematurely + terminated if your ssh session to the server is interrupted or closed. diff --git a/doc/install-source.sgml b/doc/install-source.sgml index b21d6aa8..dbb3aaca 100644 --- a/doc/install-source.sgml +++ b/doc/install-source.sgml @@ -1,4 +1,9 @@ + + installation + from source + + Installing &repmgr; from source @@ -132,7 +137,8 @@ ./configure && make install - Ensure `pg_config` for the target PostgreSQL version is in `$PATH`. + Ensure pg_config for the target PostgreSQL version is in + $PATH. diff --git a/doc/install.sgml b/doc/install.sgml index 52b827e1..ce85eb19 100644 --- a/doc/install.sgml +++ b/doc/install.sgml @@ -1,4 +1,8 @@ + + installation + + Installation diff --git a/doc/overview.sgml b/doc/overview.sgml index a0f511a5..47e057e0 100644 --- a/doc/overview.sgml +++ b/doc/overview.sgml @@ -5,6 +5,11 @@ This chapter provides a high-level overview of repmgr's components and functionality. + + + concepts + + Concepts @@ -15,13 +20,13 @@ streaming replication. - The following terms are used throughout the `repmgr` documentation. + The following terms are used throughout the &repmgr; documentation. replication cluster - In the `repmgr` documentation, "replication cluster" refers to the network + In the &repmgr; documentation, "replication cluster" refers to the network of PostgreSQL servers connected by streaming replication. @@ -31,7 +36,7 @@ node - A node is a server within a replication cluster. + A node is a single PostgreSQL server within a replication cluster. @@ -41,7 +46,7 @@ The node a standby server connects to, in order to receive streaming replication. - This is either the primary server or in the case of cascading replication, another + This is either the primary server, or in the case of cascading replication, another standby. @@ -52,7 +57,7 @@ This is the action which occurs if a primary server fails and a suitable standby - is promoted as the new primary. The `repmgrd` daemon supports automatic failover + is promoted as the new primary. The repmgrd daemon supports automatic failover to minimise downtime. @@ -66,7 +71,7 @@ it's necessary to take a primary server offline; in this case a controlled switchover is necessary, whereby a suitable standby is promoted and the existing primary removed from the replication cluster in a controlled manner. - The `repmgr` command line client provides this functionality. + The &repmgr; command line client provides this functionality. @@ -88,7 +93,7 @@ Components - `repmgr` is a suite of open-source tools to manage replication and failover + &repmgr; is a suite of open-source tools to manage replication and failover within a cluster of PostgreSQL servers. It supports and enhances PostgreSQL's built-in streaming replication, which provides a single read/write primary server and one or more read-only standbys containing near-real time copies of the primary @@ -147,11 +152,12 @@ Repmgr user and metadata - In order to effectively manage a replication cluster, `repmgr` needs to store + In order to effectively manage a replication cluster, &repmgr; needs to store information about the servers in the cluster in a dedicated database schema. - This schema is automatically by the `repmgr` extension, which is installed - during the first step in initialising a `repmgr`-administered cluster - (`repmgr primary register`) and contains the following objects: + This schema is automatically by the &repmgr; extension, which is installed + during the first step in initialising a &repmgr;-administered cluster + (repmgr primary register) + and contains the following objects: Tables @@ -159,14 +165,15 @@ - repmgr.events: records events of interest + repmgr.events: records events of interest - repmgr.nodes: connection and status information for each server in the + repmgr.nodes: connection and status information for each server in the replication cluster - repmgr.monitoring_history: historical standby monitoring information written by `repmgrd` + repmgr.monitoring_history: historical standby monitoring information + written by repmgrd @@ -178,12 +185,12 @@ - repmgr.show_nodes: based on the table `repl_nodes`, additionally showing the - name of the server's upstream node + repmgr.show_nodes: based on the table repmgr.nodes, additionally showing the + name of the server's upstream node - repmgr.replication_status: when `repmgrd`'s monitoring is enabled, shows current monitoring - status for each standby. + repmgr.replication_status: when repmgrd's monitoring is enabled, shows + current monitoring status for each standby. @@ -193,16 +200,16 @@ - The `repmgr` metadata schema can be stored in an existing database or in its own - dedicated database. Note that the `repmgr` metadata schema cannot reside on a database - server which is not part of the replication cluster managed by `repmgr`. + The &repmgr; metadata schema can be stored in an existing database or in its own + dedicated database. Note that the &repmgr; metadata schema cannot reside on a database + server which is not part of the replication cluster managed by &repmgr;. - A database user must be available for `repmgr` to access this database and perform + A database user must be available for &repmgr; to access this database and perform necessary changes. This user does not need to be a superuser, however some operations - such as initial installation of the `repmgr` extension will require a superuser + such as initial installation of the &repmgr; extension will require a superuser connection (this can be specified where required with the command line option - `--superuser`). + --superuser). diff --git a/doc/repmgr-cluster-matrix.sgml b/doc/repmgr-cluster-matrix.sgml index d37d1406..2f57060a 100644 --- a/doc/repmgr-cluster-matrix.sgml +++ b/doc/repmgr-cluster-matrix.sgml @@ -9,7 +9,7 @@ repmgr cluster matrix requires a valid repmgr.conf - file on each node. Additionally passwordless `ssh` connections are required between + file on each node. Additionally passwordless ssh connections are required between all nodes. @@ -46,7 +46,7 @@ The other two nodes are up; the corresponding rows have x in the column corresponding to node3, meaning that inbound connections to - that node have failed, and `*` in the columns corresponding to + that node have failed, and * in the columns corresponding to node1 and node2, meaning that inbound connections to these nodes have succeeded. diff --git a/doc/repmgr-cluster-show.sgml b/doc/repmgr-cluster-show.sgml index f80e3dfa..823c5668 100644 --- a/doc/repmgr-cluster-show.sgml +++ b/doc/repmgr-cluster-show.sgml @@ -32,7 +32,7 @@ --verbose mode. - The `cluster show` command accepts an optional parameter --csv, which + cluster show accepts an optional parameter --csv, which outputs the replication cluster's status in a simple CSV format, suitable for parsing by scripts: diff --git a/doc/repmgr-standby-clone.sgml b/doc/repmgr-standby-clone.sgml index 76f7e52b..1908f285 100644 --- a/doc/repmgr-standby-clone.sgml +++ b/doc/repmgr-standby-clone.sgml @@ -58,7 +58,7 @@ When initially cloning a standby, you will need to ensure that all required WAL files remain available while the cloning is taking - place. To ensure this happens when using the default `pg_basebackup` method, + place. To ensure this happens when using the default pg_basebackup method, &repmgr; will set pg_basebackup's --xlog-method parameter to stream, which will ensure all WAL files generated during the cloning process are diff --git a/doc/switchover.sgml b/doc/switchover.sgml index 4a07a4a1..2239572c 100644 --- a/doc/switchover.sgml +++ b/doc/switchover.sgml @@ -1,4 +1,9 @@ + + + switchover + + Performing a switchover with repmgr A typical use-case for replication is a combination of primary and standby @@ -39,7 +44,7 @@ Please also read carefully the sections and - `Caveats` below. + below. @@ -81,7 +86,7 @@ If WAL file archiving is set up, check that there is no backlog of files waiting to be archived, as PostgreSQL will not finally shut down until all these have been archived. If there is a backlog exceeding archive_ready_warning WAL files, - `repmgr` will emit a warning before attempting to perform a switchover; you can also check + &repmgr; will emit a warning before attempting to perform a switchover; you can also check manually with repmgr node check --archive-ready. @@ -198,7 +203,7 @@ - We hope to remove some of these restrictions in future versions of `repmgr`. + We hope to remove some of these restrictions in future versions of &repmgr;. diff --git a/doc/upgrading-repmgr.sgml b/doc/upgrading-repmgr.sgml index d3c9ef09..cc3d0500 100644 --- a/doc/upgrading-repmgr.sgml +++ b/doc/upgrading-repmgr.sgml @@ -1,5 +1,11 @@ + + + upgrading + + Upgrading repmgr + &repmgr; is updated regularly with point releases (e.g. 4.0.1 to 4.0.2) containing bugfixes and other minor improvements. Any substantial new @@ -17,8 +23,13 @@ file used by repmgrd; check the release notes for details. - - Upgrading from repmgr 3 + + + upgrading + from repmgr 3.x + + + Upgrading from repmgr 3.x The upgrade process consists of two steps: @@ -162,8 +173,8 @@ repmgr binary. - Install repmgr4; any repmgr3 packages should be uninstalled - (if not automatically uninstalled already). + Install repmgr 4 packages; any repmgr 3.x packages + should be uninstalled (if not automatically uninstalled already by your packaging system). Upgrading from repmgr 3.1.1 or earlier @@ -203,7 +214,8 @@ there must be only one schema matching repmgr_% in the - database, otherwise this step may not work. + database, otherwise this step may not work. +