github/repmgr
1
0
Fork 0
mirror of https://github.com/EnterpriseDB/repmgr.git synced 2026-03-26 00:26:30 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

docs: convert command reference sections to <refentry> format

Browse Source 
Note that most entries still need a bit more tidying up, consistent structuring,
provision of more examples etc.
This commit is contained in:
Ian Barwick
2017-10-31 11:27:13 +09:00
parent 11d856a1ec
commit c3a1969f55
16 changed files with 707 additions and 409 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
doc/repmgr-cluster-cleanup.sgml
View File

@@ -1,23 +1,41 @@
<chapter id="repmgr-cluster-cleanup" xreflabel="repmgr cluster cleanup"> <refentry id="repmgr-cluster-cleanup">
<indexterm> <indexterm>
<primary>repmgr cluster cleanup</primary> <primary>repmgr cluster cleanup</primary>
</indexterm> </indexterm>
<title>repmgr cluster cleanup</title> <refmeta>
<para> <refentrytitle>repmgr cluster cleanup</refentrytitle>
Purges monitoring history from the <literal>repmgr.monitoring_history</literal> table to </refmeta>
prevent excessive table growth. Use the <literal>-k/--keep-history</literal> to specify the
number of days of monitoring history to retain. This command can be used <refnamediv>
manually or as a cronjob. <refname>repmgr cluster cleanup</refname>
</para> <refpurpose>purge monitoring history</refpurpose>
<para> </refnamediv>
This command requires a valid <filename>repmgr.conf</filename> file for the node on which it is
executed; no additional arguments are required. <refsect1>
</para> <title>Description</title>
<note> <para>
<simpara> Purges monitoring history from the <literal>repmgr.monitoring_history</literal> table to
Monitoring history will only be written if <application>repmgrd</application> is active, and prevent excessive table growth. Use the <literal>-k/--keep-history</literal> to specify the
<varname>monitoring_history</varname> is set to <literal>true</literal> in number of days of monitoring history to retain. This command can be used
<filename>repmgr.conf</filename>. manually or as a cronjob.
</simpara> </para>
</note> </refsect1>
</chapter>
<refsect1>
<title>Usage</title>
<para>
This command requires a valid <filename>repmgr.conf</filename> file for the node on which it is
executed; no additional arguments are required.
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Monitoring history will only be written if <application>repmgrd</application> is active, and
<varname>monitoring_history</varname> is set to <literal>true</literal> in
<filename>repmgr.conf</filename>.
</para>
</refsect1>
</refentry>

48
doc/repmgr-cluster-crosscheck.sgml
View File

@@ -1,15 +1,27 @@
<chapter id="repmgr-cluster-crosscheck" xreflabel="repmgr cluster crosscheck"> <refentry id="repmgr-cluster-crosscheck">
<indexterm> <indexterm>
<primary>repmgr cluster crosscheck</primary> <primary>repmgr cluster crosscheck</primary>
</indexterm> </indexterm>
<title>repmgr cluster crosscheck</title>
<para>
<command>repmgr cluster crosscheck</command> is similar to <xref linkend="repmgr-cluster-matrix">, <refmeta>
but cross-checks connections between each combination of nodes. In "Example 3" in <refentrytitle>repmgr cluster crosscheck</refentrytitle>
<xref linkend="repmgr-cluster-matrix"> we have no information about the state of <literal>node3</literal>. </refmeta>
However by running <command>repmgr cluster crosscheck</command> it's possible to get a better
overview of the cluster situation: <refnamediv>
<programlisting> <refname>repmgr cluster crosscheck</refname>
<refpurpose>cross-checks connections between each combination of nodes</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
<command>repmgr cluster crosscheck</command> is similar to <xref linkend="repmgr-cluster-matrix">,
but cross-checks connections between each combination of nodes. In "Example 3" in
<xref linkend="repmgr-cluster-matrix"> we have no information about the state of <literal>node3</literal>.
However by running <command>repmgr cluster crosscheck</command> it's possible to get a better
overview of the cluster situation:
<programlisting>
$ repmgr -f /etc/repmgr.conf cluster crosscheck $ repmgr -f /etc/repmgr.conf cluster crosscheck
Name | Id | 1 | 2 | 3 Name | Id | 1 | 2 | 3
@@ -17,12 +29,14 @@
node1 | 1 | * | * | x node1 | 1 | * | * | x
node2 | 2 | * | * | * node2 | 2 | * | * | *
node3 | 3 | * | * | *</programlisting> node3 | 3 | * | * | *</programlisting>
</para> </para>
<para> <para>
What happened is that <command>repmgr cluster crosscheck</command> merged its own What happened is that <command>repmgr cluster crosscheck</command> merged its own
<command>repmgr cluster matrix</command> with the <command>repmgr cluster matrix</command> <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command> with the
output from <literal>node2</literal>; the latter is able to connect to <literal>node3</literal> <command>repmgr cluster matrix</command> output from <literal>node2</literal>; the latter is
and therefore determine the state of outbound connections from that node. able to connect to <literal>node3</literal>
</para> and therefore determine the state of outbound connections from that node.
</chapter> </para>
</refsect1>
</refentry>

87
doc/repmgr-cluster-event.sgml
View File

