github/repmgr
1
0
Fork 0
mirror of https://github.com/EnterpriseDB/repmgr.git synced 2026-03-23 07:06: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>
<primary>repmgr cluster cleanup</primary>
</indexterm>
<title>repmgr cluster cleanup</title>
<para>
Purges monitoring history from the <literal>repmgr.monitoring_history</literal> table to
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
manually or as a cronjob.
</para>
<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>
<note>
<simpara>
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>.
</simpara>
</note>
</chapter>
<refmeta>
<refentrytitle>repmgr cluster cleanup</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr cluster cleanup</refname>
<refpurpose>purge monitoring history</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Purges monitoring history from the <literal>repmgr.monitoring_history</literal> table to
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
manually or as a cronjob.
</para>
</refsect1>
<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>
<primary>repmgr cluster crosscheck</primary>
</indexterm>
<title>repmgr cluster crosscheck</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>
<refmeta>
<refentrytitle>repmgr cluster crosscheck</refentrytitle>
</refmeta>
<refnamediv>
<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
Name | Id | 1 | 2 | 3
@@ -17,12 +29,14 @@
node1 | 1 | * | * | x
node2 | 2 | * | * | *
node3 | 3 | * | * | *</programlisting>
</para>
<para>
What happened is that <command>repmgr cluster crosscheck</command> merged its own
<command>repmgr cluster matrix</command> with the <command>repmgr cluster matrix</command>
output from <literal>node2</literal>; the latter is able to connect to <literal>node3</literal>
and therefore determine the state of outbound connections from that node.
</para>
</chapter>
</para>
<para>
What happened is that <command>repmgr cluster crosscheck</command> merged its own
<command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command> with the
<command>repmgr cluster matrix</command> output from <literal>node2</literal>; the latter is
able to connect to <literal>node3</literal>
and therefore determine the state of outbound connections from that node.
</para>
</refsect1>
</refentry>

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