@@ -1,37 +1,60 @@
<chapter id="repmgr-cluster-event" xreflabel="repmgr cluster event"> <refentry id="repmgr-cluster-event">
<indexterm> <indexterm>
<primary>repmgr cluster event</primary> <primary>repmgr cluster event</primary>
</indexterm> </indexterm>
<title>repmgr cluster event</title>
<para> <refmeta>
This outputs a formatted list of cluster events, as stored in the <refentrytitle>repmgr cluster event</refentrytitle>
<literal>repmgr.events</literal> table. Output is in reverse chronological order, and </refmeta>
can be filtered with the following options:
<itemizedlist spacing="compact" mark="bullet"> <refnamediv>
<listitem> <refname>repmgr cluster event</refname>
<simpara><literal>--all</literal>: outputs all entries</simpara> <refpurpose>output a formatted list of cluster events</refpurpose>
</listitem> </refnamediv>
<listitem>
<simpara><literal>--limit</literal>: set the maximum number of entries to output (default: 20)</simpara> <refsect1>
</listitem> <title>Description</title>
<listitem>
<simpara><literal>--node-id</literal>: restrict entries to node with this ID</simpara> <para>
</listitem> Outputs a formatted list of cluster events, as stored in the <literal>repmgr.events</literal> table.
<listitem> </para>
<simpara><literal>--node-name</literal>: restrict entries to node with this name</simpara> </refsect1>
</listitem>
<listitem> <refsect1>
<simpara><literal>--event</literal>: filter specific event</simpara> <title>Usage</title>
</listitem>
</itemizedlist> <para>
</para> Output is in reverse chronological order, and
<para> can be filtered with the following options:
Example: <itemizedlist spacing="compact" mark="bullet">
<programlisting> <listitem>
<simpara><literal>--all</literal>: outputs all entries</simpara>
</listitem>
<listitem>
<simpara><literal>--limit</literal>: set the maximum number of entries to output (default: 20)</simpara>
</listitem>
<listitem>
<simpara><literal>--node-id</literal>: restrict entries to node with this ID</simpara>
</listitem>
<listitem>
<simpara><literal>--node-name</literal>: restrict entries to node with this name</simpara>
</listitem>
<listitem>
<simpara><literal>--event</literal>: filter specific event</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1>
<title>Example</title>
<para>
<programlisting>
$ repmgr -f /etc/repmgr.conf cluster event --event=standby_register $ repmgr -f /etc/repmgr.conf cluster event --event=standby_register
Node ID | Name | Event | OK | Timestamp | Details Node ID | Name | Event | OK | Timestamp | Details
---------+-------+------------------+----+---------------------+-------------------------------- ---------+-------+------------------+----+---------------------+--------------------------------
3 | node3 | standby_register | t | 2017-08-17 10:28:55 | standby registration succeeded 3 | node3 | standby_register | t | 2017-08-17 10:28:55 | standby registration succeeded
2 | node2 | standby_register | t | 2017-08-17 10:28:53 | standby registration succeeded</programlisting> 2 | node2 | standby_register | t | 2017-08-17 10:28:53 | standby registration succeeded</programlisting>
</para> </para>
</chapter> </refsect1>
</refentry>

50
doc/repmgr-cluster-matrix.sgml
View File

@@ -1,27 +1,44 @@
<chapter id="repmgr-cluster-matrix" xreflabel="repmgr cluster matrix"> <refentry id="repmgr-cluster-matrix">
<indexterm> <indexterm>
<primary>repmgr cluster matrix</primary> <primary>repmgr cluster matrix</primary>
</indexterm> </indexterm>
<title>repmgr cluster matrix</title>
<para> <refmeta>
<command>repmgr cluster matrix</command> runs <command>repmgr cluster show</command> on each <refentrytitle>repmgr cluster matrix</refentrytitle>
node and arranges the results in a matrix, recording success or failure. </refmeta>
</para>
<para> <refnamediv>
<command>repmgr cluster matrix</command> requires a valid <filename>repmgr.conf</filename> <refname>repmgr cluster matrix</refname>
file on each node. Additionally passwordless <command>ssh</command> connections are required between <refpurpose>
all nodes. runs repmgr cluster show on each node and summarizes output
</para> </refpurpose>
<para> </refnamediv>
<refsect1>
<title>Description</title>
<para>
<command>repmgr cluster matrix</command> runs <command><link linkend="repmgr-cluster-show">repmgr cluster show</link></command> on each
node and arranges the results in a matrix, recording success or failure.
</para>
<para>
<command>repmgr cluster matrix</command> requires a valid <filename>repmgr.conf</filename>
file on each node. Additionally, passwordless <command>ssh</command> connections are required between
all nodes.
</para>
</refsect1>
<refsect1>
<title>Example</title>
<para>
Example 1 (all nodes up): Example 1 (all nodes up):
<programlisting> <programlisting>
$ repmgr -f /etc/repmgr.conf cluster matrix $ repmgr -f /etc/repmgr.conf cluster matrix
Name | Id | 1 | 2 | 3 Name | Id | 1 | 2 | 3
-------+----+----+----+---- -------+----+----+----+----
node1 | 1 | * | * | * node1 | 1 | * | * | *
node2 | 2 | * | * | * node2 | 2 | * | * | *
node3 | 3 | * | * | *</programlisting> node3 | 3 | * | * | *</programlisting>
</para> </para>
<para> <para>
Example 2 (<literal>node1</literal> and <literal>node2</literal> up, <literal>node3</literal> down): Example 2 (<literal>node1</literal> and <literal>node2</literal> up, <literal>node3</literal> down):
@@ -79,5 +96,6 @@
In this case, the <xref linkend="repmgr-cluster-crosscheck"> command will produce a more In this case, the <xref linkend="repmgr-cluster-crosscheck"> command will produce a more
useful result. useful result.
</para> </para>
</chapter> </refsect1>
</refentry>

148
doc/repmgr-cluster-show.sgml
View File

@@ -1,21 +1,46 @@
<chapter id="repmgr-cluster-show" xreflabel="repmgr cluster show"> <refentry id="repmgr-cluster-show">
<indexterm> <indexterm>
<primary>repmgr cluster show</primary> <primary>repmgr cluster show</primary>
</indexterm> </indexterm>
<title>repmgr cluster show</title>
<para> <refmeta>
Displays information about each active node in the replication cluster. This <refentrytitle>repmgr cluster show</refentrytitle>
command polls each registered server and shows its role (<literal>primary</literal> / </refmeta>
<literal>standby</literal> / <literal>bdr</literal>) and status. It polls each server
directly and can be run on any node in the cluster; this is also useful when analyzing <refnamediv>
connectivity from a particular node. <refname>repmgr cluster show</refname>
</para> <refpurpose>display information about each registered node in the replication cluster</refpurpose>
<para> </refnamediv>
This command requires either a valid <filename>repmgr.conf</filename> file or a database
connection string to one of the registered nodes; no additional arguments are needed.
</para> <refsect1>
<para> <title>Description</title>
Example: <para>
Displays information about each registered node in the replication cluster. This
command polls each registered server and shows its role (<literal>primary</literal> /
<literal>standby</literal> / <literal>bdr</literal>) and status. It polls each server
directly and can be run on any node in the cluster; this is also useful when analyzing
connectivity from a particular node.
</para>
</refsect1>
<refsect1>
<title>Execution</title>
<para>
This command requires either a valid <filename>repmgr.conf</filename> file or a database
connection string to one of the registered nodes; no additional arguments are needed.
</para>
<para>
To show database connection errors when polling nodes, run the command in
<literal>--verbose</literal> mode.
</para>
</refsect1>
<refsect1>
<title>Example</title>
<para>
<programlisting> <programlisting>
$ repmgr -f /etc/repmgr.conf cluster show $ repmgr -f /etc/repmgr.conf cluster show
@@ -25,18 +50,15 @@
2 | node2 | standby | running | node1 | default | host=db_node2 dbname=repmgr user=repmgr 2 | node2 | standby | running | node1 | default | host=db_node2 dbname=repmgr user=repmgr
3 | node3 | standby | running | node1 | default | host=db_node3 dbname=repmgr user=repmgr</programlisting> 3 | node3 | standby | running | node1 | default | host=db_node3 dbname=repmgr user=repmgr</programlisting>
</para> </para>
</refsect1>
<para> <refsect1>
To show database connection errors when polling nodes, run the command in <title>Notes</title>
<literal>--verbose</literal> mode. <para>
</para> The column <literal>Role</literal> shows the expected server role according to the
&repmgr; metadata. <literal>Status</literal> shows whether the server is running or unreachable.
<para> If the node has an unexpected role not reflected in the &repmgr; metadata, e.g. a node was manually
Note that the column <literal>Role</literal> shows the expected server role according to the promoted to primary, this will be highlighted with an exclamation mark, e.g.:
&repmgr; metadata. <literal>Status</literal> shows whether the server is running or unreachable. <programlisting>
If the node has an unexpected role not reflected in the &repmgr; metadata, e.g. a node was manually
promoted to primary, this will be highlighted with an exclamation mark, e.g.:
<programlisting>
$ repmgr -f /etc/repmgr.conf cluster show $ repmgr -f /etc/repmgr.conf cluster show
ID | Name | Role | Status | Upstream | Location | Connection string ID | Name | Role | Status | Upstream | Location | Connection string
@@ -48,43 +70,47 @@
WARNING: following issues were detected WARNING: following issues were detected
node "node1" (ID: 1) is registered as an active primary but is unreachable node "node1" (ID: 1) is registered as an active primary but is unreachable
node "node2" (ID: 2) is registered as standby but running as primary</programlisting> node "node2" (ID: 2) is registered as standby but running as primary</programlisting>
</para> </para>
<para>
Node availability is tested by connecting from the node where
<command>repmgr cluster show</command> is executed, and does not necessarily imply the node
is down. See <xref linkend="repmgr-cluster-matrix"> and <xref linkend="repmgr-cluster-crosscheck"> to get
a better overviews of connections between nodes.
</para>
</refsect1>
<para> <refsect1>
<command>repmgr cluster show</command> accepts an optional parameter <literal>--csv</literal>, which <title>Options</title>
outputs the replication cluster's status in a simple CSV format, suitable for <para>
parsing by scripts: <command>repmgr cluster show</command> accepts an optional parameter <literal>--csv</literal>, which
<programlisting> outputs the replication cluster's status in a simple CSV format, suitable for
parsing by scripts:
<programlisting>
$ repmgr -f /etc/repmgr.conf cluster show --csv $ repmgr -f /etc/repmgr.conf cluster show --csv
1,-1,-1 1,-1,-1
2,0,0 2,0,0
3,0,1</programlisting> 3,0,1</programlisting>
</para> </para>
<para> <para>
The columns have following meanings: The columns have following meanings:
<itemizedlist spacing="compact" mark="bullet"> <itemizedlist spacing="compact" mark="bullet">
<listitem> <listitem>
<simpara> <simpara>
node ID node ID
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
availability (0 = available, -1 = unavailable) availability (0 = available, -1 = unavailable)
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
recovery state (0 = not in recovery, 1 = in recovery, -1 = unknown) recovery state (0 = not in recovery, 1 = in recovery, -1 = unknown)
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</refsect1>
<para> </refentry>
Note that the availability is tested by connecting from the node where
<command>repmgr cluster show</command> is executed, and does not necessarily imply the node
is down. See <xref linkend="repmgr-cluster-matrix"> and <xref linkend="repmgr-cluster-crosscheck"> to get
a better overviews of connections between nodes.
</para>
</chapter>

61
doc/repmgr-node-check.sgml
View File