@@ -1,37 +1,60 @@
<chapter id="repmgr-cluster-event" xreflabel="repmgr cluster event">
<indexterm>
<primary>repmgr cluster event</primary>
</indexterm>
<title>repmgr cluster event</title>
<para>
This outputs a formatted list of cluster events, as stored in the
<literal>repmgr.events</literal> table. Output is in reverse chronological order, and
can be filtered with the following options:
<itemizedlist spacing="compact" mark="bullet">
<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>
<para>
Example:
<programlisting>
<refentry id="repmgr-cluster-event">
<indexterm>
<primary>repmgr cluster event</primary>
</indexterm>
<refmeta>
<refentrytitle>repmgr cluster event</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr cluster event</refname>
<refpurpose>output a formatted list of cluster events</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Outputs a formatted list of cluster events, as stored in the <literal>repmgr.events</literal> table.
</para>
</refsect1>
<refsect1>
<title>Usage</title>
<para>
Output is in reverse chronological order, and
can be filtered with the following options:
<itemizedlist spacing="compact" mark="bullet">
<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
Node ID | Name | Event | OK | Timestamp | Details
---------+-------+------------------+----+---------------------+--------------------------------
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>
</para>
</chapter>
</para>
</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>
<primary>repmgr cluster matrix</primary>
</indexterm>
<title>repmgr cluster matrix</title>
<para>
<command>repmgr cluster matrix</command> runs <command>repmgr cluster show</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>
<para>
<refmeta>
<refentrytitle>repmgr cluster matrix</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr cluster matrix</refname>
<refpurpose>
runs repmgr cluster show on each node and summarizes output
</refpurpose>
</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):
<programlisting>
$ repmgr -f /etc/repmgr.conf cluster matrix
Name | Id | 1 | 2 | 3
-------+----+----+----+----
node1 | 1 | * | * | *
node2 | 2 | * | * | *
node3 | 3 | * | * | *</programlisting>
node1 | 1 | * | * | *
node2 | 2 | * | * | *
node3 | 3 | * | * | *</programlisting>
</para>
<para>
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
useful result.
</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>
<primary>repmgr cluster show</primary>
</indexterm>
<title>repmgr cluster show</title>
<para>
Displays information about each active 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>
<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>
Example:
<refmeta>
<refentrytitle>repmgr cluster show</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr cluster show</refname>
<refpurpose>display information about each registered node in the replication cluster</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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>
$ repmgr -f /etc/repmgr.conf cluster show
@@ -25,18 +50,15 @@
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>
</para>
<para>
To show database connection errors when polling nodes, run the command in
<literal>--verbose</literal> mode.
</para>
<para>
Note that 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.
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>
</refsect1>
<refsect1>
<title>Notes</title>
<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.
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
ID | Name | Role | Status | Upstream | Location | Connection string
@@ -48,43 +70,47 @@
WARNING: following issues were detected
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>
</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>
<command>repmgr cluster show</command> accepts an optional parameter <literal>--csv</literal>, which
outputs the replication cluster's status in a simple CSV format, suitable for
parsing by scripts:
<programlisting>
<refsect1>
<title>Options</title>
<para>
<command>repmgr cluster show</command> accepts an optional parameter <literal>--csv</literal>, which
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
1,-1,-1
2,0,0
3,0,1</programlisting>
</para>
<para>
The columns have following meanings:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<simpara>
node ID
</simpara>
</listitem>
<listitem>
<simpara>
availability (0 = available, -1 = unavailable)
</simpara>
</listitem>
<listitem>
<simpara>
recovery state (0 = not in recovery, 1 = in recovery, -1 = unknown)
</simpara>
</listitem>
</itemizedlist>
</para>
</para>
<para>
The columns have following meanings:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<simpara>
node ID
</simpara>
</listitem>
<listitem>
<simpara>
availability (0 = available, -1 = unavailable)
</simpara>
</listitem>
<listitem>
<simpara>
recovery state (0 = not in recovery, 1 = in recovery, -1 = unknown)
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
<para>
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>
</refentry>

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>
<primary>repmgr node check</primary>
</indexterm>
<title>repmgr node check</title>
<para>
Performs some health checks on a node from a replication perspective.
This command must be run on the local node.
</para>
<para>
Sample output (execute <command>repmgr node check</command>):
<programlisting>
<refmeta>
<refentrytitle>repmgr node check</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr node check</refname>
<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":
Server role: OK (node is primary)
Replication lag: OK (N/A - node is primary)
WAL archiving: OK (0 pending files)
Downstream servers: OK (2 of 2 downstream nodes attached)
Replication slots: OK (node has no replication slots)
</programlisting>
</para>
<para>
Additionally each check can be performed individually by supplying
an additional command line parameter, e.g.:
<programlisting>
$ repmgr node check --role
OK (node is primary)
</programlisting>
</para>
<para>
Replication slots: OK (node has no replication slots)</programlisting>
</para>
</refsect1>
<refsect1>
<title>Individual checks</title>
<para>
Each check can be performed individually by supplying
an additional command line parameter, e.g.:
<programlisting>
$ repmgr node check --role
OK (node is primary)</programlisting>
</para>
<para>
Parameters for individual checks are as follows:
<itemizedlist spacing="compact" mark="bullet">
@@ -67,4 +83,5 @@
Individual checks can also be output in a Nagios-compatible format by additionally
providing the option <literal>--nagios</literal>.
</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>
<primary>repmgr node rejoin</primary>
</indexterm>
<title>repmgr node rejoin</title>
<para>
Enables a dormant (stopped) node to be rejoined to the replication cluster.
</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>
<refmeta>
<refentrytitle>repmgr node rejoin</refentrytitle>
</refmeta>
<tip>
<refnamediv>
<refname>repmgr node rejoin</refname>
<refpurpose>rejoin a dormant (stopped) node to the replication cluster</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
If the node is running and needs to be attached to the current primary, use
<xref linkend="repmgr-standby-follow">.
Enables a dormant (stopped) node to be rejoined to the replication cluster.
</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>
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>.
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>
<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>
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>
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
otherwise available.
</para>
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
otherwise available.
</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>
<para>
<command>repmgr node rejoin</command> can optionally use <command>pg_rewind</command> to re-integrate a
@@ -118,5 +135,14 @@
NOTICE: NODE REJOIN successful
DETAIL: node 1 is now attached to node 2</programlisting>
</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 @@
<chapter id="repmgr-node-status" xreflabel="repmgr node status">
<refentry id="repmgr-node-status">
<indexterm>
<primary>repmgr node status</primary>
</indexterm>
<title>repmgr node status</title>
<para>
Displays an overview of a node's basic information and replication
status. This command must be run on the local node.
</para>
<para>
Sample output (execute <command>repmgr node status</command>):
<programlisting>
<refmeta>
<refentrytitle>repmgr node status</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr node status</refname>
<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":
PostgreSQL version: 10beta1
Total data size: 30 MB
@@ -20,10 +34,14 @@
Archive command: (none)
Replication connections: 2 (of maximal 10)
Replication slots: 0 (of maximal 10)
Replication lag: n/a
</programlisting>
</para>
<para>
See <xref linkend="repmgr-node-check"> to diagnose issues.
</para>
</chapter>
Replication lag: n/a</programlisting>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<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">
<indexterm><primary>repmgr primary register</primary></indexterm>
<title>repmgr primary register</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>
<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>
<refentry id="repmgr-primary-register">
<indexterm>
<primary>repmgr primary register</primary>
</indexterm>
<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>
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>).
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>
</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">
<indexterm><primary>repmgr primary unregister</primary></indexterm>
<title>repmgr primary unregister</title>
<para>
<command>repmgr primary register</command> unregisters an inactive primary node
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>
<para>
Execute with the <literal>--dry-run</literal> option to check what would happen without
actually unregistering the node.
</para>
<refentry id="repmgr-primary-unregister">
<indexterm>
<primary>repmgr primary unregister</primary>
</indexterm>
<refmeta>
<refentrytitle>repmgr primary unregister</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr primary unregister</refname>
<refpurpose>unregister an inactive primary node</refpurpose>
</refnamediv>
<para>
<command>repmgr master unregister</command> can be used as an alias for
<command>repmgr primary unregister</command>/
</para>
</chapter>
<refsect1>
<title>Description</title>
<para>
<command>repmgr primary register</command> unregisters an inactive primary node
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>
<primary>repmgr standby clone</primary>
<seealso>cloning</seealso>
</indexterm>
<title>repmgr standby clone</title>
<para>
<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>
<refmeta>
<refentrytitle>repmgr standby clone</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr standby clone</refname>
<refpurpose>clone a PostgreSQL standby node from another PostgreSQL node</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
<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>
<para>
@@ -51,9 +63,9 @@
configuration management tool such as Ansible, Chef, Puppet or Salt.
</simpara>
</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>
<para>
When initially cloning a standby, you will need to ensure
@@ -86,6 +98,6 @@
<literal>--wal-method</literal>.
</simpara>
</note>
</sect1>
</chapter>
</refsect1>
</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>
<primary>repmgr standby follow</primary>
</indexterm>
<title>repmgr standby follow</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
<refmeta>
<refentrytitle>repmgr standby follow</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr standby follow</refname>
<refpurpose>attach a standby to a new primary</refpurpose>
</refnamediv>
<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).
</para>
<para>
To re-add an inactive node to the replication cluster, see
<xref linkend="repmgr-node-rejoin">
</para>
<para>
Example execution:
<programlisting>
</para>
<para>
To re-add an inactive node to the replication cluster, see
<xref linkend="repmgr-node-rejoin">
</para>
</refsect1>
<refsect1>
<title>Example</title>
<para>
<programlisting>
$ repmgr -f /etc/repmgr.conf standby follow
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"
@@ -30,6 +45,14 @@
server started
NOTICE: STANDBY FOLLOW successful
DETAIL: node 3 is now attached to node 2</programlisting>
</para>
</chapter>
</para>
</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>
<primary>repmgr standby promote</primary>
</indexterm>
<title>repmgr standby promote</title>
<para>
Promotes a standby to a primary if the current primary has failed. 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>
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>
<para>
Example execution:
<programlisting>
<refmeta>
<refentrytitle>repmgr standby promote</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr standby promote</refname>
<refpurpose>promote a standby to a primary</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Promotes a standby to a primary if the current primary has failed. 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>
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
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"
server promoting
DEBUG: setting node 2 as primary and marking existing primary as failed
NOTICE: STANDBY PROMOTE successful
DETAIL: server "node2" (ID: 2) was successfully promoted to primary
</programlisting>
</para>
</chapter>
DETAIL: server "node2" (ID: 2) was successfully promoted to primary</programlisting>
</para>
</refsect1>
</refentry>

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