@@ -1,32 +1,48 @@
<chapter id="repmgr-node-check" xreflabel="repmgr node check"> <refentry id="repmgr-node-check">
<indexterm> <indexterm>
<primary>repmgr node check</primary> <primary>repmgr node check</primary>
</indexterm> </indexterm>
<title>repmgr node check</title>
<para> <refmeta>
Performs some health checks on a node from a replication perspective. <refentrytitle>repmgr node check</refentrytitle>
This command must be run on the local node. </refmeta>
</para>
<para> <refnamediv>
Sample output (execute <command>repmgr node check</command>): <refname>repmgr node check</refname>
<programlisting> <refpurpose>performs some health checks on a node from a replication perspective</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Performs some health checks on a node from a replication perspective.
This command must be run on the local node.
</para>
</refsect1>
<refsect1>
<title>Example</title>
<para>
<programlisting>
$ repmgr -f /etc/repmgr.conf node check
Node "node1": Node "node1":
Server role: OK (node is primary) Server role: OK (node is primary)
Replication lag: OK (N/A - node is primary) Replication lag: OK (N/A - node is primary)
WAL archiving: OK (0 pending files) WAL archiving: OK (0 pending files)
Downstream servers: OK (2 of 2 downstream nodes attached) Downstream servers: OK (2 of 2 downstream nodes attached)
Replication slots: OK (node has no replication slots) Replication slots: OK (node has no replication slots)</programlisting>
</programlisting> </para>
</para> </refsect1>
<para> <refsect1>
Additionally each check can be performed individually by supplying <title>Individual checks</title>
an additional command line parameter, e.g.: <para>
<programlisting> Each check can be performed individually by supplying
$ repmgr node check --role an additional command line parameter, e.g.:
OK (node is primary) <programlisting>
</programlisting> $ repmgr node check --role
</para> OK (node is primary)</programlisting>
<para> </para>
<para>
Parameters for individual checks are as follows: Parameters for individual checks are as follows:
<itemizedlist spacing="compact" mark="bullet"> <itemizedlist spacing="compact" mark="bullet">
@@ -67,4 +83,5 @@
Individual checks can also be output in a Nagios-compatible format by additionally Individual checks can also be output in a Nagios-compatible format by additionally
providing the option <literal>--nagios</literal>. providing the option <literal>--nagios</literal>.
</para> </para>
</chapter> </refsect1>
</refentry>

114
doc/repmgr-node-rejoin.sgml
View File

@@ -1,58 +1,75 @@
<chapter id="repmgr-node-rejoin" xreflabel="repmgr node rejoin"> <refentry id="repmgr-node-rejoin">
<indexterm> <indexterm>
<primary>repmgr node rejoin</primary> <primary>repmgr node rejoin</primary>
</indexterm> </indexterm>
<title>repmgr node rejoin</title> <refmeta>
<para> <refentrytitle>repmgr node rejoin</refentrytitle>
Enables a dormant (stopped) node to be rejoined to the replication cluster. </refmeta>
</para>
<note>
<simpara>
Currently <command>repmgr node rejoin</command> can only be used to attach
a standby to the current primary, not another standby.
</simpara>
</note>
<tip> <refnamediv>
<refname>repmgr node rejoin</refname>
<refpurpose>rejoin a dormant (stopped) node to the replication cluster</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para> <para>
If the node is running and needs to be attached to the current primary, use Enables a dormant (stopped) node to be rejoined to the replication cluster.
<xref linkend="repmgr-standby-follow">.
</para> </para>
</tip>
<para>
This can optionally use <application>pg_rewind</application> to re-integrate a node which has diverged
from the rest of the cluster, typically a failed primary.
</para>
<para>
The node must have been shut down cleanly; if this was not the case, it will
need to be manually started (remove any existing <filename>recovery.conf</filename> file first)
until it has reached a consistent recovery point, then shut down cleanly.
</para>
<tip>
<para> <para>
If <application>PostgreSQL</application> is started in single-user mode and This can optionally use <application>pg_rewind</application> to re-integrate
input is directed from <filename>/dev/null/</filename>, it will perform recovery a node which has diverged from the rest of the cluster, typically a failed primary.
then immediately quit, and will then be in a state suitable for use by </para>
<application>pg_rewind</application>.
<tip>
<para>
If the node is running and needs to be attached to the current primary, use
<xref linkend="repmgr-standby-follow">.
</para>
</tip>
</refsect1>
<refsect1>
<title>Usage</title>
<para>
<programlisting> <programlisting>
rm -f /var/lib/pgsql/data/recovery.conf
postgres --single -D /var/lib/pgsql/data/ &lt; /dev/null</programlisting>
</para>
</tip>
<para>
Usage:
<programlisting>
repmgr node rejoin -d '$conninfo'</programlisting> repmgr node rejoin -d '$conninfo'</programlisting>
where <literal>$conninfo</literal> is the conninfo string of any reachable node in the cluster. where <literal>$conninfo</literal> is the conninfo string of any reachable node in the cluster.
<filename>repmgr.conf</filename> for the stopped node *must* be supplied explicitly if not <filename>repmgr.conf</filename> for the stopped node *must* be supplied explicitly if not
otherwise available. otherwise available.
</para> </para>
</refsect1>
<sect1 id="repmgr-node-rejoin-pg-rewind"> <refsect1>
<title>Notes</title>
<para>
Currently <command>repmgr node rejoin</command> can only be used to attach
a standby to the current primary, not another standby.
</para>
<para>
The node must have been shut down cleanly; if this was not the case, it will
need to be manually started (remove any existing <filename>recovery.conf</filename> file first)
until it has reached a consistent recovery point, then shut down cleanly.
</para>
<tip>
<para>
If <application>PostgreSQL</application> is started in single-user mode and
input is directed from <filename>/dev/null/</filename>, it will perform recovery
then immediately quit, and will then be in a state suitable for use by
<application>pg_rewind</application>.
<programlisting>
rm -f /var/lib/pgsql/data/recovery.conf
postgres --single -D /var/lib/pgsql/data/ &lt; /dev/null</programlisting>
</para>
</tip>
</refsect1>
<refsect1 id="repmgr-node-rejoin-pg-rewind">
<title>Using <command>pg_rewind</command></title> <title>Using <command>pg_rewind</command></title>
<para> <para>
<command>repmgr node rejoin</command> can optionally use <command>pg_rewind</command> to re-integrate a <command>repmgr node rejoin</command> can optionally use <command>pg_rewind</command> to re-integrate a
@@ -118,5 +135,14 @@
NOTICE: NODE REJOIN successful NOTICE: NODE REJOIN successful
DETAIL: node 1 is now attached to node 2</programlisting> DETAIL: node 1 is now attached to node 2</programlisting>
</para> </para>
</sect1>
</chapter>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<xref linkend="repmgr-standby-follow">
</para>
</refsect1>
</refentry>

52
doc/repmgr-node-status.sgml
View File

@@ -1,16 +1,30 @@
<refentry id="repmgr-node-status">
<chapter id="repmgr-node-status" xreflabel="repmgr node status">
<indexterm> <indexterm>
<primary>repmgr node status</primary> <primary>repmgr node status</primary>
</indexterm> </indexterm>
<title>repmgr node status</title>
<para> <refmeta>
Displays an overview of a node's basic information and replication <refentrytitle>repmgr node status</refentrytitle>
status. This command must be run on the local node. </refmeta>
</para>
<para> <refnamediv>
Sample output (execute <command>repmgr node status</command>): <refname>repmgr node status</refname>
<programlisting> <refpurpose>show overview of a node's basic information and replication status</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Displays an overview of a node's basic information and replication
status. This command must be run on the local node.
</para>
</refsect1>
<refsect1>
<title>Example</title>
<para>
<programlisting>
$ repmgr -f /etc/repmgr.comf node status
Node "node1": Node "node1":
PostgreSQL version: 10beta1 PostgreSQL version: 10beta1
Total data size: 30 MB Total data size: 30 MB
@@ -20,10 +34,14 @@
Archive command: (none) Archive command: (none)
Replication connections: 2 (of maximal 10) Replication connections: 2 (of maximal 10)
Replication slots: 0 (of maximal 10) Replication slots: 0 (of maximal 10)
Replication lag: n/a Replication lag: n/a</programlisting>
</programlisting> </para>
</para> </refsect1>
<para>
See <xref linkend="repmgr-node-check"> to diagnose issues. <refsect1>
</para> <title>See also</title>
</chapter> <para>
See <xref linkend="repmgr-node-check"> to diagnose issues.
</para>
</refsect1>
</refentry>

67
doc/repmgr-primary-register.sgml
View File

@@ -1,32 +1,51 @@
<chapter id="repmgr-primary-register" xreflabel="repmgr primary register"> <refentry id="repmgr-primary-register">
<indexterm><primary>repmgr primary register</primary></indexterm> <indexterm>
<title>repmgr primary register</title> <primary>repmgr primary register</primary>
<para> </indexterm>
<command>repmgr primary register</command> registers a primary node in a
streaming replication cluster, and configures it for use with repmgr, including
installing the &repmgr; extension. This command needs to be executed before any
standby nodes are registered.
</para>
<para>
Execute with the <literal>--dry-run</literal> option to check what would happen without
actually registering the primary.
</para>
<para>
<command>repmgr master register</command> can be used as an alias for
<command>repmgr primary register</command>.
</para>
<note> <refmeta>
<refentrytitle>repmgr primary register</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr primary register</refname>
<refpurpose>initialise a repmgr installation and register the primary node</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
<command>repmgr primary register</command> registers a primary node in a
streaming replication cluster, and configures it for use with repmgr, including
installing the &repmgr; extension. This command needs to be executed before any
standby nodes are registered.
</para>
</refsect1>
<refsect1>
<title>Execution</title>
<para>
Execute with the <literal>--dry-run</literal> option to check what would happen without
actually registering the primary.
</para>
<para>
<command>repmgr master register</command> can be used as an alias for
<command>repmgr primary register</command>.
</para>
<note>
<para> <para>
If providing the configuration file location with <literal>-f/--config-file</literal>, If providing the configuration file location with <literal>-f/--config-file</literal>,
avoid using a relative path, as &repmgr; stores the configuration file location avoid using a relative path, as &repmgr; stores the configuration file location
in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during
<xref linkend="repmgr-standby-switchover">). &repmgr; will attempt to convert the <xref linkend="repmgr-standby-switchover">). &repmgr; will attempt to convert the
a relative path into an absolute one, but this may not be the same as the path you a relative path into an absolute one, but this may not be the same as the path you
would explicitly provide (e.g. <filename>./repmgr.conf</filename> might be converted would explicitly provide (e.g. <filename>./repmgr.conf</filename> might be converted
to <filename>/path/to/./repmgr.conf</filename>, whereas you'd normally write to <filename>/path/to/./repmgr.conf</filename>, whereas you'd normally write
<filename>/path/to/repmgr.conf</filename>). <filename>/path/to/repmgr.conf</filename>).
</para> </para>
</note> </note>
</refsect1>
</chapter> </refentry>

50
doc/repmgr-primary-unregister.sgml
View File