@@ -1,29 +1,43 @@
<chapter id="repmgr-standby-register" xreflabel="repmgr standby register">
<indexterm><primary>repmgr standby register</primary></indexterm>
<title>repmgr standby register</title>
<para>
<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>
<refentry id="repmgr-standby-register" xreflabel="repmgr standby register">
<indexterm>
<primary>repmgr standby register</primary>
</indexterm>
<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>
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>).
<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>
<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>
<para>
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
seconds) can be added to this option (e.g. <literal>--wait-sync=60</literal>).
</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>
<para>
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
<literal>-F/--force</literal> option does not result in an incorrectly configured cluster.
</para>
</sect1>
</chapter>
</refsect1>
</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>
<primary>repmgr standby switchover</primary>
</indexterm>
<title>repmgr standby switchover</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
<refmeta>
<refentrytitle>repmgr standby switchover</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr standby switchover</refname>
<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>
is specified.
</para>
<para>
Execute with the <literal>--dry-run</literal> option to test the switchover as far as
possible without actually changing the status of either node.
</para>
<para>
<application>repmgrd</application> should not be active on any nodes while a switchover is being
executed. This restriction may be lifted in a later version.
</para>
<para>
For more details see the section <xref linkend="performing-switchover">.
</para>
</chapter>
is specified.
</para>
</refsect1>
<refsect1>
<title>Execution</title>
<para>
Execute with the <literal>--dry-run</literal> option to test the switchover as far as
possible without actually changing the status of either node.
</para>
<para>
<application>repmgrd</application> should not be active on any nodes while a switchover is being
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">
<indexterm><primary>repmgr standby unregister</primary></indexterm>
<title>repmgr standby unregister</title>
<para>
Unregisters a standby with `repmgr`. This command does not affect the actual
replication, just removes the standby's entry from the &repmgr; metadata.
</para>
<para>
To unregister a running standby, execute:
<programlisting>
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>
</chapter>
<refentry id="repmgr-standby-unregister">
<indexterm>
<primary>repmgr standby unregister</primary>
</indexterm>
<refmeta>
<refentrytitle>repmgr standby unregister</refentrytitle>
</refmeta>
<refnamediv>
<refname>repmgr standby unregister</refname>
<refpurpose>remove a standby's information from the &repmgr; metadata</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Unregisters a standby with &repmgr;. This command does not affect the actual
replication, just removes the standby's entry from the &repmgr; metadata.
</para>
</refsect1>
<refsect1>
<title>Execution</title>
<para>
To unregister a running standby, execute:
<programlisting>
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>