@@ -1,18 +1,34 @@
<chapter id="repmgr-primary-unregister" xreflabel="repmgr primary unregister"> <refentry id="repmgr-primary-unregister">
<indexterm><primary>repmgr primary unregister</primary></indexterm> <indexterm>
<title>repmgr primary unregister</title> <primary>repmgr primary unregister</primary>
<para> </indexterm>
<command>repmgr primary register</command> unregisters an inactive primary node <refmeta>
from the &repmgr; metadata. This is typically when the primary has failed and is <refentrytitle>repmgr primary unregister</refentrytitle>
being removed from the cluster after a new primary has been promoted. </refmeta>
</para> <refnamediv>
<para> <refname>repmgr primary unregister</refname>
Execute with the <literal>--dry-run</literal> option to check what would happen without <refpurpose>unregister an inactive primary node</refpurpose>
actually unregistering the node. </refnamediv>
</para>
<para> <refsect1>
<command>repmgr master unregister</command> can be used as an alias for <title>Description</title>
<command>repmgr primary unregister</command>/ <para>
</para> <command>repmgr primary register</command> unregisters an inactive primary node
</chapter> from the &repmgr; metadata. This is typically when the primary has failed and is
being removed from the cluster after a new primary has been promoted.
</para>
</refsect1>
<refsect1>
<title>Execution</title>
<para>
Execute with the <literal>--dry-run</literal> option to check what would happen without
actually unregistering the node.
</para>
<para>
<command>repmgr master unregister</command> can be used as an alias for
<command>repmgr primary unregister</command>/
</para>
</refsect1>
</refentry>

52
doc/repmgr-standby-clone.sgml
View File

@@ -1,25 +1,37 @@
<chapter id="repmgr-standby-clone" xreflabel="repmgr standby clone"> <refentry id="repmgr-standby-clone">
<indexterm> <indexterm>
<primary>repmgr standby clone</primary> <primary>repmgr standby clone</primary>
<seealso>cloning</seealso> <seealso>cloning</seealso>
</indexterm> </indexterm>
<title>repmgr standby clone</title>
<para> <refmeta>
<command>repmgr standby clone</command> clones a PostgreSQL node from another <refentrytitle>repmgr standby clone</refentrytitle>
PostgreSQL node, typically the primary, but optionally from any other node in </refmeta>
the cluster or from Barman. It creates the <filename>recovery.conf</filename> file required
to attach the cloned node to the primary node (or another standby, if cascading replication <refnamediv>
is in use). <refname>repmgr standby clone</refname>
</para> <refpurpose>clone a PostgreSQL standby node from another PostgreSQL node</refpurpose>
<note> </refnamediv>
<simpara>
<command>repmgr standby clone</command> does not start the standby, and after cloning <refsect1>
<command>repmgr standby register</command> must be executed to notify &repmgr; of its presence. <title>Description</title>
</simpara> <para>
</note> <command>repmgr standby clone</command> clones a PostgreSQL node from another
PostgreSQL node, typically the primary, but optionally from any other node in
the cluster or from Barman. It creates the <filename>recovery.conf</filename> file required
to attach the cloned node to the primary node (or another standby, if cascading replication
is in use).
</para>
<note>
<simpara>
<command>repmgr standby clone</command> does not start the standby, and after cloning
<command>repmgr standby register</command> must be executed to notify &repmgr; of its presence.
</simpara>
</note>
</refsect1>
<sect1 id="repmgr-standby-clone-config-file-copying" xreflabel="Copying configuration files"> <refsect1 id="repmgr-standby-clone-config-file-copying" xreflabel="Copying configuration files">
<title>Handling configuration files</title> <title>Handling configuration files</title>
<para> <para>
@@ -51,9 +63,9 @@
configuration management tool such as Ansible, Chef, Puppet or Salt. configuration management tool such as Ansible, Chef, Puppet or Salt.
</simpara> </simpara>
</tip> </tip>
</sect1> </refsect1>
<sect1 id="repmgr-standby-clone-wal-management" xreflabel="Managing WAL during the cloning process"> <refsect1 id="repmgr-standby-clone-wal-management" xreflabel="Managing WAL during the cloning process">
<title>Managing WAL during the cloning process</title> <title>Managing WAL during the cloning process</title>
<para> <para>
When initially cloning a standby, you will need to ensure When initially cloning a standby, you will need to ensure
@@ -86,6 +98,6 @@
<literal>--wal-method</literal>. <literal>--wal-method</literal>.
</simpara> </simpara>
</note> </note>
</sect1> </refsect1>
</chapter> </refentry>

65
doc/repmgr-standby-follow.sgml
View File

@@ -1,26 +1,41 @@
<chapter id="repmgr-standby-follow" xreflabel="repmgr standby follow"> <refentry id="repmgr-standby-follow">
<indexterm> <indexterm>
<primary>repmgr standby follow</primary> <primary>repmgr standby follow</primary>
</indexterm> </indexterm>
<title>repmgr standby follow</title>
<para> <refmeta>
Attaches the standby to a new primary. This command requires a valid <refentrytitle>repmgr standby follow</refentrytitle>
<filename>repmgr.conf</filename> file for the standby, either specified </refmeta>
explicitly with <literal>-f/--config-file</literal> or located in a
default location; no additional arguments are required. <refnamediv>
</para> <refname>repmgr standby follow</refname>
<para> <refpurpose>attach a standby to a new primary</refpurpose>
This command will force a restart of the standby server, which must be </refnamediv>
running. It can only be used to attach an active standby to the current primary node
<refsect1>
<title>Description</title>
<para>
Attaches the standby to a new primary. This command requires a valid
<filename>repmgr.conf</filename> file for the standby, either specified
explicitly with <literal>-f/--config-file</literal> or located in a
default location; no additional arguments are required.
</para>
<para>
This command will force a restart of the standby server, which must be
running. It can only be used to attach an active standby to the current primary node
(and not to another standby). (and not to another standby).
</para> </para>
<para> <para>
To re-add an inactive node to the replication cluster, see To re-add an inactive node to the replication cluster, see
<xref linkend="repmgr-node-rejoin"> <xref linkend="repmgr-node-rejoin">
</para> </para>
<para> </refsect1>
Example execution:
<programlisting> <refsect1>
<title>Example</title>
<para>
<programlisting>
$ repmgr -f /etc/repmgr.conf standby follow $ repmgr -f /etc/repmgr.conf standby follow
INFO: setting node 3's primary to node 2 INFO: setting node 3's primary to node 2
NOTICE: restarting server using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' restart" NOTICE: restarting server using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' restart"
@@ -30,6 +45,14 @@
server started server started
NOTICE: STANDBY FOLLOW successful NOTICE: STANDBY FOLLOW successful
DETAIL: node 3 is now attached to node 2</programlisting> DETAIL: node 3 is now attached to node 2</programlisting>
</para> </para>
</chapter> </refsect1>
<refsect1>
<title>See also</title>
<para>
<xref linkend="repmgr-node-rejoin">
</para>
</refsect1>
</refentry>

56
doc/repmgr-standby-promote.sgml
View File

@@ -1,30 +1,44 @@
<chapter id="repmgr-standby-promote" xreflabel="repmgr standby promote"> <refentry id="repmgr-standby-promote">
<indexterm> <indexterm>
<primary>repmgr standby promote</primary> <primary>repmgr standby promote</primary>
</indexterm> </indexterm>
<title>repmgr standby promote</title>
<para> <refmeta>
Promotes a standby to a primary if the current primary has failed. This <refentrytitle>repmgr standby promote</refentrytitle>
command requires a valid <filename>repmgr.conf</filename> file for the standby, either </refmeta>
specified explicitly with <literal>-f/--config-file</literal> or located in a
default location; no additional arguments are required. <refnamediv>
</para> <refname>repmgr standby promote</refname>
<para> <refpurpose>promote a standby to a primary</refpurpose>
If the standby promotion succeeds, the server will not need to be </refnamediv>
restarted. However any other standbys will need to follow the new server,
by using <xref linkend="repmgr-standby-follow">; if <application>repmgrd</application> <refsect1>
is active, it will handle this automatically. <title>Description</title>
</para> <para>
<para> Promotes a standby to a primary if the current primary has failed. This
Example execution: command requires a valid <filename>repmgr.conf</filename> file for the standby, either
<programlisting> specified explicitly with <literal>-f/--config-file</literal> or located in a
default location; no additional arguments are required.
</para>
<para>
If the standby promotion succeeds, the server will not need to be
restarted. However any other standbys will need to follow the new server,
by using <xref linkend="repmgr-standby-follow">; if <application>repmgrd</application>
is active, it will handle this automatically.
</para>
</refsect1>
<refsect1>
<title>Example</title>
<para>
<programlisting>
$ repmgr -f /etc/repmgr.conf standby promote $ repmgr -f /etc/repmgr.conf standby promote
NOTICE: promoting standby to primary NOTICE: promoting standby to primary
DETAIL: promoting server "node2" (ID: 2) using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' promote" DETAIL: promoting server "node2" (ID: 2) using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' promote"
server promoting server promoting
DEBUG: setting node 2 as primary and marking existing primary as failed DEBUG: setting node 2 as primary and marking existing primary as failed
NOTICE: STANDBY PROMOTE successful NOTICE: STANDBY PROMOTE successful
DETAIL: server "node2" (ID: 2) was successfully promoted to primary DETAIL: server "node2" (ID: 2) was successfully promoted to primary</programlisting>
</programlisting> </para>
</para> </refsect1>
</chapter> </refentry>

66
doc/repmgr-standby-register.sgml
View File

@@ -1,29 +1,43 @@
<chapter id="repmgr-standby-register" xreflabel="repmgr standby register"> <refentry id="repmgr-standby-register" xreflabel="repmgr standby register">
<indexterm><primary>repmgr standby register</primary></indexterm> <indexterm>
<title>repmgr standby register</title> <primary>repmgr standby register</primary>
<para> </indexterm>
<command>repmgr standby register</command> adds a standby's information to
the &repmgr; metadata. This command needs to be executed to enable
promote/follow operations and to allow <application>repmgrd</application> to work with the node.
An existing standby can be registered using this command. Execute with the
<literal>--dry-run</literal> option to check what would happen without actually registering the
standby.
</para>
<note> <refmeta>
<refentrytitle>repmgr standby register</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr standby register</refname>
<refpurpose>add a standby's information to the &repmgr; metadata</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para> <para>
If providing the configuration file location with <literal>-f/--config-file</literal>, <command>repmgr standby register</command> adds a standby's information to
avoid using a relative path, as &repmgr; stores the configuration file location the &repmgr; metadata. This command needs to be executed to enable
in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during promote/follow operations and to allow <application>repmgrd</application> to work with the node.
<xref linkend="repmgr-standby-switchover">). &repmgr; will attempt to convert the An existing standby can be registered using this command. Execute with the
a relative path into an absolute one, but this may not be the same as the path you <literal>--dry-run</literal> option to check what would happen without actually registering the
would explicitly provide (e.g. <filename>./repmgr.conf</filename> might be converted standby.
to <filename>/path/to/./repmgr.conf</filename>, whereas you'd normally write
<filename>/path/to/repmgr.conf</filename>).
</para> </para>
</note>
<sect1 id="repmgr-standby-register-wait" xreflabel="repmgr standby register --wait"> <note>
<para>
If providing the configuration file location with <literal>-f/--config-file</literal>,
avoid using a relative path, as &repmgr; stores the configuration file location
in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during
<xref linkend="repmgr-standby-switchover">). &repmgr; will attempt to convert the
a relative path into an absolute one, but this may not be the same as the path you
would explicitly provide (e.g. <filename>./repmgr.conf</filename> might be converted
to <filename>/path/to/./repmgr.conf</filename>, whereas you'd normally write
<filename>/path/to/repmgr.conf</filename>).
</para>
</note>
</refsect1>
<refsect1 id="repmgr-standby-register-wait" xreflabel="repmgr standby register --wait">
<title>Waiting for the registration to propagate to the standby</title> <title>Waiting for the registration to propagate to the standby</title>
<para> <para>
Depending on your environment and workload, it may take some time for Depending on your environment and workload, it may take some time for
@@ -37,9 +51,9 @@
until the record is synchronised before exiting. An optional timeout (in until the record is synchronised before exiting. An optional timeout (in
seconds) can be added to this option (e.g. <literal>--wait-sync=60</literal>). seconds) can be added to this option (e.g. <literal>--wait-sync=60</literal>).
</para> </para>
</sect1> </refsect1>
<sect1 id="repmgr-standby-register-inactive-node" xreflabel="Registering an inactive node"> <refsect1 id="repmgr-standby-register-inactive-node" xreflabel="Registering an inactive node">
<title>Registering an inactive node</title> <title>Registering an inactive node</title>
<para> <para>
Under some circumstances you may wish to register a standby which is not Under some circumstances you may wish to register a standby which is not
@@ -59,5 +73,5 @@
When used with <command>repmgr standby register</command>, care should be taken that use of the When used with <command>repmgr standby register</command>, care should be taken that use of the
<literal>-F/--force</literal> option does not result in an incorrectly configured cluster. <literal>-F/--force</literal> option does not result in an incorrectly configured cluster.
</para> </para>
</sect1> </refsect1>
</chapter> </refentry>

69
doc/repmgr-standby-switchover.sgml
View File

@@ -1,27 +1,50 @@
<chapter id="repmgr-standby-switchover" xreflabel="repmgr standby switchover"> <refentry id="repmgr-standby-switchover">
<indexterm> <indexterm>
<primary>repmgr standby switchover</primary> <primary>repmgr standby switchover</primary>
</indexterm> </indexterm>
<title>repmgr standby switchover</title>
<para> <refmeta>
Promotes a standby to primary and demotes the existing primary to a standby. <refentrytitle>repmgr standby switchover</refentrytitle>
This command must be run on the standby to be promoted, and requires a </refmeta>
passwordless SSH connection to the current primary.
</para> <refnamediv>
<para> <refname>repmgr standby switchover</refname>
If other standbys are connected to the demotion candidate, &repmgr; can instruct <refpurpose>promote a standby to primary and demote the existing primary to a standby</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Promotes a standby to primary and demotes the existing primary to a standby.
This command must be run on the standby to be promoted, and requires a
passwordless SSH connection to the current primary.
</para>
<para>
If other standbys are connected to the demotion candidate, &repmgr; can instruct
these to follow the new primary if the option <literal>--siblings-follow</literal> these to follow the new primary if the option <literal>--siblings-follow</literal>
is specified. is specified.
</para> </para>
<para> </refsect1>
Execute with the <literal>--dry-run</literal> option to test the switchover as far as
possible without actually changing the status of either node. <refsect1>
</para> <title>Execution</title>
<para>
<application>repmgrd</application> should not be active on any nodes while a switchover is being <para>
executed. This restriction may be lifted in a later version. Execute with the <literal>--dry-run</literal> option to test the switchover as far as
</para> possible without actually changing the status of either node.
<para> </para>
For more details see the section <xref linkend="performing-switchover">. <para>
</para> <application>repmgrd</application> should not be active on any nodes while a switchover is being
</chapter> executed. This restriction may be lifted in a later version.
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>
For more details see the section <xref linkend="performing-switchover">.
</para>
</refsect1>
</refentry>

73
doc/repmgr-standby-unregister.sgml
View File

@@ -1,29 +1,46 @@
<chapter id="repmgr-standby-unregister" xreflabel="repmgr standby unregister"> <refentry id="repmgr-standby-unregister">
<indexterm><primary>repmgr standby unregister</primary></indexterm> <indexterm>
<title>repmgr standby unregister</title> <primary>repmgr standby unregister</primary>
<para> </indexterm>
Unregisters a standby with `repmgr`. This command does not affect the actual
replication, just removes the standby's entry from the &repmgr; metadata. <refmeta>
</para> <refentrytitle>repmgr standby unregister</refentrytitle>
<para> </refmeta>
To unregister a running standby, execute:
<programlisting> <refnamediv>
repmgr standby unregister -f /etc/repmgr.conf</programlisting> <refname>repmgr standby unregister</refname>
</para> <refpurpose>remove a standby's information from the &repmgr; metadata</refpurpose>
<para> </refnamediv>
This will remove the standby record from &repmgr;'s internal metadata
table (<literal>repmgr.nodes</literal>). A <literal>standby_unregister</literal> <refsect1>
event notification will be recorded in the <literal>repmgr.events</literal> table. <title>Description</title>
</para> <para>
<para> Unregisters a standby with &repmgr;. This command does not affect the actual
If the standby is not running, the command can be executed on another replication, just removes the standby's entry from the &repmgr; metadata.
node by providing the id of the node to be unregistered using </para>
the command line parameter <literal>--node-id</literal>, e.g. executing the following </refsect1>
command on the primary server will unregister the standby with
id <literal>3</literal>: <refsect1>
<programlisting> <title>Execution</title>
repmgr standby unregister -f /etc/repmgr.conf --node-id=3 <para>
</programlisting> To unregister a running standby, execute:
</para> <programlisting>
</chapter> repmgr standby unregister -f /etc/repmgr.conf</programlisting>
</para>
<para>
This will remove the standby record from &repmgr;'s internal metadata
table (<literal>repmgr.nodes</literal>). A <literal>standby_unregister</literal>
event notification will be recorded in the <literal>repmgr.events</literal> table.
</para>
<para>
If the standby is not running, the command can be executed on another
node by providing the id of the node to be unregistered using
the command line parameter <literal>--node-id</literal>, e.g. executing the following
command on the primary server will unregister the standby with
id <literal>3</literal>:
<programlisting>
repmgr standby unregister -f /etc/repmgr.conf --node-id=3</programlisting>
</para>
</refsect1>
</refentry>