Change version number from 5.0 to 5.0.0

Previous initial "major" releases were two-element only (e.g. 4.4); beginning from repmgr 5 we want to ensure all version numbers have three elements, for general consistency, including the generation of package names.
doc: split notes about PostgreSQL 9.3 and 9.4 support into a new subsection
2026-03-23 15:16:29 +00:00 · 2019-10-15 11:01:03 +09:00 · 2019-10-15 10:46:14 +09:00 · 2019-10-15 10:42:52 +09:00 · 2019-10-15 10:30:34 +09:00 · 2019-10-14 15:10:40 +09:00
165 changed files with 27771 additions and 8766 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -42,13 +42,17 @@ lib*.pc
 /regression.diffs
 /regression.out

-/doc/Makefile
-
 # other
 /.lineno
 *.dSYM
+*.orig
+*.rej
+
 # generated binaries
 repmgr
 repmgrd
 repmgr4
 repmgrd4
+
+# generated files
+configfile-scan.c
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,7 +2,7 @@ License and Contributions
 =========================

 `repmgr` is licensed under the GPL v3.  All of its code and documentation is
-Copyright 2010-2018, 2ndQuadrant Limited.  See the files COPYRIGHT and LICENSE for
+Copyright 2010-2019, 2ndQuadrant Limited.  See the files COPYRIGHT and LICENSE for
 details.

 The development of repmgr has primarily been sponsored by 2ndQuadrant customers.
@@ -24,7 +24,7 @@ Code style
 Code in repmgr should be formatted to the same standards as the main PostgreSQL
 project. For more details see:

-    https://www.postgresql.org/docs/current/static/source-format.html
+    https://www.postgresql.org/docs/current/source-format.html

 Contributors should reformat their code similarly before submitting code to
 the project, in order to minimize merge conflicts with other work.
--- a/2
+++ b/2
@@ -1,4 +1,4 @@
-Copyright (c) 2010-2018, 2ndQuadrant Limited
+Copyright (c) 2010-2019, 2ndQuadrant Limited
 All rights reserved.

 This program is free software: you can redistribute it and/or modify
--- a/FAQ.md
+++ b/FAQ.md
@@ -1,8 +1,10 @@
 FAQ - Frequently Asked Questions about repmgr
 =============================================

-The repmgr 4 FAQ is located here: [repmgr FAQ (Frequently Asked Questions)](https://repmgr.org/docs/4.0/appendix-faq.html "repmgr FAQ")
+The repmgr 4 FAQ is located here: [repmgr FAQ (Frequently Asked Questions)](https://repmgr.org/docs/current/appendix-faq.html "repmgr FAQ")

 The repmgr 3.x FAQ can be found here:

    https://github.com/2ndQuadrant/repmgr/blob/REL3_3_STABLE/FAQ.md
+
+Note that repmgr 3.x is no longer supported.
--- a/103
+++ b/103
@@ -1,4 +1,105 @@
-4.1.0   2018-??-??
+5.0     2019-10-15
+        general: add PostgreSQL 12 support (Ian)
+        general: parse configuration file using flex (Ian)
+        repmgr: rename "repmgr daemon ..." commands to "repmgr service ..." (Ian)
+        repmgr: improve data directory check (Ian)
+        repmgr: improve extension check during "standby clone" (Ian)
+		repmgr: pass provided log level when executing repmgr remotely (Ian)
+        repmgrd: fix handling of upstream node change check (Ian)
+
+4.4     2019-06-27
+        repmgr: improve "daemon status" output (Ian)
+        repmgr: add "--siblings-follow" option to "standby promote" (Ian)
+        repmgr: add "--repmgrd-force-unpause" option to "standby switchover" (Ian)
+        repmgr: fix data directory permissions issue in barman mode where
+          an existing directory is being overwritten (Ian)
+        repmgr: improve "--dry-run" behaviour for "standby promote" and
+          "standby switchover" (Ian)
+        repmgr: when running "standby clone" with the "--upstream-conninfo" option
+          ensure that "application_name" is set correctly in "primary_conninfo" (Ian)
+        repmgr: ensure "--dry-run" together with --force when running "standby clone"
+          in barman mode does not modify an existing data directory (Ian)
+        repmgr: improve "--dry-run" output when running "standby clone" in
+          basebackup mode (Ian)
+        repmgr: improve upstream walsender checks when running "standby clone" (Ian)
+        repmgr: display node timeline ID in "cluster show" output (Ian)
+        repmgr: in "cluster show" and "daemon status", show upstream node name
+          as reported by each individual node (Ian)
+        repmgr: in "cluster show" and "daemon status", check if a node is attached
+          to its advertised upstream node
+        repmgr: use --compact rather than --terse option in "cluster event" (Ian)
+        repmgr: prevent a standby being cloned from a witness server (Ian)
+        repmgr: prevent a witness server being registered on the cluster primary (John)
+        repmgr: ensure BDR2-specific functionality cannot be used on
+          BDR3 and later (Ian)
+        repmgr: canonicalize the data directory path (Ian)
+        repmgr: note that "standby follow" requires a primary to be available (Ian)
+        repmgrd: monitor standbys attached to primary (Ian)
+        repmgrd: add "primary visibility consensus" functionality (Ian)
+        repmgrd: fix memory leak which occurs while the monitored PostgreSQL
+           node is not running (Ian)
+        general: documentation converted to DocBook XML format (Ian)
+
+4.3     2019-04-02
+        repmgr: add "daemon (start|stop)" command; GitHub #528 (Ian)
+        repmgr: add --version-number command line option (Ian)
+        repmgr: add --compact option to "cluster show"; GitHub #521 (Ian)
+        repmgr: cluster show - differentiate between unreachable nodes
+          and nodes which are running but rejecting connections (Ian)
+        repmgr: add --dry-run option to "standby promote"; GitHub #522 (Ian)
+        repmgr: add "node check --data-directory-config"; GitHub #523 (Ian)
+        repmgr: prevent potential race condition in "standby switchover"
+          when checking received WAL location; GitHub #518 (Ian)
+        repmgr: ensure "standby switchover" verifies repmgr can read the
+          data directory on the demotion candidate; GitHub #523 (Ian)
+        repmgr: ensure "standby switchover" verifies replication connection
+          exists; GitHub #519 (Ian)
+        repmgr: add sanity check for correct extension version (Ian)
+        repmgr: ensure "witness register --dry-run" does not attempt to read node
+          tables if repmgr extension not installed; GitHub #513 (Ian)
+        repmgr: ensure "standby register" fails when --upstream-node-id is the
+          same as the local node ID (Ian)
+        repmgrd: check binary and extension major versions match; GitHub #515 (Ian)
+        repmgrd: on a cascaded standby, don't fail over if "failover=manual";
+          GitHub #531 (Ian)
+        repmgrd: don't consider nodes where repmgrd is not running as promotion
+          candidates (Ian)
+        repmgrd: add option "connection_check_type" (Ian)
+        repmgrd: improve witness monitoring when primary node not available (Ian)
+		repmgrd: handle situation where a primary has unexpectedly appeared
+		  during failover; GitHub #420 (Ian)
+		general: fix Makefile (John)
+
+4.2     2018-10-24
+        repmgr: add parameter "shutdown_check_timeout" for use by "standby switchover";
+          GitHub #504 (Ian)
+        repmgr: add "--node-id" option to "repmgr cluster cleanup"; GitHub #493 (Ian)
+        repmgr: report unreachable nodes when running "repmgr cluster (matrix|crosscheck);
+          GitHub #246 (Ian)
+        repmgr: add configuration file parameter "repmgr_bindir"; GitHub #246 (Ian)
+        repmgr: fix "Missing replication slots" label in "node check"; GitHub #507 (Ian)
+        repmgrd: fix parsing of -d/--daemonize option (Ian)
+        repmgrd: support "pausing" of repmgrd (Ian)
+
+4.1.1   2018-09-05
+        logging: explicitly log the text of failed queries as ERRORs to
+          assist logfile analysis; GitHub #498
+        repmgr: truncate version string, if necessary; GitHub #490 (Ian)
+        repmgr: improve messages emitted during "standby promote" (Ian)
+        repmgr: "standby clone" - don't copy external config files in --dry-run
+          mode; GitHub #491 (Ian)
+        repmgr: add "cluster_cleanup" event; GitHub #492 (Ian)
+        repmgr: (standby switchover) improve detection of free walsenders;
+          GitHub #495 (Ian)
+        repmgr: (node rejoin) improve replication slot handling; GitHub #499 (Ian)
+        repmgrd: ensure that sending SIGHUP always results in the log file
+          being reopened; GitHub #485 (Ian)
+        repmgrd: report version number *after* logger initialisation; GitHub #487 (Ian)
+        repmgrd: fix startup on witness node when local data is stale; GitHub #488/#489 (Ian)
+        repmgrd: improve cascaded standby failover handling; GitHub #480 (Ian)
+        repmgrd: improve reconnection handling (Ian)
+
+4.1.0   2018-07-31
        repmgr: change default log_level to INFO, add documentation; GitHub #470 (Ian)
        repmgr: add "--missing-slots" check to "repmgr node check" (Ian)
        repmgr: improve command line error handling; GitHub #464 (Ian)
--- a/Makefile.global.in
+++ b/Makefile.global.in
@@ -2,6 +2,7 @@
 # Makefile.global.in
 # @configure_input@

+
 # Can only be built using pgxs
 USE_PGXS=1

@@ -14,6 +15,9 @@ ifeq ($(vpath_build),yes)
 	VPATH := $(repmgr_abs_srcdir)/$(repmgr_subdir)
 	USE_VPATH :=$(VPATH)
 endif
+
+SED=@SED@
+
 GIT_WORK_TREE=${repmgr_abs_srcdir}
 GIT_DIR=${repmgr_abs_srcdir}/.git
 export GIT_DIR
@@ -24,4 +28,13 @@ include $(PGXS)
 -include ${repmgr_abs_srcdir}/Makefile.custom

 REPMGR_VERSION=$(shell awk '/^\#define REPMGR_VERSION / { print $3; }' ${repmgr_abs_srcdir}/repmgr_version.h.in | cut -d '"' -f 2)
+REPMGR_RELEASE_DATE=$(shell awk '/^\#define REPMGR_RELEASE_DATE / { print $3; }' ${repmgr_abs_srcdir}/repmgr_version.h.in | cut -d '"' -f 2)

+FLEX = flex
+
+##########################################################################
+#
+# Global targets and rules
+
+%.c: %.l
+	$(FLEX) $(FLEXFLAGS) -o'$@' $<
--- a/Makefile.in
+++ b/Makefile.in
@@ -13,8 +13,15 @@ DATA = \
  repmgr--unpackaged--4.0.sql \
  repmgr--4.0.sql \
  repmgr--4.0--4.1.sql \
-  repmgr--4.1.sql
-
+  repmgr--4.1.sql \
+  repmgr--4.1--4.2.sql \
+  repmgr--4.2.sql \
+  repmgr--4.2--4.3.sql \
+  repmgr--4.3.sql \
+  repmgr--4.3--4.4.sql \
+  repmgr--4.4.sql \
+  repmgr--4.4--5.0.sql \
+  repmgr--5.0.sql

 REGRESS = repmgr_extension

@@ -29,25 +36,33 @@ all: \
 PG_CPPFLAGS = -std=gnu89 -I$(includedir_internal) -I$(libpq_srcdir) -Wall -Wmissing-prototypes -Wmissing-declarations $(EXTRA_CFLAGS)
 SHLIB_LINK = $(libpq)

-HEADERS = $(wildcard *.h)
+

 OBJS = \
 	repmgr.o

 include Makefile.global

+ifeq ($(vpath_build),yes)
+	HEADERS = $(wildcard *.h)
+else
+	HEADERS_built = $(wildcard *.h)
+endif

 $(info Building against PostgreSQL $(MAJORVERSION))

 REPMGR_CLIENT_OBJS = repmgr-client.o \
 	repmgr-action-primary.o repmgr-action-standby.o repmgr-action-witness.o \
-	repmgr-action-bdr.o repmgr-action-cluster.o repmgr-action-node.o \
-	configfile.o log.o strutil.o controldata.o dirutil.o compat.o dbutils.o
-REPMGRD_OBJS = repmgrd.o repmgrd-physical.o repmgrd-bdr.o configfile.o log.o dbutils.o strutil.o controldata.o compat.o
+	repmgr-action-bdr.o repmgr-action-cluster.o repmgr-action-node.o repmgr-action-service.o repmgr-action-daemon.o \
+	configfile.o configfile-scan.o log.o strutil.o controldata.o dirutil.o compat.o dbutils.o sysutils.o
+REPMGRD_OBJS = repmgrd.o repmgrd-physical.o repmgrd-bdr.o configfile.o configfile-scan.o log.o dbutils.o strutil.o controldata.o compat.o sysutils.o
 DATE=$(shell date "+%Y-%m-%d")

 repmgr_version.h: repmgr_version.h.in
-	sed '0,/REPMGR_VERSION_DATE/s,\(REPMGR_VERSION_DATE\).*,\1 "$(DATE)",' $< >$@
+	$(SED) -E 's/REPMGR_VERSION_DATE.*""/REPMGR_VERSION_DATE "$(DATE)"/' $< >$@; \
+	$(SED) -i -E 's/PG_ACTUAL_VERSION_NUM/PG_ACTUAL_VERSION_NUM $(VERSION_NUM)/' $@
+
+configfile-scan.c: configfile-scan.l

 $(REPMGR_CLIENT_OBJS): repmgr-client.h repmgr_version.h

@@ -67,10 +82,19 @@ Makefile: Makefile.in config.status configure
 Makefile.global: Makefile.global.in config.status configure
 	./config.status $@

-doc:
-	$(MAKE) -C doc all
+doc: repmgr_version.h
+	$(MAKE) -C doc html

-install-doc:
+doc-repmgr.html: repmgr_version.h
+	$(MAKE) -C doc repmgr.html
+
+doc-repmgr-A4.pdf: repmgr_version.h
+	$(MAKE) -C doc repmgr-A4.pdf
+
+doc-repmgr-US.pdf: repmgr_version.h
+	$(MAKE) -C doc repmgr-US.pdf
+
+install-doc: doc
 	$(MAKE) -C doc install

 clean: additional-clean
@@ -78,28 +102,17 @@ clean: additional-clean
 maintainer-clean: additional-maintainer-clean

 additional-clean:
-	rm -f repmgr-client.o
-	rm -f repmgr-action-primary.o
-	rm -f repmgr-action-standby.o
-	rm -f repmgr-action-witness.o
-	rm -f repmgr-action-bdr.o
-	rm -f repmgr-action-node.o
-	rm -f repmgr-action-cluster.o
-	rm -f repmgrd.o
-	rm -f repmgrd-physical.o
-	rm -f repmgrd-bdr.o
-	rm -f compat.o
-	rm -f configfile.o
-	rm -f controldata.o
-	rm -f dbutils.o
-	rm -f dirutil.o
-	rm -f log.o
-	rm -f strutil.o
+	rm -f *.o
+	rm -f repmgr_version.h
+	$(MAKE) -C doc clean

-maintainer-additional-clean: clean
-	rm -f configure
+additional-maintainer-clean: clean
+	$(MAKE) -C doc maintainer-clean
 	rm -f config.status config.log
+	rm -f config.h
+	rm -f repmgr_version.h
 	rm -f Makefile
+	rm -f Makefile.global
 	@rm -rf autom4te.cache/

 ifeq ($(MAJORVERSION),$(filter $(MAJORVERSION),9.3 9.4))
@@ -114,3 +127,4 @@ installdirs-scripts:
 .PHONY: installdirs-scripts
 endif

+.PHONY: doc doc-repmgr.html doc-repmgr-A4.pdf doc-repmgr-US.pdf install-doc
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ operations.
 `repmgr 4` is a complete rewrite of the existing `repmgr` codebase, allowing
 the use of all of the latest features in PostgreSQL replication.

-PostgreSQL 10, 9.6 and 9.5 are fully supported.
+PostgreSQL 11, 10, 9.6 and 9.5 are fully supported.
 PostgreSQL 9.4 and 9.3 are supported, with some restrictions.

 `repmgr` is distributed under the GNU GPL 3 and maintained by 2ndQuadrant.
@@ -19,7 +19,7 @@ PostgreSQL 9.4 and 9.3 are supported, with some restrictions.

 `repmgr 4` supports monitoring of a two-node BDR 2.0 cluster on PostgreSQL 9.6
 only. Note that BDR 2.0 is not publicly available; please contact 2ndQuadrant
-for details. `repmgr 4` will support future public BDR releases.
+for details.


 Documentation
@@ -27,7 +27,7 @@ Documentation

 The main `repmgr` documentation is available here:

-> [repmgr 4 documentation](https://repmgr.org/docs/4.0/index.html)
+> [repmgr documentation](https://repmgr.org/docs/current/index.html)

 The `README` file for `repmgr` 3.x is available here:

@@ -72,7 +72,7 @@ Please report bugs and other issues to:

 * https://github.com/2ndQuadrant/repmgr

-Further information is available at https://www.repmgr.org/
+Further information is available at https://repmgr.org/

 We'd love to hear from you about how you use repmgr. Case studies and
 news are always welcome. Send us an email at info@2ndQuadrant.com, or
@@ -97,6 +97,7 @@ Thanks from the repmgr core team.
 Further reading
 ---------------

+* [repmgr documentation](https://repmgr.org/docs/current/index.html)
 * https://blog.2ndquadrant.com/repmgr-3-2-is-here-barman-support-brand-new-high-availability-features/
 * https://blog.2ndquadrant.com/improvements-in-repmgr-3-1-4/
 * https://blog.2ndquadrant.com/managing-useful-clusters-repmgr/
--- a/compat.c
+++ b/compat.c
@@ -6,7 +6,7 @@
 *    supported PostgreSQL versions. They're unlikely to change but
 *    it would be worth keeping an eye on them for any fixes/improvements.
 *
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 * Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
@@ -98,9 +98,42 @@ appendShellString(PQExpBuffer buf, const char *str)

 		if (*p == '\'')
 			appendPQExpBufferStr(buf, "'\"'\"'");
+		else if (*p == '&')
+			appendPQExpBufferStr(buf, "\\&");
 		else
 			appendPQExpBufferChar(buf, *p);
 	}

 	appendPQExpBufferChar(buf, '\'');
 }
+
+/*
+ * Adapted from: src/fe_utils/string_utils.c
+ */
+void
+appendRemoteShellString(PQExpBuffer buf, const char *str)
+{
+	const char *p;
+
+	appendPQExpBufferStr(buf, "\\'");
+
+	for (p = str; *p; p++)
+	{
+		if (*p == '\n' || *p == '\r')
+		{
+			fprintf(stderr,
+					_("shell command argument contains a newline or carriage return: \"%s\"\n"),
+					str);
+			exit(ERR_BAD_CONFIG);
+		}
+
+		if (*p == '\'')
+			appendPQExpBufferStr(buf, "'\"'\"'");
+		else if (*p == '&')
+			appendPQExpBufferStr(buf, "\\&");
+		else
+			appendPQExpBufferChar(buf, *p);
+	}
+
+	appendPQExpBufferStr(buf, "\\'");
+}
--- a/compat.h
+++ b/compat.h
@@ -1,6 +1,6 @@
 /*
 * compat.h
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 * Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
@@ -27,4 +27,6 @@ extern void appendConnStrVal(PQExpBuffer buf, const char *str);

 extern void appendShellString(PQExpBuffer buf, const char *str);

+extern void appendRemoteShellString(PQExpBuffer buf, const char *str);
+
 #endif
--- a/configfile-scan.l
+++ b/configfile-scan.l
@@ -0,0 +1,366 @@
+/*
+ * Scanner for the configuration file
+ */
+
+%{
+
+#include <setjmp.h>
+
+#include "repmgr.h"
+#include "configfile.h"
+
+/*
+ * flex emits a yy_fatal_error() function that it calls in response to
+ * critical errors like malloc failure, file I/O errors, and detection of
+ * internal inconsistency.  That function prints a message and calls exit().
+ * Mutate it to instead call our handler, which jumps out of the parser.
+ */
+#undef fprintf
+#define fprintf(file, fmt, msg) CONF_flex_fatal(msg)
+
+enum
+{
+	CONF_ID = 1,
+	CONF_STRING = 2,
+	CONF_INTEGER = 3,
+	CONF_REAL = 4,
+	CONF_EQUALS = 5,
+	CONF_UNQUOTED_STRING = 6,
+	CONF_QUALIFIED_ID = 7,
+	CONF_EOL = 99,
+	CONF_ERROR = 100
+};
+
+static unsigned int ConfigFileLineno;
+static const char *CONF_flex_fatal_errmsg;
+static sigjmp_buf *CONF_flex_fatal_jmp;
+
+static char *CONF_scanstr(const char *s);
+static int	CONF_flex_fatal(const char *msg);
+
+static bool ProcessConfigFile(FILE *fp, const char *config_file, KeyValueList *contents, t_configuration_options *options, ItemList *error_list, ItemList *warning_list);
+
+%}
+
+%option 8bit
+%option never-interactive
+%option nodefault
+%option noinput
+%option nounput
+%option noyywrap
+%option warn
+%option prefix="CONF_yy"
+
+
+SIGN			("-"|"+")
+DIGIT			[0-9]
+HEXDIGIT		[0-9a-fA-F]
+
+UNIT_LETTER		[a-zA-Z]
+
+INTEGER			{SIGN}?({DIGIT}+|0x{HEXDIGIT}+){UNIT_LETTER}*
+
+EXPONENT		[Ee]{SIGN}?{DIGIT}+
+REAL			{SIGN}?{DIGIT}*"."{DIGIT}*{EXPONENT}?
+
+LETTER			[A-Za-z_\200-\377]
+LETTER_OR_DIGIT [A-Za-z_0-9\200-\377]
+
+ID				{LETTER}{LETTER_OR_DIGIT}*
+QUALIFIED_ID	{ID}"."{ID}
+
+UNQUOTED_STRING {LETTER}({LETTER_OR_DIGIT}|[-._:/])*
+STRING			\'([^'\\\n]|\\.|\'\')*\'
+
+%%
+
+\n				ConfigFileLineno++; return CONF_EOL;
+[ \t\r]+		/* eat whitespace */
+#.*				/* eat comment (.* matches anything until newline) */
+
+{ID}			return CONF_ID;
+{QUALIFIED_ID}	return CONF_QUALIFIED_ID;
+{STRING}		return CONF_STRING;
+{UNQUOTED_STRING} return CONF_UNQUOTED_STRING;
+{INTEGER}		return CONF_INTEGER;
+{REAL}			return CONF_REAL;
+=				return CONF_EQUALS;
+
+.				return CONF_ERROR;
+
+%%
+
+extern bool
+ProcessRepmgrConfigFile(FILE *fp, const char *config_file, t_configuration_options *options, ItemList *error_list, ItemList *warning_list)
+{
+	return ProcessConfigFile(fp, config_file, NULL, options, error_list, warning_list);
+}
+
+extern bool
+ProcessPostgresConfigFile(FILE *fp, const char *config_file, KeyValueList *contents, ItemList *error_list, ItemList *warning_list)
+{
+	return ProcessConfigFile(fp, config_file, contents, NULL, error_list, warning_list);
+}
+
+static bool
+ProcessConfigFile(FILE *fp, const char *config_file, KeyValueList *contents, t_configuration_options *options, ItemList *error_list, ItemList *warning_list)
+{
+	volatile bool OK = true;
+	volatile YY_BUFFER_STATE lex_buffer = NULL;
+	sigjmp_buf	flex_fatal_jmp;
+	int			errorcount;
+	int			token;
+
+	if (sigsetjmp(flex_fatal_jmp, 1) == 0)
+	{
+		CONF_flex_fatal_jmp = &flex_fatal_jmp;
+	}
+	else
+	{
+		/*
+		 * Regain control after a fatal, internal flex error.  It may have
+		 * corrupted parser state.  Consequently, abandon the file, but trust
+		 * that the state remains sane enough for yy_delete_buffer().
+		 */
+		item_list_append_format(error_list,
+								"%s at file \"%s\" line %u",
+								CONF_flex_fatal_errmsg, config_file, ConfigFileLineno);
+		OK = false;
+		goto cleanup;
+	}
+
+	/*
+	 * Parse
+	 */
+	ConfigFileLineno = 1;
+	errorcount = 0;
+
+	lex_buffer = yy_create_buffer(fp, YY_BUF_SIZE);
+	yy_switch_to_buffer(lex_buffer);
+
+	/* This loop iterates once per logical line */
+	while ((token = yylex()))
+	{
+		char	   *opt_name = NULL;
+		char	   *opt_value = NULL;
+
+		if (token == CONF_EOL)	/* empty or comment line */
+			continue;
+
+		/* first token on line is option name */
+		if (token != CONF_ID && token != CONF_QUALIFIED_ID)
+			goto parse_error;
+		opt_name = pstrdup(yytext);
+
+		/* next we have an optional equal sign; discard if present */
+		token = yylex();
+		if (token == CONF_EQUALS)
+			token = yylex();
+
+		/* now we must have the option value */
+		if (token != CONF_ID &&
+			token != CONF_STRING &&
+			token != CONF_INTEGER &&
+			token != CONF_REAL &&
+			token != CONF_UNQUOTED_STRING)
+			goto parse_error;
+		if (token == CONF_STRING)	/* strip quotes and escapes */
+			opt_value = CONF_scanstr(yytext);
+		else
+			opt_value = pstrdup(yytext);
+
+		/* now we'd like an end of line, or possibly EOF */
+		token = yylex();
+		if (token != CONF_EOL)
+		{
+			if (token != 0)
+				goto parse_error;
+			/* treat EOF like \n for line numbering purposes, cf bug 4752 */
+			ConfigFileLineno++;
+		}
+
+		/* OK, process the option name and value */
+		if (contents != NULL)
+		{
+			key_value_list_replace_or_set(contents,
+										  opt_name,
+										  opt_value);
+		}
+
+		if (options != NULL)
+		{
+			parse_configuration_item(options,
+									 error_list,
+									 warning_list,
+									 opt_name,
+									 opt_value);
+		}
+
+		/* break out of loop if read EOF, else loop for next line */
+		if (token == 0)
+			break;
+		continue;
+
+parse_error:
+		/* release storage if we allocated any on this line */
+		if (opt_name)
+			pfree(opt_name);
+		if (opt_value)
+			pfree(opt_value);
+
+		/* report the error */
+		if (token == CONF_EOL || token == 0)
+		{
+			item_list_append_format(error_list,
+									_("syntax error in file \"%s\" line %u, near end of line"),
+								    config_file, ConfigFileLineno - 1);
+		}
+		else
+		{
+			item_list_append_format(error_list,
+									_("syntax error in file \"%s\" line %u, near token \"%s\""),
+									config_file, ConfigFileLineno, yytext);
+		}
+		OK = false;
+		errorcount++;
+
+		/*
+		 * To avoid producing too much noise when fed a totally bogus file,
+		 * give up after 100 syntax errors per file (an arbitrary number).
+		 * Also, if we're only logging the errors at DEBUG level anyway, might
+		 * as well give up immediately.  (This prevents postmaster children
+		 * from bloating the logs with duplicate complaints.)
+		 */
+		if (errorcount >= 100)
+		{
+			fprintf(stderr,
+ 				   _("too many syntax errors found, abandoning file \"%s\"\n"),
+				   config_file);
+			break;
+		}
+
+		/* resync to next end-of-line or EOF */
+		while (token != CONF_EOL && token != 0)
+			token = yylex();
+		/* break out of loop on EOF */
+		if (token == 0)
+			break;
+	}
+
+cleanup:
+	yy_delete_buffer(lex_buffer);
+
+	return OK;
+}
+
+
+/*
+ *		scanstr
+ *
+ * Strip the quotes surrounding the given string, and collapse any embedded
+ * '' sequences and backslash escapes.
+ *
+ * the string returned is palloc'd and should eventually be pfree'd by the
+ * caller.
+ */
+static char *
+CONF_scanstr(const char *s)
+{
+	char	   *newStr;
+	int			len,
+				i,
+				j;
+
+	Assert(s != NULL && s[0] == '\'');
+	len = strlen(s);
+	Assert(s != NULL);
+
+	Assert(len >= 2);
+	Assert(s[len - 1] == '\'');
+
+	/* Skip the leading quote; we'll handle the trailing quote below */
+	s++, len--;
+
+	/* Since len still includes trailing quote, this is enough space */
+	newStr = palloc(len);
+
+	for (i = 0, j = 0; i < len; i++)
+	{
+		if (s[i] == '\\')
+		{
+			i++;
+			switch (s[i])
+			{
+				case 'b':
+					newStr[j] = '\b';
+					break;
+				case 'f':
+					newStr[j] = '\f';
+					break;
+				case 'n':
+					newStr[j] = '\n';
+					break;
+				case 'r':
+					newStr[j] = '\r';
+					break;
+				case 't':
+					newStr[j] = '\t';
+					break;
+				case '0':
+				case '1':
+				case '2':
+				case '3':
+				case '4':
+				case '5':
+				case '6':
+				case '7':
+					{
+						int			k;
+						long		octVal = 0;
+
+						for (k = 0;
+							 s[i + k] >= '0' && s[i + k] <= '7' && k < 3;
+							 k++)
+							octVal = (octVal << 3) + (s[i + k] - '0');
+						i += k - 1;
+						newStr[j] = ((char) octVal);
+					}
+					break;
+				default:
+					newStr[j] = s[i];
+					break;
+			}					/* switch */
+		}
+		else if (s[i] == '\'' && s[i + 1] == '\'')
+		{
+			/* doubled quote becomes just one quote */
+			newStr[j] = s[++i];
+		}
+		else
+			newStr[j] = s[i];
+		j++;
+	}
+
+	/* We copied the ending quote to newStr, so replace with \0 */
+	Assert(j > 0 && j <= len);
+	newStr[--j] = '\0';
+
+	return newStr;
+}
+
+
+/*
+ * Flex fatal errors bring us here.  Stash the error message and jump back to
+ * ParseConfigFp().  Assume all msg arguments point to string constants; this
+ * holds for flex 2.5.31 (earliest we support) and flex 2.5.35 (latest as of
+ * this writing).  Otherwise, we would need to copy the message.
+ *
+ * We return "int" since this takes the place of calls to fprintf().
+*/
+static int
+CONF_flex_fatal(const char *msg)
+{
+	CONF_flex_fatal_errmsg = msg;
+	siglongjmp(*CONF_flex_fatal_jmp, 1);
+	return 0;					/* keep compiler quiet */
+}
--- a/configfile.c
+++ b/configfile.c
--- a/configfile.h
+++ b/configfile.h
@@ -1,7 +1,7 @@
 /*
 * configfile.h
 *
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 *
 * This program is free software: you can redistribute it and/or modify
@@ -28,6 +28,12 @@
 /* magic number for use in t_recovery_conf */
 #define TARGET_TIMELINE_LATEST 0

+/*
+ * This is defined src/include/utils.h, however it's not practical
+ * to include that from a frontend application.
+ */
+#define PG_AUTOCONF_FILENAME "postgresql.auto.conf"
+
 extern bool config_file_found;
 extern char config_file_path[MAXPGPATH];

@@ -37,6 +43,13 @@ typedef enum
 	FAILOVER_AUTOMATIC
 } failover_mode_opt;

+typedef enum
+{
+	CHECK_PING,
+	CHECK_QUERY,
+	CHECK_CONNECTION
+} ConnectionCheckType;
+
 typedef struct EventNotificationListCell
 {
 	struct EventNotificationListCell *next;
@@ -69,18 +82,19 @@ typedef struct
 {
 	/* node information */
 	int			node_id;
-	char		node_name[MAXLEN];
+	char		node_name[NAMEDATALEN];
 	char		conninfo[MAXLEN];
 	char		replication_user[NAMEDATALEN];
 	char		data_directory[MAXPGPATH];
 	char		config_directory[MAXPGPATH];
 	char		pg_bindir[MAXPGPATH];
+	char		repmgr_bindir[MAXPGPATH];
 	int			replication_type;

 	/* log settings */
 	char		log_level[MAXLEN];
 	char		log_facility[MAXLEN];
-	char		log_file[MAXLEN];
+	char		log_file[MAXPGPATH];
 	int			log_status_interval;

 	/* standby clone settings */
@@ -103,7 +117,9 @@ typedef struct
 	int			standby_follow_timeout;

 	/* standby switchover settings */
+	int			shutdown_check_timeout;
 	int			standby_reconnect_timeout;
+	int			wal_receive_check_timeout;

 	/* node rejoin settings */
 	int			node_rejoin_timeout;
@@ -132,6 +148,18 @@ typedef struct
 	int			primary_notification_timeout;
 	int			repmgrd_standby_startup_timeout;
 	char		repmgrd_pid_file[MAXPGPATH];
+	bool		standby_disconnect_on_failover;
+	int			sibling_nodes_disconnect_timeout;
+	ConnectionCheckType connection_check_type;
+	bool		primary_visibility_consensus;
+	char		failover_validation_command[MAXPGPATH];
+	int			election_rerun_interval;
+	int			child_nodes_check_interval;
+	int			child_nodes_disconnect_min_count;
+	int			child_nodes_connected_min_count;
+	bool		child_nodes_connected_include_witness;
+	int			child_nodes_disconnect_timeout;
+	char		child_nodes_disconnect_command[MAXPGPATH];

 	/* BDR settings */
 	bool		bdr_local_monitoring_only;
@@ -139,14 +167,18 @@ typedef struct

 	/* service settings */
 	char		pg_ctl_options[MAXLEN];
-	char		service_stop_command[MAXLEN];
-	char		service_start_command[MAXLEN];
-	char		service_restart_command[MAXLEN];
-	char		service_reload_command[MAXLEN];
-	char		service_promote_command[MAXLEN];
+	char		service_start_command[MAXPGPATH];
+	char		service_stop_command[MAXPGPATH];
+	char		service_restart_command[MAXPGPATH];
+	char		service_reload_command[MAXPGPATH];
+	char		service_promote_command[MAXPGPATH];
+
+	/* repmgrd service settings */
+	char		repmgrd_service_start_command[MAXPGPATH];
+	char		repmgrd_service_stop_command[MAXPGPATH];

 	/* event notification settings */
-	char		event_notification_command[MAXLEN];
+	char		event_notification_command[MAXPGPATH];
 	char		event_notifications_orig[MAXLEN];
 	EventNotificationList event_notifications;

@@ -170,9 +202,9 @@ typedef struct

 #define T_CONFIGURATION_OPTIONS_INITIALIZER { \
 		/* node information */ \
-		UNKNOWN_NODE_ID, "", "", "", "", "", "", REPLICATION_TYPE_PHYSICAL,	\
+		UNKNOWN_NODE_ID, "", "", "", "", "", "", "", REPLICATION_TYPE_PHYSICAL,	\
 		/* log settings */ \
-		"", "", "", DEFAULT_LOG_STATUS_INTERVAL,	\
+		"", "", "", DEFAULT_LOG_STATUS_INTERVAL, \
 		/* standby clone settings */ \
 		false, "", "", { NULL, NULL }, "", false, "", false, "", \
 		/* standby promote settings */ \
@@ -181,7 +213,9 @@ typedef struct
 		DEFAULT_PRIMARY_FOLLOW_TIMEOUT,	\
 		DEFAULT_STANDBY_FOLLOW_TIMEOUT,	\
 		/* standby switchover settings */ \
+		DEFAULT_SHUTDOWN_CHECK_TIMEOUT, \
 		DEFAULT_STANDBY_RECONNECT_TIMEOUT, \
+		DEFAULT_WAL_RECEIVE_CHECK_TIMEOUT, \
 		/* node rejoin settings */ \
 		DEFAULT_NODE_REJOIN_TIMEOUT, \
 		/* node check settings */ \
@@ -196,12 +230,20 @@ typedef struct
        DEFAULT_RECONNECTION_INTERVAL, \
        false, -1, \
 		DEFAULT_ASYNC_QUERY_TIMEOUT, \
-		DEFAULT_PRIMARY_NOTIFICATION_TIMEOUT,	\
-		-1, "", \
+		DEFAULT_PRIMARY_NOTIFICATION_TIMEOUT, \
+		-1, "", false, DEFAULT_SIBLING_NODES_DISCONNECT_TIMEOUT, \
+		CHECK_PING, true, "", DEFAULT_ELECTION_RERUN_INTERVAL, \
+		DEFAULT_CHILD_NODES_CHECK_INTERVAL, \
+		DEFAULT_CHILD_NODES_DISCONNECT_MIN_COUNT, \
+		DEFAULT_CHILD_NODES_CONNECTED_MIN_COUNT, \
+		DEFAULT_CHILD_NODES_CONNECTED_INCLUDE_WITNESS, \
+		DEFAULT_CHILD_NODES_DISCONNECT_TIMEOUT, "", \
 		/* BDR settings */ \
 		false, DEFAULT_BDR_RECOVERY_TIMEOUT, \
 		/* service settings */ \
 		"", "", "", "", "", "", \
+		/* repmgrd service settings */ \
+		"", "",  \
 		/* event notification settings */ \
 		"", "", { NULL, NULL }, \
 		/* barman settings */ \
@@ -217,7 +259,7 @@ typedef struct
 typedef struct
 {
 	char		slot[MAXLEN];
-	char		xlog_method[MAXLEN];
+	char		wal_method[MAXLEN];
 	bool		no_slot;		/* from PostgreSQL 10 */
 } t_basebackup_options;

@@ -273,13 +315,15 @@ typedef struct
 	"", "", "", "" \
 }

+#include "dbutils.h"

 void		set_progname(const char *argv0);
 const char *progname(void);

 void		load_config(const char *config_file, bool verbose, bool terse, t_configuration_options *options, char *argv0);
-void		parse_config(t_configuration_options *options, bool terse);
-bool		reload_config(t_configuration_options *orig_options);
+bool		reload_config(t_configuration_options *orig_options, t_server_type server_type);
+
+void		parse_configuration_item(t_configuration_options *options, ItemList *error_list, ItemList *warning_list, const char *name, const char *value);

 bool		parse_recovery_conf(const char *data_dir, t_recovery_conf *conf);

@@ -304,5 +348,12 @@ void free_parsed_argv(char ***argv_array);
 /* called by repmgr-client and repmgrd */
 void		exit_with_cli_errors(ItemList *error_list, const char *repmgr_command);
 void		print_item_list(ItemList *item_list);
+const char *print_connection_check_type(ConnectionCheckType type);
+
+extern bool modify_auto_conf(const char *data_dir, KeyValueList *items);
+
+extern bool ProcessRepmgrConfigFile(FILE *fp, const char *config_file, t_configuration_options *options, ItemList *error_list, ItemList *warning_list);
+
+extern bool ProcessPostgresConfigFile(FILE *fp, const char *config_file, KeyValueList *contents, ItemList *error_list, ItemList *warning_list);

 #endif							/* _REPMGR_CONFIGFILE_H_ */
--- a/171
+++ b/171
@@ -1,8 +1,8 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for repmgr 4.1.
+# Generated by GNU Autoconf 2.69 for repmgr 5.0.0.
 #
-# Report bugs to <pgsql-bugs@postgresql.org>.
+# Report bugs to <repmgr@googlegroups.com>.
 #
 #
 # Copyright (C) 1992-1996, 1998-2012 Free Software Foundation, Inc.
@@ -11,7 +11,7 @@
 # This configure script is free software; the Free Software Foundation
 # gives unlimited permission to copy, distribute and modify it.
 #
-# Copyright (c) 2010-2018, 2ndQuadrant Ltd.
+# Copyright (c) 2010-2019, 2ndQuadrant Ltd.
 ## -------------------- ##
 ## M4sh Initialization. ##
 ## -------------------- ##
@@ -269,7 +269,7 @@ fi
    $as_echo "$0: be upgraded to zsh 4.3.4 or later."
  else
    $as_echo "$0: Please tell bug-autoconf@gnu.org and
-$0: pgsql-bugs@postgresql.org about your system, including
+$0: repmgr@googlegroups.com about your system, including
 $0: any error possibly output before this message. Then
 $0: install a modern shell, or manually run the script
 $0: under such a shell if you do have one."
@@ -582,13 +582,16 @@ MAKEFLAGS=
 # Identity of this package.
 PACKAGE_NAME='repmgr'
 PACKAGE_TARNAME='repmgr'
-PACKAGE_VERSION='4.1'
-PACKAGE_STRING='repmgr 4.1'
-PACKAGE_BUGREPORT='pgsql-bugs@postgresql.org'
-PACKAGE_URL='https://2ndquadrant.com/en/resources/repmgr/'
+PACKAGE_VERSION='5.0.0'
+PACKAGE_STRING='repmgr 5.0.0'
+PACKAGE_BUGREPORT='repmgr@googlegroups.com'
+PACKAGE_URL='https://repmgr.org/'

 ac_subst_vars='LTLIBOBJS
 LIBOBJS
+HAVE_SED
+HAVE_GSED
+HAVE_GNUSED
 vpath_build
 SED
 PG_CONFIG
@@ -1178,7 +1181,7 @@ if test "$ac_init_help" = "long"; then
  # Omit some internal or obsolete options to make the list less imposing.
  # This message is too long to be a string in the A/UX 3.1 sh.
  cat <<_ACEOF
-\`configure' configures repmgr 4.1 to adapt to many kinds of systems.
+\`configure' configures repmgr 5.0.0 to adapt to many kinds of systems.

 Usage: $0 [OPTION]... [VAR=VALUE]...

@@ -1239,7 +1242,7 @@ fi

 if test -n "$ac_init_help"; then
  case $ac_init_help in
-     short | recursive ) echo "Configuration of repmgr 4.1:";;
+     short | recursive ) echo "Configuration of repmgr 5.0.0:";;
   esac
  cat <<\_ACEOF

@@ -1249,8 +1252,8 @@ Some influential environment variables:
 Use these variables to override the choices made by `configure' or to help
 it to find libraries and programs with nonstandard names/locations.

-Report bugs to <pgsql-bugs@postgresql.org>.
-repmgr home page: <https://2ndquadrant.com/en/resources/repmgr/>.
+Report bugs to <repmgr@googlegroups.com>.
+repmgr home page: <https://repmgr.org/>.
 _ACEOF
 ac_status=$?
 fi
@@ -1313,14 +1316,14 @@ fi
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
  cat <<\_ACEOF
-repmgr configure 4.1
+repmgr configure 5.0.0
 generated by GNU Autoconf 2.69

 Copyright (C) 2012 Free Software Foundation, Inc.
 This configure script is free software; the Free Software Foundation
 gives unlimited permission to copy, distribute and modify it.

-Copyright (c) 2010-2018, 2ndQuadrant Ltd.
+Copyright (c) 2010-2019, 2ndQuadrant Ltd.
 _ACEOF
  exit
 fi
@@ -1332,7 +1335,7 @@ cat >config.log <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.

-It was created by repmgr $as_me 4.1, which was
+It was created by repmgr $as_me 5.0.0, which was
 generated by GNU Autoconf 2.69.  Invocation command line was

  $ $0 $@
@@ -1847,12 +1850,137 @@ else
 fi


+# Extract the first word of "gnused", so it can be a program name with args.
+set dummy gnused; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_prog_HAVE_GNUSED+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  if test -n "$HAVE_GNUSED"; then
+  ac_cv_prog_HAVE_GNUSED="$HAVE_GNUSED" # Let the user override the test.
+else
+as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_prog_HAVE_GNUSED="yes"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+  test -z "$ac_cv_prog_HAVE_GNUSED" && ac_cv_prog_HAVE_GNUSED="no"
+fi
+fi
+HAVE_GNUSED=$ac_cv_prog_HAVE_GNUSED
+if test -n "$HAVE_GNUSED"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HAVE_GNUSED" >&5
+$as_echo "$HAVE_GNUSED" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+# Extract the first word of "gsed", so it can be a program name with args.
+set dummy gsed; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_prog_HAVE_GSED+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  if test -n "$HAVE_GSED"; then
+  ac_cv_prog_HAVE_GSED="$HAVE_GSED" # Let the user override the test.
+else
+as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_prog_HAVE_GSED="yes"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+  test -z "$ac_cv_prog_HAVE_GSED" && ac_cv_prog_HAVE_GSED="no"
+fi
+fi
+HAVE_GSED=$ac_cv_prog_HAVE_GSED
+if test -n "$HAVE_GSED"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HAVE_GSED" >&5
+$as_echo "$HAVE_GSED" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+# Extract the first word of "sed", so it can be a program name with args.
+set dummy sed; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_prog_HAVE_SED+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  if test -n "$HAVE_SED"; then
+  ac_cv_prog_HAVE_SED="$HAVE_SED" # Let the user override the test.
+else
+as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_prog_HAVE_SED="yes"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+  test -z "$ac_cv_prog_HAVE_SED" && ac_cv_prog_HAVE_SED="no"
+fi
+fi
+HAVE_SED=$ac_cv_prog_HAVE_SED
+if test -n "$HAVE_SED"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HAVE_SED" >&5
+$as_echo "$HAVE_SED" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+
+if test "$HAVE_GNUSED" = yes; then
+ SED=gnused
+else
+ if test "$HAVE_GSED" = yes; then
+  SED=gsed
+ else
+  SED=sed
+ fi
+fi
+
+
+
 ac_config_files="$ac_config_files Makefile"

 ac_config_files="$ac_config_files Makefile.global"

-ac_config_files="$ac_config_files doc/Makefile"
-
 cat >confcache <<\_ACEOF
 # This file is a shell script that caches the results of configure
 # tests run on this system so they can be shared between configure
@@ -2359,7 +2487,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by repmgr $as_me 4.1, which was
+This file was extended by repmgr $as_me 5.0.0, which was
 generated by GNU Autoconf 2.69.  Invocation command line was

  CONFIG_FILES    = $CONFIG_FILES
@@ -2415,14 +2543,14 @@ $config_files
 Configuration headers:
 $config_headers

-Report bugs to <pgsql-bugs@postgresql.org>.
-repmgr home page: <https://2ndquadrant.com/en/resources/repmgr/>."
+Report bugs to <repmgr@googlegroups.com>.
+repmgr home page: <https://repmgr.org/>."

 _ACEOF
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
 ac_cs_version="\\
-repmgr config.status 4.1
+repmgr config.status 5.0.0
 configured by $0, generated by GNU Autoconf 2.69,
  with options \\"\$ac_cs_config\\"

@@ -2546,7 +2674,6 @@ do
    "config.h") CONFIG_HEADERS="$CONFIG_HEADERS config.h" ;;
    "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;;
    "Makefile.global") CONFIG_FILES="$CONFIG_FILES Makefile.global" ;;
-    "doc/Makefile") CONFIG_FILES="$CONFIG_FILES doc/Makefile" ;;

  *) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;;
  esac
--- a/configure.in
+++ b/configure.in
@@ -1,6 +1,6 @@
-AC_INIT([repmgr], [4.1], [pgsql-bugs@postgresql.org], [repmgr], [https://2ndquadrant.com/en/resources/repmgr/])
+AC_INIT([repmgr], [5.0.0], [repmgr@googlegroups.com], [repmgr], [https://repmgr.org/])

-AC_COPYRIGHT([Copyright (c) 2010-2018, 2ndQuadrant Ltd.])
+AC_COPYRIGHT([Copyright (c) 2010-2019, 2ndQuadrant Ltd.])

 AC_CONFIG_HEADER(config.h)

@@ -57,8 +57,23 @@ else
 fi
 AC_SUBST(vpath_build)

+AC_CHECK_PROG(HAVE_GNUSED,gnused,yes,no)
+AC_CHECK_PROG(HAVE_GSED,gsed,yes,no)
+AC_CHECK_PROG(HAVE_SED,sed,yes,no)
+
+if test "$HAVE_GNUSED" = yes; then
+ SED=gnused
+else
+ if test "$HAVE_GSED" = yes; then
+  SED=gsed
+ else
+  SED=sed
+ fi
+fi
+AC_SUBST(SED)
+
+
 AC_CONFIG_FILES([Makefile])
 AC_CONFIG_FILES([Makefile.global])
-AC_CONFIG_FILES([doc/Makefile])
 AC_OUTPUT

--- a/contrib/convert-config.pl
+++ b/contrib/convert-config.pl
@@ -73,7 +73,16 @@ while(<$fh>) {
        if ($param eq 'data_directory') {
            $data_directory_found = 1;
        }
-        push @outp, $line;
+
+        # Don't quote numbers
+        if ($value =~ /^\d+$/) {
+            push @outp, sprintf(q|%s=%s|, $param, $value);
+        }
+        # Quote everything else
+        else {
+            $value =~ s/'/''/g;
+            push @outp, sprintf(q|%s='%s'|, $param, $value);
+        }
    }
 }

@@ -83,6 +92,6 @@ print join("\n", @outp);
 print "\n";

 if ($data_directory_found == 0) {
-    print "data_directory=\n";
+    print "data_directory=''\n";
 }

--- a/controldata.c
+++ b/controldata.c
@@ -1,6 +1,12 @@
 /*
- * controldata.c
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * controldata.c - functions for reading the pg_control file
+ *
+ * The functions provided here enable repmgr to read a pg_control file
+ * in a version-indepent way, even if the PostgreSQL instance is not
+ * running. For that reason we can't use on the pg_control_*() functions
+ * provided in PostgreSQL 9.6 and later.
+ *
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 * Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
@@ -30,6 +36,53 @@

 static ControlFileInfo *get_controlfile(const char *DataDir);

+int
+get_pg_version(const char *data_directory, char *version_string)
+{
+	char		PgVersionPath[MAXPGPATH] = "";
+	FILE	   *fp = NULL;
+	char	   *endptr = NULL;
+	char		file_version_string[MAX_VERSION_STRING] = "";
+	long		file_major, file_minor;
+	int			ret;
+
+	snprintf(PgVersionPath, MAXPGPATH, "%s/PG_VERSION", data_directory);
+
+	fp = fopen(PgVersionPath, "r");
+
+	if (fp == NULL)
+	{
+		log_warning(_("could not open file \"%s\" for reading"),
+					PgVersionPath);
+		log_detail("%s", strerror(errno));
+		return UNKNOWN_SERVER_VERSION_NUM;
+	}
+
+	file_version_string[0] = '\0';
+
+	ret = fscanf(fp, "%23s", file_version_string);
+	fclose(fp);
+
+	if (ret != 1 || endptr == file_version_string)
+	{
+		log_warning(_("unable to determine major version number from PG_VERSION"));
+
+		return UNKNOWN_SERVER_VERSION_NUM;
+	}
+
+	file_major = strtol(file_version_string, &endptr, 10);
+	file_minor = 0;
+
+	if (*endptr == '.')
+		file_minor = strtol(endptr + 1, NULL, 10);
+
+	if (version_string != NULL)
+		strncpy(version_string, file_version_string, MAX_VERSION_STRING);
+
+	return ((int) file_major * 10000) + ((int) file_minor * 100);
+}
+
+
 uint64
 get_system_identifier(const char *data_directory)
 {
@@ -44,6 +97,7 @@ get_system_identifier(const char *data_directory)
 	return system_identifier;
 }

+
 DBState
 get_db_state(const char *data_directory)
 {
@@ -60,7 +114,7 @@ get_db_state(const char *data_directory)
 }


-extern XLogRecPtr
+XLogRecPtr
 get_latest_checkpoint_location(const char *data_directory)
 {
 	ControlFileInfo *control_file_info = NULL;
@@ -112,10 +166,59 @@ describe_db_state(DBState state)
 		case DB_IN_PRODUCTION:
 			return _("in production");
 	}
+
 	return _("unrecognized status code");
 }


+TimeLineID
+get_timeline(const char *data_directory)
+{
+	ControlFileInfo *control_file_info = NULL;
+	TimeLineID		 timeline = -1;
+
+	control_file_info = get_controlfile(data_directory);
+
+	timeline = (int) control_file_info->timeline;
+
+	pfree(control_file_info);
+
+	return timeline;
+}
+
+
+TimeLineID
+get_min_recovery_end_timeline(const char *data_directory)
+{
+	ControlFileInfo *control_file_info = NULL;
+	TimeLineID		 timeline = -1;
+
+	control_file_info = get_controlfile(data_directory);
+
+	timeline = (int) control_file_info->minRecoveryPointTLI;
+
+	pfree(control_file_info);
+
+	return timeline;
+}
+
+
+XLogRecPtr
+get_min_recovery_location(const char *data_directory)
+{
+	ControlFileInfo *control_file_info = NULL;
+	XLogRecPtr	minRecoveryPoint  = InvalidXLogRecPtr;
+
+	control_file_info = get_controlfile(data_directory);
+
+	minRecoveryPoint = control_file_info->minRecoveryPoint;
+
+	pfree(control_file_info);
+
+	return minRecoveryPoint;
+}
+
+
 /*
 * We maintain our own version of get_controlfile() as we need cross-version
 * compatibility, and also don't care if the file isn't readable.
@@ -123,14 +226,10 @@ describe_db_state(DBState state)
 static ControlFileInfo *
 get_controlfile(const char *DataDir)
 {
+	char		file_version_string[MAX_VERSION_STRING] = "";
 	ControlFileInfo *control_file_info;
-	FILE	   *fp = NULL;
-	int			fd, ret, version_num;
-	char		PgVersionPath[MAXPGPATH] = "";
+	int			fd, version_num;
 	char		ControlFilePath[MAXPGPATH] = "";
-	char		file_version_string[64] = "";
-	long		file_major, file_minor;
-	char	   *endptr = NULL;
 	void	   *ControlFileDataPtr = NULL;
 	int			expected_size = 0;

@@ -142,50 +241,32 @@ get_controlfile(const char *DataDir)
 	control_file_info->state = DB_SHUTDOWNED;
 	control_file_info->checkPoint = InvalidXLogRecPtr;
 	control_file_info->data_checksum_version = -1;
+	control_file_info->timeline = -1;
+	control_file_info->minRecoveryPointTLI = -1;
+	control_file_info->minRecoveryPoint = InvalidXLogRecPtr;

 	/*
 	 * Read PG_VERSION, as we'll need to determine which struct to read
 	 * the control file contents into
 	 */
-	snprintf(PgVersionPath, MAXPGPATH, "%s/PG_VERSION", DataDir);

-	fp = fopen(PgVersionPath, "r");
+	version_num = get_pg_version(DataDir, file_version_string);

-	if (fp == NULL)
+	if (version_num == UNKNOWN_SERVER_VERSION_NUM)
 	{
-		log_warning(_("could not open file \"%s\" for reading"),
-					PgVersionPath);
-		log_detail("%s", strerror(errno));
+		log_warning(_("unable to determine server version number from PG_VERSION"));
 		return control_file_info;
 	}

-	file_version_string[0] = '\0';
-
-	ret = fscanf(fp, "%63s", file_version_string);
-	fclose(fp);
-
-	if (ret != 1 || endptr == file_version_string)
+	if (version_num < MIN_SUPPORTED_VERSION_NUM)
 	{
-		log_warning(_("unable to determine major version number from PG_VERSION"));
-
+		log_warning(_("data directory appears to be initialised for %s"),
+					file_version_string);
+		log_detail(_("minimum supported PostgreSQL version is %s"),
+				   MIN_SUPPORTED_VERSION);
 		return control_file_info;
 	}

-	file_major = strtol(file_version_string, &endptr, 10);
-	file_minor = 0;
-
-	if (*endptr == '.')
-		file_minor = strtol(endptr + 1, NULL, 10);
-
-	version_num = ((int) file_major * 10000) + ((int) file_minor * 100);
-
-	if (version_num < 90300)
-	{
-		log_warning(_("Data directory appears to be initialised for %s"), file_version_string);
-		return control_file_info;
-	}
-
-
 	snprintf(ControlFilePath, MAXPGPATH, "%s/global/pg_control", DataDir);

 	if ((fd = open(ControlFilePath, O_RDONLY | PG_BINARY, 0)) == -1)
@@ -220,6 +301,8 @@ get_controlfile(const char *DataDir)
 					ControlFilePath);
 		log_detail("%s", strerror(errno));

+		close(fd);
+
 		return control_file_info;
 	}

@@ -227,13 +310,43 @@ get_controlfile(const char *DataDir)

 	control_file_info->control_file_processed = true;

-	if (version_num >= 90500)
+	if (version_num >= 120000)
+	{
+#if PG_ACTUAL_VERSION_NUM >= 120000
+		ControlFileData12 *ptr = (struct ControlFileData12 *)ControlFileDataPtr;
+		control_file_info->system_identifier = ptr->system_identifier;
+		control_file_info->state = ptr->state;
+		control_file_info->checkPoint = ptr->checkPoint;
+		control_file_info->data_checksum_version = ptr->data_checksum_version;
+		control_file_info->timeline = ptr->checkPointCopy.ThisTimeLineID;
+		control_file_info->minRecoveryPointTLI = ptr->minRecoveryPointTLI;
+		control_file_info->minRecoveryPoint = ptr->minRecoveryPoint;
+#else
+		fprintf(stderr, "ERROR: please use a repmgr version built for PostgreSQL 12\n");
+		exit(ERR_BAD_CONFIG);
+#endif
+	}
+	else if (version_num >= 110000)
+	{
+		ControlFileData11 *ptr = (struct ControlFileData11 *)ControlFileDataPtr;
+		control_file_info->system_identifier = ptr->system_identifier;
+		control_file_info->state = ptr->state;
+		control_file_info->checkPoint = ptr->checkPoint;
+		control_file_info->data_checksum_version = ptr->data_checksum_version;
+		control_file_info->timeline = ptr->checkPointCopy.ThisTimeLineID;
+		control_file_info->minRecoveryPointTLI = ptr->minRecoveryPointTLI;
+		control_file_info->minRecoveryPoint = ptr->minRecoveryPoint;
+	}
+	else if (version_num >= 90500)
 	{
 		ControlFileData95 *ptr = (struct ControlFileData95 *)ControlFileDataPtr;
 		control_file_info->system_identifier = ptr->system_identifier;
 		control_file_info->state = ptr->state;
 		control_file_info->checkPoint = ptr->checkPoint;
 		control_file_info->data_checksum_version = ptr->data_checksum_version;
+		control_file_info->timeline = ptr->checkPointCopy.ThisTimeLineID;
+		control_file_info->minRecoveryPointTLI = ptr->minRecoveryPointTLI;
+		control_file_info->minRecoveryPoint = ptr->minRecoveryPoint;
 	}
 	else if (version_num >= 90400)
 	{
@@ -242,6 +355,9 @@ get_controlfile(const char *DataDir)
 		control_file_info->state = ptr->state;
 		control_file_info->checkPoint = ptr->checkPoint;
 		control_file_info->data_checksum_version = ptr->data_checksum_version;
+		control_file_info->timeline = ptr->checkPointCopy.ThisTimeLineID;
+		control_file_info->minRecoveryPointTLI = ptr->minRecoveryPointTLI;
+		control_file_info->minRecoveryPoint = ptr->minRecoveryPoint;
 	}
 	else if (version_num >= 90300)
 	{
@@ -250,6 +366,9 @@ get_controlfile(const char *DataDir)
 		control_file_info->state = ptr->state;
 		control_file_info->checkPoint = ptr->checkPoint;
 		control_file_info->data_checksum_version = ptr->data_checksum_version;
+		control_file_info->timeline = ptr->checkPointCopy.ThisTimeLineID;
+		control_file_info->minRecoveryPointTLI = ptr->minRecoveryPointTLI;
+		control_file_info->minRecoveryPoint = ptr->minRecoveryPoint;
 	}

 	pfree(ControlFileDataPtr);
@@ -257,9 +376,7 @@ get_controlfile(const char *DataDir)
 	/*
 	 * We don't check the CRC here as we're potentially checking a pg_control
 	 * file from a different PostgreSQL version to the one repmgr was compiled
-	 * against. However we're only interested in the first few fields, which
-	 * should be constant across supported versions
-	 *
+	 * against.
 	 */

 	return control_file_info;
--- a/controldata.h
+++ b/controldata.h
@@ -1,6 +1,6 @@
 /*
 * controldata.h
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 * Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
@@ -12,6 +12,8 @@
 #include "postgres_fe.h"
 #include "catalog/pg_control.h"

+
+#define MAX_VERSION_STRING 24
 /*
 * A simplified representation of pg_control containing only those fields
 * required by repmgr.
@@ -23,6 +25,9 @@ typedef struct
 	DBState		state;
 	XLogRecPtr	checkPoint;
 	uint32		data_checksum_version;
+	TimeLineID	timeline;
+	TimeLineID	minRecoveryPointTLI;
+	XLogRecPtr	minRecoveryPoint;
 } ControlFileInfo;


@@ -51,7 +56,7 @@ typedef struct CheckPoint93
 } CheckPoint93;


-/* Same for 9.5, 9.6, 10, HEAD */
+/* Same for 9.5, 9.6, 10, 11 */
 typedef struct CheckPoint95
 {
 	XLogRecPtr	redo;			/* next RecPtr available when we began to
@@ -79,6 +84,50 @@ typedef struct CheckPoint95
 } CheckPoint95;


+#if PG_ACTUAL_VERSION_NUM >= 120000
+/*
+ * Following fields removed in PostgreSQL 12;
+ *
+ *   uint32 nextXidEpoch;
+ *   TransactionId nextXid;
+ *
+ * and replaced by:
+ *
+ *   FullTransactionId nextFullXid;
+ */
+
+typedef struct CheckPoint12
+{
+	XLogRecPtr	redo;			/* next RecPtr available when we began to
+								 * create CheckPoint (i.e. REDO start point) */
+	TimeLineID	ThisTimeLineID; /* current TLI */
+	TimeLineID	PrevTimeLineID; /* previous TLI, if this record begins a new
+								 * timeline (equals ThisTimeLineID otherwise) */
+	bool		fullPageWrites; /* current full_page_writes */
+	FullTransactionId nextFullXid;	/* next free full transaction ID */
+	Oid			nextOid;		/* next free OID */
+	MultiXactId nextMulti;		/* next free MultiXactId */
+	MultiXactOffset nextMultiOffset;	/* next free MultiXact offset */
+	TransactionId oldestXid;	/* cluster-wide minimum datfrozenxid */
+	Oid			oldestXidDB;	/* database with minimum datfrozenxid */
+	MultiXactId oldestMulti;	/* cluster-wide minimum datminmxid */
+	Oid			oldestMultiDB;	/* database with minimum datminmxid */
+	pg_time_t	time;			/* time stamp of checkpoint */
+	TransactionId oldestCommitTsXid;	/* oldest Xid with valid commit
+										 * timestamp */
+	TransactionId newestCommitTsXid;	/* newest Xid with valid commit
+										 * timestamp */
+
+	/*
+	 * Oldest XID still running. This is only needed to initialize hot standby
+	 * mode from an online checkpoint, so we only bother calculating this for
+	 * online checkpoints and only when wal_level is replica. Otherwise it's
+	 * set to InvalidTransactionId.
+	 */
+	TransactionId oldestActiveXid;
+} CheckPoint12;
+#endif
+
 typedef struct ControlFileData93
 {
 	uint64		system_identifier;
@@ -134,13 +183,11 @@ typedef struct ControlFileData93


 /*
- * Following fields added since 9.3:
+ * Following field added since 9.3:
 *
 * 	int			max_worker_processes;
- *  int			max_prepared_xacts;
- *  int			max_locks_per_xact;
- *
 */
+
 typedef struct ControlFileData94
 {
 	uint64		system_identifier;
@@ -265,12 +312,139 @@ typedef struct ControlFileData95

 } ControlFileData95;

+/*
+ * Following field removed in 11:
+ *
+ *  XLogRecPtr	prevCheckPoint;
+ *
+ * In 10, following field appended *after* "data_checksum_version":
+ *
+ * 	char		mock_authentication_nonce[MOCK_AUTH_NONCE_LEN];
+ *
+ * (but we don't care about that)
+ */
+
+typedef struct ControlFileData11
+{
+	uint64		system_identifier;
+
+	uint32		pg_control_version;		/* PG_CONTROL_VERSION */
+	uint32		catalog_version_no;		/* see catversion.h */
+
+	DBState		state;			/* see enum above */
+	pg_time_t	time;			/* time stamp of last pg_control update */
+	XLogRecPtr	checkPoint;		/* last check point record ptr */
+
+	CheckPoint95	checkPointCopy; /* copy of last check point record */
+
+	XLogRecPtr	unloggedLSN;	/* current fake LSN value, for unlogged rels */
+
+	XLogRecPtr	minRecoveryPoint;
+	TimeLineID	minRecoveryPointTLI;
+	XLogRecPtr	backupStartPoint;
+	XLogRecPtr	backupEndPoint;
+	bool		backupEndRequired;
+
+	int			wal_level;
+	bool		wal_log_hints;
+	int			MaxConnections;
+	int			max_worker_processes;
+	int			max_prepared_xacts;
+	int			max_locks_per_xact;
+	bool		track_commit_timestamp;
+
+	uint32		maxAlign;		/* alignment requirement for tuples */
+	double		floatFormat;	/* constant 1234567.0 */
+
+	uint32		blcksz;			/* data block size for this DB */
+	uint32		relseg_size;	/* blocks per segment of large relation */
+
+	uint32		xlog_blcksz;	/* block size within WAL files */
+	uint32		xlog_seg_size;	/* size of each WAL segment */
+
+	uint32		nameDataLen;	/* catalog name field width */
+	uint32		indexMaxKeys;	/* max number of columns in an index */
+
+	uint32		toast_max_chunk_size;	/* chunk size in TOAST tables */
+	uint32		loblksize;		/* chunk size in pg_largeobject */
+
+	bool		enableIntTimes; /* int64 storage enabled? */
+
+	bool		float4ByVal;	/* float4 pass-by-value? */
+	bool		float8ByVal;	/* float8, int8, etc pass-by-value? */
+
+	uint32		data_checksum_version;
+
+} ControlFileData11;


+#if PG_ACTUAL_VERSION_NUM >= 120000
+/*
+ * Following field added in Pg12:
+ *
+ *   int max_wal_senders;
+ */
+
+typedef struct ControlFileData12
+{
+	uint64		system_identifier;
+
+	uint32		pg_control_version; /* PG_CONTROL_VERSION */
+	uint32		catalog_version_no; /* see catversion.h */
+
+	DBState		state;			/* see enum above */
+	pg_time_t	time;			/* time stamp of last pg_control update */
+	XLogRecPtr	checkPoint;		/* last check point record ptr */
+
+	CheckPoint12	checkPointCopy; /* copy of last check point record */
+
+	XLogRecPtr	unloggedLSN;	/* current fake LSN value, for unlogged rels */
+
+	XLogRecPtr	minRecoveryPoint;
+	TimeLineID	minRecoveryPointTLI;
+	XLogRecPtr	backupStartPoint;
+	XLogRecPtr	backupEndPoint;
+	bool		backupEndRequired;
+
+	int			wal_level;
+	bool		wal_log_hints;
+	int			MaxConnections;
+	int			max_worker_processes;
+	int			max_wal_senders;
+	int			max_prepared_xacts;
+	int			max_locks_per_xact;
+	bool		track_commit_timestamp;
+
+	uint32		maxAlign;		/* alignment requirement for tuples */
+	double		floatFormat;	/* constant 1234567.0 */
+
+	uint32		blcksz;			/* data block size for this DB */
+	uint32		relseg_size;	/* blocks per segment of large relation */
+
+	uint32		xlog_blcksz;	/* block size within WAL files */
+	uint32		xlog_seg_size;	/* size of each WAL segment */
+
+	uint32		nameDataLen;	/* catalog name field width */
+	uint32		indexMaxKeys;	/* max number of columns in an index */
+
+	uint32		toast_max_chunk_size;	/* chunk size in TOAST tables */
+	uint32		loblksize;		/* chunk size in pg_largeobject */
+
+	bool		float4ByVal;	/* float4 pass-by-value? */
+	bool		float8ByVal;	/* float8, int8, etc pass-by-value? */
+
+	uint32		data_checksum_version;
+} ControlFileData12;
+#endif
+
+extern int get_pg_version(const char *data_directory, char *version_string);
 extern DBState get_db_state(const char *data_directory);
 extern const char *describe_db_state(DBState state);
 extern int	get_data_checksum_version(const char *data_directory);
 extern uint64 get_system_identifier(const char *data_directory);
 extern XLogRecPtr get_latest_checkpoint_location(const char *data_directory);
+extern TimeLineID get_timeline(const char *data_directory);
+extern TimeLineID get_min_recovery_end_timeline(const char *data_directory);
+extern XLogRecPtr get_min_recovery_location(const char *data_directory);

 #endif							/* _CONTROLDATA_H_ */
--- a/dbutils.c
+++ b/dbutils.c
--- a/dbutils.h
+++ b/dbutils.h
@@ -1,7 +1,7 @@
 /*
 * dbutils.h
 *
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
@@ -20,6 +20,7 @@
 #ifndef _REPMGR_DBUTILS_H_
 #define _REPMGR_DBUTILS_H_

+#include "access/timeline.h"
 #include "access/xlogdefs.h"
 #include "pqexpbuffer.h"
 #include "portability/instr_time.h"
@@ -28,7 +29,38 @@
 #include "strutil.h"
 #include "voting.h"

-#define REPMGR_NODES_COLUMNS "n.node_id, n.type, n.upstream_node_id, n.node_name, n.conninfo, n.repluser, n.slot_name, n.location, n.priority, n.active, n.config_file, '' AS upstream_node_name "
+#define REPMGR_NODES_COLUMNS \
+	"n.node_id, " \
+	"n.type, " \
+	"n.upstream_node_id, " \
+	"n.node_name,  " \
+	"n.conninfo, " \
+	"n.repluser, " \
+	"n.slot_name, " \
+	"n.location, " \
+	"n.priority, " \
+	"n.active, " \
+	"n.config_file, " \
+	"'' AS upstream_node_name, " \
+	"NULL AS attached "
+
+#define REPMGR_NODES_COLUMNS_WITH_UPSTREAM \
+	"n.node_id, " \
+	"n.type, " \
+	"n.upstream_node_id, " \
+	"n.node_name, " \
+	"n.conninfo, " \
+	"n.repluser, " \
+	"n.slot_name, " \
+	"n.location, " \
+	"n.priority, " \
+	"n.active, "\
+	"n.config_file, " \
+	"un.node_name AS upstream_node_name, " \
+	"NULL AS attached "
+
+
+
 #define BDR2_NODES_COLUMNS "node_sysid, node_timeline, node_dboid, node_name, node_local_dsn, ''"
 #define BDR3_NODES_COLUMNS "ns.node_id, 0, 0, ns.node_name, ns.interface_connstr, ns.peer_state_name"

@@ -47,6 +79,7 @@ typedef enum
 typedef enum
 {
 	REPMGR_INSTALLED = 0,
+	REPMGR_OLD_VERSION_INSTALLED,
 	REPMGR_AVAILABLE,
 	REPMGR_UNAVAILABLE,
 	REPMGR_UNKNOWN
@@ -78,7 +111,8 @@ typedef enum
 	NODE_STATUS_UP,
 	NODE_STATUS_SHUTTING_DOWN,
 	NODE_STATUS_DOWN,
-	NODE_STATUS_UNCLEAN_SHUTDOWN
+	NODE_STATUS_UNCLEAN_SHUTDOWN,
+	NODE_STATUS_REJECTED
 } NodeStatus;

 typedef enum
@@ -89,6 +123,13 @@ typedef enum
 	CONN_ERROR
 } ConnectionStatus;

+typedef enum
+{
+	NODE_ATTACHED_UNKNOWN = -1,
+	NODE_DETACHED,
+	NODE_ATTACHED
+} NodeAttached;
+
 typedef enum
 {
 	SLOT_UNKNOWN = -1,
@@ -104,8 +145,47 @@ typedef enum
 } BackupState;


+
 /*
- * Struct to store node information
+ * Struct to store extension version information
+ */
+
+typedef struct s_extension_versions {
+	char		default_version[8];
+	int			default_version_num;
+	char		installed_version[8];
+	int			installed_version_num;
+} t_extension_versions;
+
+#define T_EXTENSION_VERSIONS_INITIALIZER { \
+	"", \
+	UNKNOWN_SERVER_VERSION_NUM, \
+	"", \
+	UNKNOWN_SERVER_VERSION_NUM \
+}
+
+
+typedef struct
+{
+	char		current_timestamp[MAXLEN];
+	bool		in_recovery;
+	TimeLineID	timeline_id;
+	XLogRecPtr	last_wal_receive_lsn;
+	XLogRecPtr	last_wal_replay_lsn;
+	char		last_xact_replay_timestamp[MAXLEN];
+	int			replication_lag_time;
+	bool		receiving_streamed_wal;
+	bool		wal_replay_paused;
+	int			upstream_last_seen;
+	int			upstream_node_id;
+} ReplInfo;
+
+/*
+ * Struct to store node information.
+ *
+ * The first section represents the contents of the "repmgr.nodes"
+ * table; subsequent section contain information collated in
+ * various contexts.
 */
 typedef struct s_node_info
 {
@@ -113,8 +193,8 @@ typedef struct s_node_info
 	int			node_id;
 	int			upstream_node_id;
 	t_server_type type;
-	char		node_name[MAXLEN];
-	char		upstream_node_name[MAXLEN];
+	char		node_name[NAMEDATALEN];
+	char		upstream_node_name[NAMEDATALEN];
 	char		conninfo[MAXLEN];
 	char		repluser[NAMEDATALEN];
 	char		location[MAXLEN];
@@ -131,7 +211,7 @@ typedef struct s_node_info
 	/* for ad-hoc use e.g. when working with a list of nodes */
 	char		details[MAXLEN];
 	bool		reachable;
-	bool		attached;
+	NodeAttached attached;
 	/* various statistics */
 	int			max_wal_senders;
 	int			attached_wal_receivers;
@@ -139,6 +219,8 @@ typedef struct s_node_info
 	int			total_replication_slots;
 	int			active_replication_slots;
 	int			inactive_replication_slots;
+	/* replication info */
+	ReplInfo   *replication_info;
 } t_node_info;


@@ -163,9 +245,10 @@ typedef struct s_node_info
 	MS_NORMAL, \
 	NULL, \
 	/* for ad-hoc use e.g. when working with a list of nodes */ \
-	"", true, true \
+	"", true, true,	\
 	/* various statistics */ \
-	-1, -1, -1, -1, -1, -1					\
+	-1, -1, -1, -1, -1, -1,	\
+	NULL \
 }


@@ -278,23 +361,6 @@ typedef struct BdrNodeInfoList
 	0 \
 }

-typedef struct
-{
-	char		current_timestamp[MAXLEN];
-	uint64		last_wal_receive_lsn;
-	uint64		last_wal_replay_lsn;
-	char		last_xact_replay_timestamp[MAXLEN];
-	int			replication_lag_time;
-	bool		receiving_streamed_wal;
-} ReplInfo;
-
-#define T_REPLINFO_INTIALIZER { \
-	"", \
-	InvalidXLogRecPtr, \
-	InvalidXLogRecPtr, \
-	"", \
-	0 \
-}


 typedef struct
@@ -327,9 +393,24 @@ typedef struct
    UNKNOWN_TIMELINE_ID, \
 	InvalidXLogRecPtr \
 }
-/* global variables */

-extern int	server_version_num;
+
+typedef struct RepmgrdInfo {
+	int node_id;
+	int pid;
+	char pid_text[MAXLEN];
+	char pid_file[MAXLEN];
+	bool pg_running;
+	char pg_running_text[MAXLEN];
+	RecoveryType recovery_type;
+	bool running;
+	char repmgrd_running[MAXLEN];
+	bool paused;
+	bool wal_paused_pending_wal;
+	int  upstream_last_seen;
+	char upstream_last_seen_text[MAXLEN];
+} RepmgrdInfo;
+

 /* macros */

@@ -346,19 +427,18 @@ __attribute__((format(PG_PRINTF_ATTRIBUTE, 3, 4)));
 bool		atobool(const char *value);

 /* connection functions */
-PGconn *establish_db_connection(const char *conninfo,
+PGconn	   *establish_db_connection(const char *conninfo,
 						const bool exit_on_error);
 PGconn	   *establish_db_connection_quiet(const char *conninfo);
-
-PGconn *establish_db_connection_by_params(t_conninfo_param_list *param_list,
+PGconn	   *establish_db_connection_by_params(t_conninfo_param_list *param_list,
 								  const bool exit_on_error);
-PGconn *establish_primary_db_connection(PGconn *conn,
+PGconn	   *establish_primary_db_connection(PGconn *conn,
 								const bool exit_on_error);
-
 PGconn	   *get_primary_connection(PGconn *standby_conn, int *primary_id, char *primary_conninfo_out);
 PGconn	   *get_primary_connection_quiet(PGconn *standby_conn, int *primary_id, char *primary_conninfo_out);

 bool		is_superuser_connection(PGconn *conn, t_connection_user *userinfo);
+bool		connection_has_pg_settings(PGconn *conn);
 void		close_connection(PGconn **conn);

 /* conninfo manipulation functions */
@@ -373,6 +453,7 @@ void		param_set_ine(t_conninfo_param_list *param_list, const char *param, const
 char	   *param_get(t_conninfo_param_list *param_list, const char *param);
 bool		parse_conninfo_string(const char *conninfo_str, t_conninfo_param_list *param_list, char **errmsg, bool ignore_local_params);
 char	   *param_list_to_string(t_conninfo_param_list *param_list);
+char	   *normalize_conninfo_string(const char *conninfo_str);
 bool		has_passfile(void);


@@ -380,39 +461,57 @@ bool		has_passfile(void);
 bool		begin_transaction(PGconn *conn);
 bool		commit_transaction(PGconn *conn);
 bool		rollback_transaction(PGconn *conn);
-bool		check_cluster_schema(PGconn *conn);

 /* GUC manipulation functions */
 bool		set_config(PGconn *conn, const char *config_param, const char *config_value);
 bool		set_config_bool(PGconn *conn, const char *config_param, bool state);
 int		    guc_set(PGconn *conn, const char *parameter, const char *op, const char *value);
-int			guc_set_typed(PGconn *conn, const char *parameter, const char *op, const char *value, const char *datatype);
 bool		get_pg_setting(PGconn *conn, const char *setting, char *output);
+bool		get_pg_setting_int(PGconn *conn, const char *setting, int *output);
+bool		alter_system_int(PGconn *conn, const char *name, int value);
+bool		pg_reload_conf(PGconn *conn);

 /* server information functions */
 bool		get_cluster_size(PGconn *conn, char *size);
-int			get_server_version(PGconn *conn, char *server_version);
+int			get_server_version(PGconn *conn, char *server_version_buf);
+
 RecoveryType get_recovery_type(PGconn *conn);
 int			get_primary_node_id(PGconn *conn);
 int			get_ready_archive_files(PGconn *conn, const char *data_directory);
 bool		identify_system(PGconn *repl_conn, t_system_identification *identification);
+uint64		system_identifier(PGconn *conn);
+TimeLineHistoryEntry *get_timeline_history(PGconn *repl_conn, TimeLineID tli);
+
+/* repmgrd shared memory functions */
 bool		repmgrd_set_local_node_id(PGconn *conn, int local_node_id);
 int			repmgrd_get_local_node_id(PGconn *conn);
+bool		repmgrd_check_local_node_id(PGconn *conn);
 BackupState	server_in_exclusive_backup_mode(PGconn *conn);
+void		repmgrd_set_pid(PGconn *conn, pid_t repmgrd_pid, const char *pidfile);
+pid_t		repmgrd_get_pid(PGconn *conn);
+bool		repmgrd_is_running(PGconn *conn);
+bool		repmgrd_is_paused(PGconn *conn);
+bool		repmgrd_pause(PGconn *conn, bool pause);
+pid_t		get_wal_receiver_pid(PGconn *conn);
+int			repmgrd_get_upstream_node_id(PGconn *conn);
+bool		repmgrd_set_upstream_node_id(PGconn *conn, int node_id);

 /* extension functions */
-ExtensionStatus get_repmgr_extension_status(PGconn *conn);
+ExtensionStatus get_repmgr_extension_status(PGconn *conn, t_extension_versions *extversions);

 /* node management functions */
 void		checkpoint(PGconn *conn);
 bool		vacuum_table(PGconn *conn, const char *table);
-
+bool		promote_standby(PGconn *conn, bool wait, int wait_seconds);
+bool		resume_wal_replay(PGconn *conn);

 /* node record functions */
 t_server_type parse_node_type(const char *type);
 const char *get_node_type_string(t_server_type type);

 RecordStatus get_node_record(PGconn *conn, int node_id, t_node_info *node_info);
+RecordStatus refresh_node_record(PGconn *conn, int node_id, t_node_info *node_info);
+
 RecordStatus get_node_record_with_upstream(PGconn *conn, int node_id, t_node_info *node_info);

 RecordStatus get_node_record_by_name(PGconn *conn, const char *node_name, t_node_info *node_info);
@@ -421,9 +520,10 @@ t_node_info *get_node_record_pointer(PGconn *conn, int node_id);
 bool		get_local_node_record(PGconn *conn, int node_id, t_node_info *node_info);
 bool		get_primary_node_record(PGconn *conn, t_node_info *node_info);

-void		get_all_node_records(PGconn *conn, NodeInfoList *node_list);
+bool		get_all_node_records(PGconn *conn, NodeInfoList *node_list);
 void		get_downstream_node_records(PGconn *conn, int node_id, NodeInfoList *nodes);
 void		get_active_sibling_node_records(PGconn *conn, int node_id, int upstream_node_id, NodeInfoList *node_list);
+bool		get_child_nodes(PGconn *conn, int node_id, NodeInfoList *node_list);
 void		get_node_records_by_priority(PGconn *conn, NodeInfoList *node_list);
 bool		get_all_node_records_with_upstream(PGconn *conn, NodeInfoList *node_list);
 bool		get_downstream_nodes_with_missing_slot(PGconn *conn, int this_node_id, NodeInfoList *noede_list);
@@ -459,7 +559,7 @@ PGresult   *get_event_records(PGconn *conn, int node_id, const char *node_name,

 /* replication slot functions */
 void		create_slot_name(char *slot_name, int node_id);
-bool		create_replication_slot(PGconn *conn, char *slot_name, int server_version_num, PQExpBufferData *error_msg);
+bool		create_replication_slot(PGconn *conn, char *slot_name, PQExpBufferData *error_msg);
 bool		drop_replication_slot(PGconn *conn, char *slot_name);
 RecordStatus get_slot_record(PGconn *conn, char *slot_name, t_replication_slot *record);
 int			get_free_replication_slot_count(PGconn *conn);
@@ -470,12 +570,14 @@ bool		get_tablespace_name_by_location(PGconn *conn, const char *location, char *

 /* asynchronous query functions */
 bool		cancel_query(PGconn *conn, int timeout);
-int			wait_connection_availability(PGconn *conn, long long timeout);
+int			wait_connection_availability(PGconn *conn, int timeout);

 /* node availability functions */
 bool		is_server_available(const char *conninfo);
+bool		is_server_available_quiet(const char *conninfo);
 bool		is_server_available_params(t_conninfo_param_list *param_list);
-void		connection_ping(PGconn *conn);
+ExecStatusType	connection_ping(PGconn *conn);
+ExecStatusType	connection_ping_reconnect(PGconn *conn);

 /* monitoring functions  */
 void
@@ -491,8 +593,8 @@ add_monitoring_record(PGconn *primary_conn,
 					  long long unsigned int apply_lag_bytes
 );

-int			get_number_of_monitoring_records_to_delete(PGconn *primary_conn, int keep_history);
-bool		delete_monitoring_records(PGconn *primary_conn, int keep_history);
+int			get_number_of_monitoring_records_to_delete(PGconn *primary_conn, int keep_history, int node_id);
+bool		delete_monitoring_records(PGconn *primary_conn, int keep_history, int node_id);



@@ -506,12 +608,19 @@ bool		get_new_primary(PGconn *conn, int *primary_node_id);
 void		reset_voting_status(PGconn *conn);

 /* replication status functions */
-XLogRecPtr	get_current_wal_lsn(PGconn *conn);
+XLogRecPtr	get_primary_current_lsn(PGconn *conn);
+XLogRecPtr	get_node_current_lsn(PGconn *conn);
 XLogRecPtr	get_last_wal_receive_location(PGconn *conn);
-bool		get_replication_info(PGconn *conn, ReplInfo *replication_info);
+void		init_replication_info(ReplInfo *replication_info);
+bool		get_replication_info(PGconn *conn, t_server_type node_type, ReplInfo *replication_info);
 int			get_replication_lag_seconds(PGconn *conn);
-void		get_node_replication_stats(PGconn *conn, int server_version_num, t_node_info *node_info);
-bool		is_downstream_node_attached(PGconn *conn, char *node_name);
+TimeLineID	get_node_timeline(PGconn *conn);
+void		get_node_replication_stats(PGconn *conn, t_node_info *node_info);
+NodeAttached is_downstream_node_attached(PGconn *conn, char *node_name);
+void		set_upstream_last_seen(PGconn *conn, int upstream_node_id);
+int			get_upstream_last_seen(PGconn *conn, t_server_type node_type);
+
+bool		is_wal_replay_paused(PGconn *conn, bool check_pending_wal);

 /* BDR functions */
 int			get_bdr_version_num(void);
--- a/dirutil.c
+++ b/dirutil.c
@@ -3,7 +3,7 @@
 * dirmod.c
 *	  directory handling functions
 *
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
@@ -50,7 +50,7 @@ typedef long pgpid_t;
 * and tablespace directories.
 */
 DataDirState
-check_dir(char *path)
+check_dir(const char *path)
 {
 	DIR		   *chkdir = NULL;
 	struct dirent *file = NULL;
@@ -91,12 +91,17 @@ check_dir(char *path)
 * Create directory with error log message when failing
 */
 bool
-create_dir(char *path)
+create_dir(const char *path)
 {
-	if (mkdir_p(path, 0700) == 0)
+	char create_dir_path[MAXPGPATH];
+
+	/* mkdir_p() may modify the supplied path */
+	strncpy(create_dir_path, path, MAXPGPATH);
+
+	if (mkdir_p(create_dir_path, 0700) == 0)
 		return true;

-	log_error(_("unable to create directory \"%s\""), path);
+	log_error(_("unable to create directory \"%s\""), create_dir_path);
 	log_detail("%s", strerror(errno));

 	return false;
@@ -104,13 +109,12 @@ create_dir(char *path)


 bool
-set_dir_permissions(char *path)
+set_dir_permissions(const char *path)
 {
 	return (chmod(path, 0700) != 0) ? false : true;
 }


-
 /* function from initdb.c */
 /* source adapted from FreeBSD /src/bin/mkdir/mkdir.c */

@@ -198,9 +202,9 @@ mkdir_p(char *path, mode_t omode)


 bool
-is_pg_dir(char *path)
+is_pg_dir(const char *path)
 {
-	char		dirpath[MAXPGPATH];
+	char		dirpath[MAXPGPATH] = "";
 	struct stat sb;

 	/* test pgdata */
@@ -223,7 +227,7 @@ is_pg_dir(char *path)
 * any further useful progress can be made.
 */
 PgDirState
-is_pg_running(char *path)
+is_pg_running(const char *path)
 {
 	long		pid;
 	FILE	   *pidf;
@@ -272,6 +276,8 @@ is_pg_running(char *path)
 			log_warning(_("invalid data in PostgreSQL PID file \"%s\""), path);
 		}

+		fclose(pidf);
+
 		return PG_DIR_NOT_RUNNING;
 	}

@@ -291,7 +297,7 @@ is_pg_running(char *path)


 bool
-create_pg_dir(char *path, bool force)
+create_pg_dir(const char *path, bool force)
 {
 	/* Check this directory can be used as a PGDATA dir */
 	switch (check_dir(path))
@@ -330,6 +336,15 @@ create_pg_dir(char *path, bool force)
 				{
 					log_notice(_("-F/--force provided - deleting existing data directory \"%s\""), path);
 					nftw(path, unlink_dir_callback, 64, FTW_DEPTH | FTW_PHYS);
+
+					/* recreate the directory ourselves to ensure permissions are correct */
+					if (!create_dir(path))
+					{
+						log_error(_("unable to create directory \"%s\"..."),
+								  path);
+						return false;
+					}
+
 					return true;
 				}

@@ -341,14 +356,24 @@ create_pg_dir(char *path, bool force)
 				{
 					log_notice(_("deleting existing directory \"%s\""), path);
 					nftw(path, unlink_dir_callback, 64, FTW_DEPTH | FTW_PHYS);
+
+					/* recreate the directory ourselves to ensure permissions are correct */
+					if (!create_dir(path))
+					{
+						log_error(_("unable to create directory \"%s\"..."),
+								  path);
+						return false;
+					}
+
 					return true;
 				}
 				return false;
 			}
 			break;
 		case DIR_ERROR:
-			log_error(_("could not access directory \"%s\": %s"),
-					  path, strerror(errno));
+			log_error(_("could not access directory \"%s\"")
+					  , path);
+			log_detail("%s", strerror(errno));
 			return false;
 	}

@@ -358,7 +383,7 @@ create_pg_dir(char *path, bool force)


 int
-rmdir_recursive(char *path)
+rmdir_recursive(const char *path)
 {
 	return nftw(path, unlink_dir_callback, 64, FTW_DEPTH | FTW_PHYS);
 }
--- a/dirutil.h
+++ b/dirutil.h
@@ -1,6 +1,6 @@
 /*
 * dirutil.h
- * Copyright (c) 2ndQuadrant, 2010-2018
+ * Copyright (c) 2ndQuadrant, 2010-2019
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
@@ -35,13 +35,13 @@ typedef enum
 } PgDirState;

 extern int	mkdir_p(char *path, mode_t omode);
-extern bool set_dir_permissions(char *path);
+extern bool set_dir_permissions(const char *path);

-extern DataDirState	check_dir(char *path);
-extern bool create_dir(char *path);
-extern bool is_pg_dir(char *path);
-extern PgDirState is_pg_running(char *path);
-extern bool create_pg_dir(char *path, bool force);
-extern int rmdir_recursive(char *path);
+extern DataDirState	check_dir(const char *path);
+extern bool create_dir(const char *path);
+extern bool is_pg_dir(const char *path);
+extern PgDirState is_pg_running(const char *path);
+extern bool create_pg_dir(const char *path, bool force);
+extern int rmdir_recursive(const char *path);

 #endif
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,7 +1,9 @@
 HTML.index
-bookindex.sgml
+bookindex.xml
 html-stamp
 html/
-nochunks.dsl
 repmgr.html
-version.sgml
+version.xml
+*.fo
+*.pdf
+*.sgml
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -0,0 +1,102 @@
+# Make "html" the default target, since that is what most people tend
+# to want to use.
+html:
+
+all: html
+
+subdir = doc
+repmgr_top_builddir = ..
+include $(repmgr_top_builddir)/Makefile.global
+
+XMLINCLUDE = --path .
+
+ifndef XMLLINT
+XMLLINT = $(missing) xmllint
+endif
+
+ifndef XSLTPROC
+XSLTPROC = $(missing) xsltproc
+endif
+
+ifndef FOP
+FOP = $(missing) fop
+endif
+
+override XSLTPROCFLAGS += --stringparam repmgr.version '$(REPMGR_VERSION)'
+
+GENERATED_XML = version.xml
+ALLXML := $(wildcard $(srcdir)/*.xml) $(GENERATED_XML)
+
+
+version.xml: $(repmgr_top_builddir)/repmgr_version.h
+	{ \
+	  echo "<!ENTITY repmgrversion \"$(REPMGR_VERSION)\">"; \
+	  echo "<!ENTITY releasedate \"$(REPMGR_RELEASE_DATE)\">"; \
+	} > $@
+
+##
+## HTML
+##
+
+
+html: html-stamp
+
+html-stamp: stylesheet.xsl repmgr.xml $(ALLXML)
+	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
+	cp $(srcdir)/stylesheet.css  $(srcdir)/website-docs.css html/
+	touch $@
+
+# single-page HTML
+repmgr.html: stylesheet-html-nochunk.xsl repmgr.xml $(ALLXML)
+	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
+
+
+zip: html
+	cp -r html repmgr-docs-$(REPMGR_VERSION)
+	zip -r repmgr-docs-$(REPMGR_VERSION).zip repmgr-docs-$(REPMGR_VERSION)
+	rm -rf repmgr-docs-$(REPMGR_VERSION)
+
+##
+## Print
+##
+
+repmgr.pdf:
+	$(error Invalid target; use repmgr-A4.pdf or repmgr-US.pdf as targets)
+
+# Standard paper size
+
+repmgr-A4.fo: stylesheet-fo.xsl repmgr.xml $(ALLXML)
+	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
+
+repmgr-A4.pdf: repmgr-A4.fo
+	$(FOP) -fo $< -pdf $@
+
+# North American paper size
+
+repmgr-US.fo: stylesheet-fo.xsl repmgr.xml $(ALLXML)
+	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
+
+repmgr-US.pdf: repmgr-US.fo
+	$(FOP) -fo $< -pdf $@
+
+
+install: html
+	@$(MKDIR_P) $(DESTDIR)$(docdir)/$(docmoduledir)/repmgr
+	@$(INSTALL_DATA) $(wildcard html/*.html) $(wildcard html/*.css) $(DESTDIR)$(docdir)/$(docmoduledir)/repmgr
+	@echo Installed docs to $(DESTDIR)$(docdir)/$(docmoduledir)/repmgr
+
+clean:
+	rm -f html-stamp
+	rm -f HTML.index $(GENERATED_XML)
+	rm -f repmgr.html
+	rm -f repmgr-A4.pdf
+	rm -f repmgr-US.pdf
+
+maintainer-clean:
+	rm -rf html
+
+.PHONY: html
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -1,76 +0,0 @@
-repmgr_subdir = doc
-repmgr_top_builddir = ..
-include $(repmgr_top_builddir)/Makefile.global
-
-ifndef JADE
-JADE = $(missing) jade
-endif
-
-SGMLINCLUDE = -D . -D ${srcdir}
-
-SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged
-
-JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -t sgml -i output-html
-
-ALLSGML := $(wildcard $(srcdir)/*.sgml)
-# to build bookindex
-ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML))
-GENERATED_SGML = version.sgml bookindex.sgml
-
-Makefile: Makefile.in
-	cd $(repmgr_top_builddir) && ./config.status doc/Makefile
-
-all: html
-
-html: html-stamp
-
-html-stamp: repmgr.sgml $(ALLSGML) $(GENERATED_SGML) stylesheet.dsl website-docs.css
-	$(MKDIR_P) html
-	$(JADE.html.call) -d stylesheet.dsl -i include-index $<
-	cp $(srcdir)/stylesheet.css $(srcdir)/website-docs.css html/
-	touch $@
-
-repmgr.html: repmgr.sgml $(ALLSGML) $(GENERATED_SGML) stylesheet.dsl website-docs.css
-	sed '/html-index-filename/a\
-(define nochunks  #t)' <stylesheet.dsl >nochunks.dsl
-	$(JADE.html.call) -d nochunks.dsl -i include-index $< >repmgr.html
-
-version.sgml: ${repmgr_top_builddir}/repmgr_version.h
-	{ \
-	  echo "<!ENTITY repmgrversion \"$(REPMGR_VERSION)\">"; \
-	} > $@
-
-HTML.index: repmgr.sgml $(ALMOSTALLSGML) stylesheet.dsl
-	@$(MKDIR_P) html
-	$(JADE.html.call) -d stylesheet.dsl -V html-index $<
-
-website-docs.css:
-	@$(MKDIR_P) html
-	curl http://www.postgresql.org/media/css/docs.css > ${srcdir}/website-docs.css
-
-bookindex.sgml: HTML.index
-ifdef COLLATEINDEX
-	LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $<
-else
-	@$(missing) collateindex.pl $< $@
-endif
-
-clean:
-	rm -f html-stamp
-	rm -f HTML.index $(GENERATED_SGML)
-
-maintainer-clean:
-	rm -rf html
-	rm -rf Makefile
-
-zip: html
-	cp -r html repmgr-docs-$(REPMGR_VERSION)
-	zip -r repmgr-docs-$(REPMGR_VERSION).zip repmgr-docs-$(REPMGR_VERSION)
-	rm -rf repmgr-docs-$(REPMGR_VERSION)
-
-install: html
-	@$(MKDIR_P) $(DESTDIR)$(docdir)/$(docmoduledir)/repmgr
-	@$(INSTALL_DATA) $(wildcard html/*.html) $(wildcard html/*.css) $(DESTDIR)$(docdir)/$(docmoduledir)/repmgr
-	@echo Installed docs to $(DESTDIR)$(docdir)/$(docmoduledir)/repmgr
-
-.PHONY: html all
--- a/doc/appendix-faq.sgml
+++ b/doc/appendix-faq.sgml
@@ -1,307 +0,0 @@
-<appendix id="appendix-faq" xreflabel="FAQ">
- <indexterm>
-  <primary>FAQ (Frequently Asked Questions)</primary>
- </indexterm>
-
- <title>FAQ (Frequently Asked Questions)</title>
-
- <sect1 id="faq-general" xreflabel="General">
-  <title>General</title>
-
-  <sect2 id="faq-xrepmgr-version-diff" xreflabel="Version differences">
-    <title>What's the difference between the repmgr versions?</title>
-    <para>
-      &repmgr; 4 is a complete rewrite of the existing &repmgr; code base
-      and implements &repmgr; as a PostgreSQL extension. It
-      supports all PostgreSQL versions from 9.3 (although some &repmgr;
-      features are not available for PostgreSQL 9.3 and 9.4).
-     </para>
-     <para>
-      &repmgr; 3.x builds on the improved replication facilities added
-      in PostgreSQL 9.3, as well as improved automated failover support
-      via <application>repmgrd</application>, and is not compatible with PostgreSQL 9.2
-      and earlier. We recommend upgrading to &repmgr; 4, as the &repmgr; 3.x
-      series will no longer be actively maintained.
-     </para>
-     <para>
-      &repmgr; 2.x supports PostgreSQL 9.0 ~ 9.3. While it is compatible
-      with PostgreSQL 9.3, we recommend using repmgr 4.x. &repmgr; 2.x is
-      no longer maintained.
-     </para>
-  </sect2>
-
-  <sect2 id="faq-replication-slots-advantage" xreflabel="Advantages of replication slots">
-   <title>What's the advantage of using replication slots?</title>
-   <para>
-    Replication slots, introduced in PostgreSQL 9.4, ensure that the
-    primary server will retain WAL files until they have been consumed
-    by all standby servers. This makes WAL file management much easier,
-    and if used &repmgr; will no longer insist on a fixed minimum number
-    (default: 5000) of WAL files being retained.
-   </para>
-   <para>
-    However this does mean that if a standby is no longer connected to the
-    primary, the presence of the replication slot will cause WAL files
-    to be retained indefinitely.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-replication-slots-number" xreflabel="Number of replication slots">
-   <title>How many replication slots should I define in <varname>max_replication_slots</varname>?</title>
-   <para>
-    Normally at least same number as the number of standbys which will connect
-    to the node. Note that changes to <varname>max_replication_slots</varname> require a server
-    restart to take effect, and as there is no particular penalty for unused
-    replication slots, setting a higher figure will make adding new nodes
-    easier.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-hash-index" xreflabel="Hash indexes">
-   <title>Does &repmgr; support hash indexes?</title>
-   <para>
-    Before PostgreSQL 10, hash indexes were not WAL logged and are therefore not suitable
-    for use in streaming replication in PostgreSQL 9.6 and earlier. See the
-    <ulink url="https://www.postgresql.org/docs/9.6/static/sql-createindex.html#AEN80279">PostgreSQL documentation</ulink>
-    for details.
-   </para>
-   <para>
-    From PostgreSQL 10, this restriction has been lifted and hash indexes can be used
-    in a streaming replication cluster.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-upgrades" xreflabel="Upgrading PostgreSQL with repmgr">
-   <title>Can &repmgr; assist with upgrading a PostgreSQL cluster?</title>
-   <para>
-     For <emphasis>minor</emphasis> version upgrades, e.g. from 9.6.7 to 9.6.8, a common
-     approach is to upgrade a standby to the latest version, perform a
-     <link linkend="performing-switchover">switchover</link> promoting it to a primary,
-     then upgrade the former primary.
-   </para>
-   <para>
-     For <emphasis>major</emphasis> version upgrades (e.g. from PostgreSQL 9.6 to PostgreSQL 10),
-     the traditional approach is to "reseed" a cluster by upgrading a single
-     node with <ulink url="https://www.postgresql.org/docs/current/static/pgupgrade.html">pg_upgrade</ulink>
-     and recloning standbys from this.
-   </para>
-   <para>
-     To minimize downtime during major upgrades, for more recent PostgreSQL
-     versions (PostgreSQL 9.4 and later),
-     <ulink url="https://www.2ndquadrant.com/en/resources/pglogical/">pglogical</ulink>
-     can be used to set up a parallel cluster using the newer PostgreSQL version,
-     which can be kept in sync with the existing production cluster until the
-     new cluster is ready to be put into production.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-libdir-repmgr-error">
-   <title>What does this error mean: <literal>ERROR: could not access file "$libdir/repmgr"</literal>?</title>
-   <para>
-     It means the &repmgr; extension code is not installed in the
-     PostgreSQL application directory. This typically happens when using PostgreSQL
-     packages provided by a third-party vendor, which often have different
-     filesystem layouts.
-   </para>
-   <para>
-     Either use PostgreSQL packages provided by the community or 2ndQuadrant; if this
-     is not possible, contact your vendor for assistance.
-   </para>
-  </sect2>
- </sect1>
-
- <sect1 id="faq-repmgr" xreflabel="repmgr">
-  <title><command>repmgr</command></title>
-
-  <sect2 id="faq-register-existing-node" xreflabel="registering an existing node">
-   <title>Can I register an existing PostgreSQL server with repmgr?</title>
-   <para>
-    Yes, any existing PostgreSQL server which is part of the same replication
-    cluster can be registered with &repmgr;. There's no requirement for a
-    standby to have been cloned using &repmgr;.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-clone-other-source" >
-   <title>Can I use a standby not cloned by &repmgr; as a &repmgr; node?</title>
-
-   <para>
-     For a standby which has been manually cloned or recovered from an external
-     backup manager such as Barman, the command
-     <command><link linkend="repmgr-standby-clone">repmgr standby clone --recovery-conf-only</link></command>
-     can be used to create the correct <filename>recovery.conf</filename> file for
-     use with &repmgr; (and will create a replication slot if required). Once this has been done,
-     <link linkend="repmgr-standby-register">register the node</link> as usual.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-recovery-conf" >
-    <title>What does &repmgr; write in <filename>recovery.conf</filename>, and what options can be set there?</title>
-   <para>
-     See section <link linkend="repmgr-standby-clone-recovery-conf">Customising recovery.conf</link>.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-failed-primary-standby" xreflabel="Reintegrate a failed primary as a standby">
-   <title>How can a failed primary be re-added as a standby?</title>
-   <para>
-    This is a two-stage process. First, the failed primary's data directory
-    must be re-synced with the current primary; secondly the failed primary
-    needs to be re-registered as a standby.
-   </para>
-   <para>
-    It's possible to use <command>pg_rewind</command> to re-synchronise the existing data
-    directory, which will usually be much
-    faster than re-cloning the server. However <command>pg_rewind</command> can only
-    be used if PostgreSQL either has <varname>wal_log_hints</varname> enabled, or
-    data checksums were enabled when the cluster was initialized.
-   </para>
-   <para>
-     Note that <command>pg_rewind</command> is available as part of the core PostgreSQL
-     distribution from PostgreSQL 9.5, and as a third-party utility for PostgreSQL 9.3 and 9.4.
-   </para>
-   <para>
-    &repmgr; provides the command <command>repmgr node rejoin</command> which can
-    optionally execute <command>pg_rewind</command>; see the <xref linkend="repmgr-node-rejoin">
-    documentation for details, in particular the section <xref linkend="repmgr-node-rejoin-pg-rewind">.
-   </para>
-   <para>
-    If <command>pg_rewind</command> cannot be used, then the data directory will need
-    to be re-cloned from scratch.
-   </para>
-
-  </sect2>
-
-  <sect2 id="faq-repmgr-check-configuration" xreflabel="Check PostgreSQL configuration">
-   <title>Is there an easy way to check my primary server is correctly configured for use with &repmgr;?</title>
-   <para>
-    Execute <command><link linkend="repmgr-standby-clone">repmgr standby clone</link></command>
-    with the <literal>--dry-run</literal> option; this will report any configuration problems
-    which need to be rectified.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-clone-skip-config-files" xreflabel="">
-   <title>When cloning a standby, how can I get &repmgr; to copy
-     <filename>postgresql.conf</filename> and <filename>pg_hba.conf</filename> from the PostgreSQL configuration
-     directory in <filename>/etc</filename>?</title>
-   <para>
-    Use the command line option <literal>--copy-external-config-files</literal>. For more details
-    see <xref linkend="repmgr-standby-clone-config-file-copying">.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-shared-preload-libaries-no-repmgrd" xreflabel="shared_preload_libraries without repmgrd">
-    <title>Do I need to include <literal>shared_preload_libraries = 'repmgr'</literal>
-      in <filename>postgresql.conf</filename> if I'm not using <application>repmgrd</application>?</title>
-   <para>
-    No, the <literal>repmgr</literal> shared library is only needed when running <application>repmgrd</application>.
-    If you later decide to run <application>repmgrd</application>, you just need to add
-    <literal>shared_preload_libraries = 'repmgr'</literal> and restart PostgreSQL.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-permissions" xreflabel="Replication permission problems">
-   <title>I've provided replication permission for the <literal>repmgr</literal> user in <filename>pg_hba.conf</filename>
-     but <command>repmgr</command>/<application>repmgrd</application> complains it can't connect to the server... Why?</title>
-   <para>
-    <command>repmgr</command> and <application>repmgrd</application> need to be able to connect to the repmgr database
-    with a normal connection to query metadata. The <literal>replication</literal> connection
-    permission is for PostgreSQL's streaming replication (and doesn't  necessarily need to be the <literal>repmgr</literal> user).
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-clone-provide-primary-conninfo" xreflabel="Providing primary connection parameters">
-   <title>When cloning a standby, why do I need to provide the connection parameters
-     for the primary server on the command line, not in the configuration file?</title>
-   <para>
-    Cloning a standby is a one-time action; the role of the server being cloned
-    from could change, so fixing it in the configuration file would create
-    confusion. If &repmgr; needs to establish a connection to the primary
-    server, it can retrieve this from the <literal>repmgr.nodes</literal> table on the local
-    node, and if necessary scan the replication cluster until it locates the active primary.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-clone-waldir-xlogdir" xreflabel="Providing a custom WAL directory">
-   <title>When cloning a standby, how do I ensure the WAL files are placed in a custom directory?</title>
-   <para>
-     Provide the option <literal>--waldir</literal>  (<literal>--xlogdir</literal> in PostgreSQL 9.6
-     and earlier) with the absolute path to the WAL directory in <varname>pg_basebackup_options</varname>.
-     For more details see <xref linkend="cloning-advanced-pg-basebackup-options">.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgr-events-no-fkey" xreflabel="No foreign key on node_id in repmgr.events">
-   <title>Why is there no foreign key on the <literal>node_id</literal> column in the <literal>repmgr.events</literal>
-     table?</title>
-   <para>
-     Under some circumstances event notifications can be generated for servers
-     which have not yet been registered; it's also useful to retain a record
-     of events which includes servers removed from the replication cluster
-     which no longer have an entry in the <literal>repmrg.nodes</literal> table.
-   </para>
-  </sect2>
-
-
-
-
- </sect1>
-
- <sect1 id="faq-repmgrd" xreflabel="repmgrd">
-  <title><application>repmgrd</application></title>
-
-
-  <sect2 id="faq-repmgrd-prevent-promotion" xreflabel="Prevent standby from being promoted to primary">
-   <title>How can I prevent a node from ever being promoted to primary?</title>
-   <para>
-    In `repmgr.conf`, set its priority to a value of 0 or less; apply the changed setting with
-    <command><link linkend="repmgr-standby-register">repmgr standby register --force</link></command>.
-   </para>
-   <para>
-    Additionally, if <varname>failover</varname> is set to <literal>manual</literal>, the node will never
-    be considered as a promotion candidate.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgrd-delayed-standby" xreflabel="Delayed standby support">
-   <title>Does <application>repmgrd</application> support delayed standbys?</title>
-   <para>
-    <application>repmgrd</application> can monitor delayed standbys - those set up with
-    <varname>recovery_min_apply_delay</varname> set to a non-zero value
-    in <filename>recovery.conf</filename> - but as it's not currently possible
-    to directly examine the value applied to the standby, <application>repmgrd</application>
-    may not be able to properly evaluate the node as a promotion candidate.
-   </para>
-   <para>
-    We recommend that delayed standbys are explicitly excluded from promotion
-    by setting <varname>priority</varname> to <literal>0</literal> in
-    <filename>repmgr.conf</filename>.
-   </para>
-   <para>
-    Note that after registering a delayed standby, <application>repmgrd</application> will only start
-    once the metadata added in the primary node has been replicated.
-   </para>
-  </sect2>
-
-  <sect2 id="faq-repmgrd-logfile-rotate" xreflabel="repmgrd logfile rotation">
-   <title>How can I get <application>repmgrd</application> to rotate its logfile?</title>
-   <para>
-     Configure your system's <literal>logrotate</literal> service to do this; see <xref linkend="repmgrd-log-rotation">.
-   </para>
-
-  </sect2>
-
-  <sect2 id="faq-repmgrd-recloned-no-start" xreflabel="repmgrd not restarting after node cloned">
-   <title>I've recloned a failed primary as a standby, but <application>repmgrd</application> refuses to start?</title>
-   <para>
-    Check you registered the standby after recloning. If unregistered, the standby
-    cannot be considered as a promotion candidate even if <varname>failover</varname> is set to
-    <literal>automatic</literal>, which is probably not what you want. <application>repmgrd</application> will start if
-    <varname>failover</varname> is set to <literal>manual</literal> so the node's replication status can still
-  be monitored, if desired.
-   </para>
-  </sect2>
-
- </sect1>
-</appendix>
--- a/doc/appendix-faq.xml
+++ b/doc/appendix-faq.xml
@@ -0,0 +1,466 @@
+<appendix id="appendix-faq" xreflabel="FAQ">
+
+  <title>FAQ (Frequently Asked Questions)</title>
+
+  <indexterm>
+    <primary>FAQ (Frequently Asked Questions)</primary>
+  </indexterm>
+
+  <sect1 id="faq-general" xreflabel="General">
+    <title>General</title>
+
+    <sect2 id="faq-xrepmgr-version-diff" xreflabel="Version differences">
+      <title>What's the difference between the repmgr versions?</title>
+      <para>
+        &repmgr; 4 is a complete rewrite of the previous &repmgr; code base
+        and implements &repmgr; as a PostgreSQL extension. It
+        supports all PostgreSQL versions from 9.3 (although some &repmgr;
+        features are not available for PostgreSQL 9.3 and 9.4).
+      </para>
+      <note>
+        <para>
+          &repmgr; 5 is fundamentally the same code base as &repmgr; 4, but provides
+          support for the revised replication configuration mechanism in PostgreSQL 12.
+        </para>
+      </note>
+      <para>
+        &repmgr; 3.x builds on the improved replication facilities added
+        in PostgreSQL 9.3, as well as improved automated failover support
+        via &repmgrd;, and is not compatible with PostgreSQL 9.2
+        and earlier. We recommend upgrading to &repmgr; 4, as the &repmgr; 3.x
+        series is no longer maintained.
+      </para>
+      <para>
+        &repmgr; 2.x supports PostgreSQL 9.0 ~ 9.3. While it is compatible
+        with PostgreSQL 9.3, we recommend using repmgr 4.x. &repmgr; 2.x is
+        no longer maintained.
+      </para>
+      <para>
+        See also <link linkend="install-compatibility-matrix">&repmgr; compatibility matrix</link>
+        and <link linkend="faq-upgrade-repmgr">Should I upgrade &repmgr;?</link>.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-replication-slots-advantage" xreflabel="Advantages of replication slots">
+      <title>What's the advantage of using replication slots?</title>
+      <para>
+        Replication slots, introduced in PostgreSQL 9.4, ensure that the
+        primary server will retain WAL files until they have been consumed
+        by all standby servers. This means standby servers should never
+        fail due to not being able to retrieve required WAL files from the
+        primary.
+      </para>
+      <para>
+        However this does mean that if a standby is no longer connected to the
+        primary, the presence of the replication slot will cause WAL files
+        to be retained indefinitely, and eventually lead to disk space
+        exhaustion.
+      </para>
+
+      <tip>
+        <para>
+          2ndQuadrant's recommended configuration is to configure
+          <ulink url="https://www.pgbarman.org/">Barman</ulink> as a fallback
+          source of WAL files, rather than maintain replication slots for
+          each standby. See also: <link linkend="cloning-from-barman-restore-command">Using Barman as a WAL file source</link>.
+        </para>
+      </tip>
+    </sect2>
+
+    <sect2 id="faq-replication-slots-number" xreflabel="Number of replication slots">
+      <title>How many replication slots should I define in <varname>max_replication_slots</varname>?</title>
+      <para>
+        Normally at least same number as the number of standbys which will connect
+        to the node. Note that changes to <varname>max_replication_slots</varname> require a server
+        restart to take effect, and as there is no particular penalty for unused
+        replication slots, setting a higher figure will make adding new nodes
+        easier.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-hash-index" xreflabel="Hash indexes">
+      <title>Does &repmgr; support hash indexes?</title>
+      <para>
+        Before PostgreSQL 10, hash indexes were not WAL logged and are therefore not suitable
+        for use in streaming replication in PostgreSQL 9.6 and earlier. See the
+        <ulink url="https://www.postgresql.org/docs/9.6/sql-createindex.html#AEN80279">PostgreSQL documentation</ulink>
+        for details.
+      </para>
+      <para>
+        From PostgreSQL 10, this restriction has been lifted and hash indexes can be used
+        in a streaming replication cluster.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-upgrades" xreflabel="Upgrading PostgreSQL with repmgr">
+      <title>Can &repmgr; assist with upgrading a PostgreSQL cluster?</title>
+      <para>
+        For <emphasis>minor</emphasis> version upgrades, e.g. from 9.6.7 to 9.6.8, a common
+        approach is to upgrade a standby to the latest version, perform a
+        <link linkend="performing-switchover">switchover</link> promoting it to a primary,
+        then upgrade the former primary.
+      </para>
+      <para>
+        For <emphasis>major</emphasis> version upgrades (e.g. from PostgreSQL 9.6 to PostgreSQL 10),
+        the traditional approach is to "reseed" a cluster by upgrading a single
+        node with <ulink url="https://www.postgresql.org/docs/current/pgupgrade.html">pg_upgrade</ulink>
+        and recloning standbys from this.
+      </para>
+      <para>
+        To minimize downtime during major upgrades from PostgreSQL 9.4 and later,
+        <ulink url="https://www.2ndquadrant.com/en/resources/pglogical/">pglogical</ulink>
+        can be used to set up a parallel cluster using the newer PostgreSQL version,
+        which can be kept in sync with the existing production cluster until the
+        new cluster is ready to be put into production.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-libdir-repmgr-error">
+      <title>What does this error mean: <literal>ERROR: could not access file "$libdir/repmgr"</literal>?</title>
+      <para>
+        It means the &repmgr; extension code is not installed in the
+        PostgreSQL application directory. This typically happens when using PostgreSQL
+        packages provided by a third-party vendor, which often have different
+        filesystem layouts.
+      </para>
+      <para>
+        Either use PostgreSQL packages provided by the community or 2ndQuadrant; if this
+        is not possible, contact your vendor for assistance.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-old-packages">
+      <title>How can I obtain old versions of &repmgr; packages?</title>
+      <para>
+        See appendix <xref linkend="packages-old-versions"/> for details.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-required-for-replication">
+      <title>Is &repmgr; required for streaming replication?</title>
+      <para>
+        No.
+      </para>
+      <para>
+        &repmgr; (together with &repmgrd;) assists with
+        <emphasis>managing</emphasis> replication. It does not actually perform replication, which
+        is part of the core PostgreSQL functionality.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-what-if-repmgr-uninstalled">
+      <title>Will replication stop working if &repmgr; is uninstalled?</title>
+      <para>
+        No. See preceding question.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-version-mix">
+      <title>Does it matter if different &repmgr; versions are present in the replication cluster?</title>
+      <para>
+        Yes. If different &quot;major&quot; &repmgr; versions (e.g. 3.3.x and 4.1.x) are present,
+        &repmgr; (in particular &repmgrd;)
+        may not run, or run properly, or in the worst case (if different &repmgrd;
+        versions are running and there are differences in the failover implementation) break
+        your replication cluster.
+      </para>
+      <para>
+        If different &quot;minor&quot; &repmgr; versions (e.g. 4.1.1 and 4.1.6) are installed,
+        &repmgr; will function, but we strongly recommend always running the same version
+        to ensure there are no unexpected suprises, e.g. a newer version behaving slightly
+        differently to the older version.
+      </para>
+      <para>
+        See also <link linkend="faq-upgrade-repmgr">Should I upgrade &repmgr;?</link>.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-upgrade-repmgr">
+      <title>Should I upgrade &repmgr;?</title>
+      <para>
+        Yes.
+      </para>
+      <para>
+        We don't release new versions for fun, you know. Upgrading may require a little effort,
+        but running an older &repmgr; version with bugs which have since been fixed may end up
+        costing you more effort. The same applies to PostgreSQL itself.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-conf-data-directory">
+      <title>Why do I need to specify the data directory location in repmgr.conf?</title>
+      <para>
+        In some circumstances &repmgr; may need to access a PostgreSQL data
+        directory while the PostgreSQL server is not running, e.g. to confirm
+        it shut down cleanly during a <link linkend="performing-switchover">switchover</link>.
+      </para>
+      <para>
+        Additionally, this provides support when using &repmgr; on PostgreSQL 9.6 and
+        earlier, where the <literal>repmgr</literal> user is not a superuser; in that
+        case the <literal>repmgr</literal> user will not be able to access the
+        <literal>data_directory</literal> configuration setting, access to which is restricted
+        to superusers.
+      </para>
+      <para>
+        In PostgreSQL 10 and later, non-superusers can be added to the
+        <ulink url="https://www.postgresql.org/docs/current/default-roles.html">default role</ulink>
+        <option>pg_read_all_settings</option> (or the meta-role <option>pg_monitor</option>)
+        which will enable them to read this setting.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-third-party-packages" xreflabel="Compatability with third party vendor packages">
+      <title>Are &repmgr; packages compatible with <literal>$third_party_vendor</literal>'s packages?</title>
+      <para>
+        &repmgr; packages provided by 2ndQuadrant are compatible with the community-provided PostgreSQL
+        packages and any software provided by 2ndQuadrant.
+      </para>
+      <para>
+        A number of other vendors provide their own versions of PostgreSQL packages, often with different
+        package naming schemes and/or file locations.
+      </para>
+      <para>
+        We cannot guarantee that &repmgr; packages will be compatible with these packages.
+        It may be possible to override package dependencies (e.g. <literal>rpm --nodeps</literal>
+        for CentOS-based systems or <literal>dpkg --force-depends</literal> for Debian-based systems).
+      </para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="faq-repmgr" xreflabel="repmgr">
+    <title><command>repmgr</command></title>
+
+    <sect2 id="faq-register-existing-node" xreflabel="registering an existing node">
+      <title>Can I register an existing PostgreSQL server with repmgr?</title>
+      <para>
+        Yes, any existing PostgreSQL server which is part of the same replication
+        cluster can be registered with &repmgr;. There's no requirement for a
+        standby to have been cloned using &repmgr;.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-clone-other-source" >
+      <title>Can I use a standby not cloned by &repmgr; as a &repmgr; node?</title>
+
+      <para>
+        For a standby which has been manually cloned or recovered from an external
+        backup manager such as Barman, the command
+        <command><link linkend="repmgr-standby-clone">repmgr standby clone --recovery-conf-only</link></command>
+        can be used to create the correct <filename>recovery.conf</filename> file for
+        use with &repmgr; (and will create a replication slot if required). Once this has been done,
+        <link linkend="repmgr-standby-register">register the node</link> as usual.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-recovery-conf" >
+      <title>What does &repmgr; write in <filename>recovery.conf</filename>, and what options can be set there?</title>
+      <para>
+        See section <link linkend="repmgr-standby-clone-recovery-conf">Customising recovery.conf</link>.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-failed-primary-standby" xreflabel="Reintegrate a failed primary as a standby">
+      <title>How can a failed primary be re-added as a standby?</title>
+      <para>
+        This is a two-stage process. First, the failed primary's data directory
+        must be re-synced with the current primary; secondly the failed primary
+        needs to be re-registered as a standby.
+      </para>
+      <para>
+        It's possible to use <command>pg_rewind</command> to re-synchronise the existing data
+        directory, which will usually be much
+        faster than re-cloning the server. However <command>pg_rewind</command> can only
+        be used if PostgreSQL either has <varname>wal_log_hints</varname> enabled, or
+        data checksums were enabled when the cluster was initialized.
+      </para>
+      <para>
+        Note that <command>pg_rewind</command> is available as part of the core PostgreSQL
+        distribution from PostgreSQL 9.5, and as a third-party utility for PostgreSQL 9.3 and 9.4.
+      </para>
+      <para>
+        &repmgr; provides the command <command>repmgr node rejoin</command> which can
+        optionally execute <command>pg_rewind</command>; see the <xref linkend="repmgr-node-rejoin"/>
+        documentation for details, in particular the section <xref linkend="repmgr-node-rejoin-pg-rewind"/>.
+      </para>
+      <para>
+        If <command>pg_rewind</command> cannot be used, then the data directory will need
+        to be re-cloned from scratch.
+      </para>
+
+    </sect2>
+
+    <sect2 id="faq-repmgr-check-configuration" xreflabel="Check PostgreSQL configuration">
+      <title>Is there an easy way to check my primary server is correctly configured for use with &repmgr;?</title>
+      <para>
+        Execute <command><link linkend="repmgr-standby-clone">repmgr standby clone</link></command>
+        with the <literal>--dry-run</literal> option; this will report any configuration problems
+        which need to be rectified.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-clone-skip-config-files" xreflabel="">
+      <title>When cloning a standby, how can I get &repmgr; to copy
+        <filename>postgresql.conf</filename> and <filename>pg_hba.conf</filename> from the PostgreSQL configuration
+        directory in <filename>/etc</filename>?</title>
+      <para>
+        Use the command line option <literal>--copy-external-config-files</literal>. For more details
+        see <xref linkend="repmgr-standby-clone-config-file-copying"/>.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-shared-preload-libaries-no-repmgrd" xreflabel="shared_preload_libraries without repmgrd">
+      <title>Do I need to include <literal>shared_preload_libraries = 'repmgr'</literal>
+        in <filename>postgresql.conf</filename> if I'm not using &repmgrd;?</title>
+      <para>
+        No, the <literal>repmgr</literal> shared library is only needed when running &repmgrd;.
+        If you later decide to run &repmgrd;, you just need to add
+        <literal>shared_preload_libraries = 'repmgr'</literal> and restart PostgreSQL.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-permissions" xreflabel="Replication permission problems">
+      <title>I've provided replication permission for the <literal>repmgr</literal> user in <filename>pg_hba.conf</filename>
+        but <command>repmgr</command>/&repmgrd; complains it can't connect to the server... Why?</title>
+      <para>
+        <command>repmgr</command> and &repmgrd; need to be able to connect to the repmgr database
+        with a normal connection to query metadata. The <literal>replication</literal> connection
+        permission is for PostgreSQL's streaming replication (and doesn't  necessarily need to be the <literal>repmgr</literal> user).
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-clone-provide-primary-conninfo" xreflabel="Providing primary connection parameters">
+      <title>When cloning a standby, why do I need to provide the connection parameters
+        for the primary server on the command line, not in the configuration file?</title>
+      <para>
+        Cloning a standby is a one-time action; the role of the server being cloned
+        from could change, so fixing it in the configuration file would create
+        confusion. If &repmgr; needs to establish a connection to the primary
+        server, it can retrieve this from the <literal>repmgr.nodes</literal> table on the local
+        node, and if necessary scan the replication cluster until it locates the active primary.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-clone-waldir-xlogdir" xreflabel="Providing a custom WAL directory">
+      <title>When cloning a standby, how do I ensure the WAL files are placed in a custom directory?</title>
+      <para>
+        Provide the option <literal>--waldir</literal>  (<literal>--xlogdir</literal> in PostgreSQL 9.6
+        and earlier) with the absolute path to the WAL directory in <varname>pg_basebackup_options</varname>.
+        For more details see <xref linkend="cloning-advanced-pg-basebackup-options"/>.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-events-no-fkey" xreflabel="No foreign key on node_id in repmgr.events">
+      <title>Why is there no foreign key on the <literal>node_id</literal> column in the <literal>repmgr.events</literal>
+        table?</title>
+      <para>
+        Under some circumstances event notifications can be generated for servers
+        which have not yet been registered; it's also useful to retain a record
+        of events which includes servers removed from the replication cluster
+        which no longer have an entry in the <literal>repmgr.nodes</literal> table.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgr-recovery-conf-quoted-values" xreflabel="Quoted values in recovery.conf">
+      <title>Why are some values in <filename>recovery.conf</filename> surrounded by pairs of single quotes?</title>
+      <para>
+        This is to ensure that user-supplied values which are written as parameter values in <filename>recovery.conf</filename>
+        are escaped correctly and do not cause errors when <filename>recovery.conf</filename> is parsed.
+      </para>
+      <para>
+        The escaping is performed by an internal PostgreSQL routine, which leaves strings consisting
+        of digits and alphabetical characters only as-is, but wraps everything else in pairs of single quotes,
+        even if the string does not contain any characters which need escaping.
+      </para>
+    </sect2>
+
+
+  </sect1>
+
+  <sect1 id="faq-repmgrd" xreflabel="repmgrd">
+    <title>&repmgrd;</title>
+
+
+    <sect2 id="faq-repmgrd-prevent-promotion" xreflabel="Prevent standby from being promoted to primary">
+      <title>How can I prevent a node from ever being promoted to primary?</title>
+      <para>
+        In <filename>repmgr.conf</filename>, set its priority to a value of <literal>0</literal>; apply the changed setting with
+        <command><link linkend="repmgr-standby-register">repmgr standby register --force</link></command>.
+      </para>
+      <para>
+        Additionally, if <varname>failover</varname> is set to <literal>manual</literal>, the node will never
+        be considered as a promotion candidate.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgrd-delayed-standby" xreflabel="Delayed standby support">
+      <title>Does &repmgrd; support delayed standbys?</title>
+      <para>
+        &repmgrd; can monitor delayed standbys - those set up with
+        <varname>recovery_min_apply_delay</varname> set to a non-zero value
+        in <filename>recovery.conf</filename> - but as it's not currently possible
+        to directly examine the value applied to the standby, &repmgrd;
+        may not be able to properly evaluate the node as a promotion candidate.
+      </para>
+      <para>
+        We recommend that delayed standbys are explicitly excluded from promotion
+        by setting <varname>priority</varname> to <literal>0</literal> in
+        <filename>repmgr.conf</filename>.
+      </para>
+      <para>
+        Note that after registering a delayed standby, &repmgrd; will only start
+        once the metadata added in the primary node has been replicated.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgrd-logfile-rotate" xreflabel="repmgrd logfile rotation">
+      <title>How can I get &repmgrd; to rotate its logfile?</title>
+      <para>
+        Configure your system's <literal>logrotate</literal> service to do this; see <xref linkend="repmgrd-log-rotation"/>.
+      </para>
+
+    </sect2>
+
+    <sect2 id="faq-repmgrd-recloned-no-start" xreflabel="repmgrd not restarting after node cloned">
+      <title>I've recloned a failed primary as a standby, but &repmgrd; refuses to start?</title>
+      <para>
+        Check you registered the standby after recloning. If unregistered, the standby
+        cannot be considered as a promotion candidate even if <varname>failover</varname> is set to
+        <literal>automatic</literal>, which is probably not what you want. &repmgrd; will start if
+        <varname>failover</varname> is set to <literal>manual</literal> so the node's replication status can still
+        be monitored, if desired.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgrd-pg-bindir" xreflabel="repmgrd does not apply pg_bindir to promote_command or follow_command">
+      <title>
+        &repmgrd; ignores pg_bindir when executing <varname>promote_command</varname> or <varname>follow_command</varname>
+      </title>
+      <para>
+        <varname>promote_command</varname> or <varname>follow_command</varname> can be user-defined scripts,
+        so &repmgr; will not apply <option>pg_bindir</option> even if excuting &repmgr;. Always provide the full
+        path; see <xref linkend="repmgrd-automatic-failover-configuration"/> for more details.
+      </para>
+    </sect2>
+
+    <sect2 id="faq-repmgrd-startup-no-upstream" xreflabel="repmgrd does not start if upstream node is not running">
+      <title>
+        &repmgrd; aborts startup with the error "<literal>upstream node must be running before repmgrd can start</literal>"
+      </title>
+      <para>
+        &repmgrd; does this to avoid starting up on a replication cluster
+        which is not in a healthy state. If the upstream is unavailable, &repmgrd;
+        may initiate a failover immediately after starting up, which could have unintended side-effects,
+        particularly if &repmgrd; is not running on other nodes.
+      </para>
+      <para>
+        In particular, it's possible that the node's local copy of the <literal>repmgr.nodes</literal> copy
+        is out-of-date, which may lead to incorrect failover behaviour.
+      </para>
+      <para>
+        The onus is therefore on the adminstrator to manually set the cluster to a stable, healthy state before
+        starting &repmgrd;.
+      </para>
+    </sect2>
+
+  </sect1>
+</appendix>
--- a/doc/appendix-packages.sgml
+++ b/doc/appendix-packages.sgml
@@ -1,9 +1,11 @@
 <appendix id="appendix-packages" xreflabel="Package details">
+
+  <title>&repmgr; package details</title>
+
  <indexterm>
    <primary>packages</primary>
  </indexterm>

-  <title>&repmgr; package details</title>
  <para>
    This section provides technical details about various &repmgr; binary
    packages, such as location of the installed binaries and
@@ -12,10 +14,17 @@

  <sect1 id="packages-centos" xreflabel="CentOS packages">
    <title>CentOS Packages</title>
+
    <indexterm>
      <primary>packages</primary>
      <secondary>CentOS packages</secondary>
    </indexterm>
+
+    <indexterm>
+      <primary>CentOS</primary>
+      <secondary>package information</secondary>
+    </indexterm>
+
    <para>
      Currently, &repmgr; RPM packages are provided for versions 6.x and 7.x of CentOS. These should also
      work on matching versions of Red Hat Enterprise Linux, Scientific Linux and Oracle Enterprise Linux;
@@ -53,11 +62,11 @@
          <tbody>
            <row>
              <entry>Repository URL:</entry>
-              <entry><ulink url="https://rpm.2ndquadrant.com/">https://rpm.2ndquadrant.com/</ulink></entry>
+              <entry><ulink url="https://dl.2ndquadrant.com/">https://dl.2ndquadrant.com/</ulink></entry>
            </row>
            <row>
              <entry>Repository documentation:</entry>
-              <entry><ulink url="https://repmgr.org/docs/4.0/installation-packages.html#INSTALLATION-PACKAGES-REDHAT-2NDQ">https://repmgr.org/docs/4.0/installation-packages.html#INSTALLATION-PACKAGES-REDHAT-2NDQ</ulink></entry>
+              <entry><ulink url="https://repmgr.org/docs/current/installation-packages.html#INSTALLATION-PACKAGES-REDHAT-2NDQ">https://repmgr.org/docs/current/installation-packages.html#INSTALLATION-PACKAGES-REDHAT-2NDQ</ulink></entry>
            </row>
          </tbody>
        </tgroup>
@@ -113,7 +122,7 @@

     <row>
      <entry>Package name example:</entry>
-      <entry><filename>repmgr10-4.0.4-1.rhel7.x86_64</filename></entry>
+      <entry><filename>repmgr11-4.4.0-1.rhel7.x86_64</filename></entry>
     </row>

     <row>
@@ -123,12 +132,12 @@

     <row>
      <entry>Installation command:</entry>
-      <entry><literal>yum install repmgr10</literal></entry>
+      <entry><literal>yum install repmgr11</literal></entry>
     </row>

     <row>
      <entry>Binary location:</entry>
-      <entry><filename>/usr/pgsql-10/bin</filename></entry>
+      <entry><filename>/usr/pgsql-11/bin</filename></entry>
     </row>

     <row>
@@ -138,22 +147,22 @@

     <row>
      <entry>Configuration file location:</entry>
-      <entry><filename>/etc/repmgr/10/repmgr.conf</filename></entry>
+      <entry><filename>/etc/repmgr/11/repmgr.conf</filename></entry>
     </row>

     <row>
      <entry>Data directory:</entry>
-      <entry><filename>/var/lib/pgsql/10/data</filename></entry>
+      <entry><filename>/var/lib/pgsql/11/data</filename></entry>
     </row>

     <row>
      <entry>repmgrd service command:</entry>
-      <entry><command>systemctl [start|stop|restart|reload] repmgr10</command></entry>
+      <entry><command>systemctl [start|stop|restart|reload] repmgr11</command></entry>
     </row>

     <row>
      <entry>repmgrd service file location:</entry>
-      <entry><filename>/usr/lib/systemd/system/repmgr10.service</filename></entry>
+      <entry><filename>/usr/lib/systemd/system/repmgr11.service</filename></entry>
     </row>

     <row>
@@ -237,6 +246,12 @@
      <primary>packages</primary>
      <secondary>Debian/Ubuntu packages</secondary>
    </indexterm>
+
+    <indexterm>
+      <primary>Debian/Ubuntu</primary>
+      <secondary>package information</secondary>
+    </indexterm>
+
    <para>
      &repmgr; <literal>.deb</literal> packages are provided via the
      PostgreSQL Community APT repository, and are available for each community-supported
@@ -253,6 +268,23 @@
      </para>


+      <table id="apt-2ndquadrant-repository">
+        <title>2ndQuadrant public repository</title>
+        <tgroup cols="2">
+          <tbody>
+            <row>
+              <entry>Repository URL:</entry>
+              <entry><ulink url="https://dl.2ndquadrant.com/">https://dl.2ndquadrant.com/</ulink></entry>
+            </row>
+            <row>
+              <entry>Repository documentation:</entry>
+              <entry><ulink url="https://repmgr.org/docs/current/installation-packages.html#INSTALLATION-PACKAGES-DEBIAN">https://repmgr.org/docs/current/installation-packages.html#INSTALLATION-PACKAGES-DEBIAN</ulink></entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+
      <table id="apt-repository">
        <title>PostgreSQL Community APT repository (PGDG)</title>
        <tgroup cols="2">
@@ -263,7 +295,7 @@
            </row>
            <row>
              <entry>Repository documentation:</entry>
-              <entry><ulink url="https://wiki.postgresql.org/wiki/Apt)">https://wiki.postgresql.org/wiki/Apt)</ulink></entry>
+              <entry><ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</ulink></entry>
            </row>
          </tbody>
        </tgroup>
@@ -279,8 +311,8 @@
        version number for your installation.
      </para>
      <para>
-        See also <xref linkend="repmgrd-configuration-debian-ubuntu"> for some specifics related
-        to configuring the <application>repmgrd</application> daemon.
+        See also <xref linkend="repmgrd-configuration-debian-ubuntu"/> for some specifics related
+        to configuring the &repmgrd; daemon.
      </para>

      <table id="debian-9-packages">
@@ -291,7 +323,7 @@

            <row>
              <entry>Package name example:</entry>
-              <entry><filename>postgresql-10-repmgr</filename></entry>
+              <entry><filename>postgresql-11-repmgr</filename></entry>
            </row>

            <row>
@@ -301,12 +333,12 @@

            <row>
              <entry>Installation command:</entry>
-              <entry><literal>apt-get install postgresql-10-repmgr</literal></entry>
+              <entry><literal>apt-get install postgresql-11-repmgr</literal></entry>
            </row>

            <row>
              <entry>Binary location:</entry>
-              <entry><filename>/usr/lib/postgresql/10/bin</filename></entry>
+              <entry><filename>/usr/lib/postgresql/11/bin</filename></entry>
            </row>

            <row>
@@ -321,12 +353,12 @@

            <row>
              <entry>Data directory:</entry>
-              <entry><filename>/var/lib/postgresql/10/main</filename></entry>
+              <entry><filename>/var/lib/postgresql/11/main</filename></entry>
            </row>

            <row>
              <entry>PostgreSQL service command:</entry>
-              <entry><command>systemctl [start|stop|restart|reload] postgresql@10-main</command></entry>
+              <entry><command>systemctl [start|stop|restart|reload] postgresql@11-main</command></entry>

            </row>

@@ -354,7 +386,7 @@
          it's recommended to execute <command>pg_ctlcluster</command> (as <literal>root</literal>,
          either directly or via <command>sudo</command>), e.g.:
          <programlisting>
-            <command>pg_ctlcluster 10 main [start|stop|restart|reload]</command></programlisting>
+            <command>pg_ctlcluster 11 main [start|stop|restart|reload]</command></programlisting>
        </para>
        <para>
          For pre-<application>systemd</application> systems, <command>pg_ctlcluster</command>
@@ -365,6 +397,138 @@

  </sect1>

+  <sect1 id="packages-snapshot" xreflabel="Snapshot packages">
+    <title>Snapshot packages</title>
+    <indexterm>
+      <primary>snapshot packages</primary>
+    </indexterm>
+    <indexterm>
+      <primary>packages</primary>
+      <secondary>snaphots</secondary>
+    </indexterm>
+
+    <para>
+      For testing new features and bug fixes, from time to time 2ndQuadrant provides
+      so-called &quot;snapshot packages&quot; via its public repository. These packages
+      are built from the &repmgr; source at a particular point in time, and are not formal
+      releases.
+    </para>
+    <note>
+      <para>
+        We do not recommend installing these packages in a production environment
+        unless specifically advised.
+      </para>
+    </note>
+    <para>
+      To install a snapshot package, it's necessary to install the 2ndQuadrant public snapshot repository,
+      following the instructions here: <ulink url="https://dl.2ndquadrant.com/default/release/site/">https://dl.2ndquadrant.com/default/release/site/</ulink> but replace <literal>release</literal> with <literal>snapshot</literal>
+      in the appropriate URL.
+    </para>
+    <para>
+      For example, to install the snapshot RPM repository for PostgreSQL 9.6, execute (as <literal>root</literal>):
+      <programlisting>
+curl https://dl.2ndquadrant.com/default/snapshot/get/9.6/rpm | bash</programlisting>
+
+      or as a normal user with root sudo access:
+      <programlisting>
+curl https://dl.2ndquadrant.com/default/snapshot/get/9.6/rpm | sudo bash</programlisting>
+    </para>
+    <para>
+      Alternatively you can browse the repository here:
+      <ulink url="https://dl.2ndquadrant.com/default/snapshot/browse/">https://dl.2ndquadrant.com/default/snapshot/browse/</ulink>.
+    </para>
+    <para>
+      Once the repository is installed, installing or updating &repmgr; will result in the latest snapshot
+      package being installed.
+    </para>
+    <para>
+      The package name will be formatted like this:
+      <programlisting>
+repmgr96-4.1.1-0.0git320.g5113ab0.1.el7.x86_64.rpm</programlisting>
+      containg the snapshot build number (here: <literal>320</literal>) and the hash
+      of the <application>git</application> commit it was built from (here: <literal>g5113ab0</literal>).
+    </para>
+
+    <para>
+      Note that the next formal release (in the above example <literal>4.1.1</literal>), once available,
+      will install in place of any snapshot builds.
+    </para>
+
+  </sect1>
+
+  <sect1 id="packages-old-versions" xreflabel="Installing old package versions">
+    <title>Installing old package versions</title>
+
+    <indexterm>
+      <primary>old packages</primary>
+    </indexterm>
+
+    <indexterm>
+      <primary>packages</primary>
+      <secondary>old versions</secondary>
+    </indexterm>
+
+    <indexterm>
+      <primary>installation</primary>
+      <secondary>old package versions</secondary>
+    </indexterm>
+
+    <sect2 id="packages-old-versions-debian" xreflabel="old Debian package versions">
+      <title>Debian/Ubuntu</title>
+      <para>
+        An archive of old packages (<literal>3.3.2</literal> and later) for Debian/Ubuntu-based systems is available here:
+        <ulink url="http://atalia.postgresql.org/morgue/r/repmgr/">http://atalia.postgresql.org/morgue/r/repmgr/</ulink>
+      </para>
+    </sect2>
+
+    <sect2 id="packages-old-versions-rhel-centos" xreflabel="old RHEL/CentOS package versions">
+      <title>RHEL/CentOS</title>
+
+      <para>
+        Old versions can be located with e.g.:
+        <programlisting>
+          yum --showduplicates list repmgr96</programlisting>
+        (substitute the appropriate package name; see <xref linkend="packages-centos"/>) and installed with:
+        <programlisting>
+          yum install {package_name}-{version}</programlisting>
+        where <literal>{package_name}</literal> is the base package name (e.g. <literal>repmgr96</literal>)
+        and <literal>{version}</literal> is the version listed by the
+        <command> yum --showduplicates list ...</command> command, e.g. <literal>4.0.6-1.rhel6</literal>.
+      </para>
+      <para>For example:
+        <programlisting>
+          yum install repmgr96-4.0.6-1.rhel6</programlisting>
+      </para>
+
+      <sect3 id="packages-old-versions-rhel-centos-repmgr3">
+        <title>repmgr 3 packages</title>
+        <para>
+          Old &repmgr; 3 RPM packages (<literal>3.2</literal> and later) can be retrieved from the
+          (deprecated) 2ndQuadrant repository at
+          <ulink url="http://packages.2ndquadrant.com/repmgr/yum/">http://packages.2ndquadrant.com/repmgr/yum/</ulink>
+          by installing the appropriate repository RPM:
+        </para>
+
+        <itemizedlist spacing="compact" mark="bullet">
+
+          <listitem>
+            <simpara>
+              <ulink url="http://packages.2ndquadrant.com/repmgr/yum-repo-rpms/repmgr-fedora-1.0-1.noarch.rpm">http://packages.2ndquadrant.com/repmgr/yum-repo-rpms/repmgr-fedora-1.0-1.noarch.rpm</ulink>
+            </simpara>
+          </listitem>
+
+          <listitem>
+            <simpara>
+              <ulink url="http://packages.2ndquadrant.com/repmgr/yum-repo-rpms/repmgr-rhel-1.0-1.noarch.rpm">http://packages.2ndquadrant.com/repmgr/yum-repo-rpms/repmgr-rhel-1.0-1.noarch.rpm</ulink>
+            </simpara>
+          </listitem>
+
+        </itemizedlist>
+      </sect3>
+
+    </sect2>
+  </sect1>
+

  <sect1 id="packages-packager-info" xreflabel="Information for packagers">
    <title>Information for packagers</title>
@@ -373,7 +537,7 @@
      <secondary>information for packagers</secondary>
    </indexterm>
    <para>
-      We recommend patching the following  parameters when
+      We recommend patching the following parameters when
      building the package as built-in default values for user convenience.
      These values can nevertheless be overridden by the user, if desired.
    </para>
@@ -388,13 +552,13 @@
 		char		package_conf_file[MAXPGPATH] = "";</programlisting>
        </para>
        <para>
-          See also: <xref linkend="configuration-file">
+          See also: <xref linkend="configuration-file"/>
        </para>
      </listitem>

      <listitem>
        <para>
-          PID file location: the default <application>repmgrd</application> PID file
+          PID file location: the default &repmgrd; PID file
          location can be hard-coded by patching <varname>package_pid_file</varname>
          in <filename>repmgrd.c</filename>:
          <programlisting>
@@ -402,7 +566,7 @@
 		char		package_pid_file[MAXPGPATH] = "";</programlisting>
        </para>
        <para>
-          See also: <xref linkend="repmgrd-pid-file">
+          See also: <xref linkend="repmgrd-pid-file"/>
        </para>
      </listitem>

--- a/doc/appendix-release-notes.sgml
+++ b/doc/appendix-release-notes.sgml
--- a/doc/appendix-release-notes.xml
+++ b/doc/appendix-release-notes.xml
--- a/doc/appendix-signatures.sgml
+++ b/doc/appendix-signatures.sgml
@@ -5,14 +5,14 @@
   <title>repmgr source code signing key</title>
   <para>
     The signing key ID used for <application>repmgr</application> source code bundles is:
-     <ulink url="http://packages.2ndquadrant.com/repmgr/SOURCE-GPG-KEY-repmgr">
+     <ulink url="https://repmgr.org/download/SOURCE-GPG-KEY-repmgr">
       <literal>0x297F1DCC</literal></ulink>.
   </para>

   <para>
     To download the <application>repmgr</application> source key to your computer:
     <programlisting>
-       curl -s http://packages.2ndquadrant.com/repmgr/SOURCE-GPG-KEY-repmgr | gpg --import
+       curl -s https://repmgr.org/download/SOURCE-GPG-KEY-repmgr | gpg --import
       gpg --fingerprint 0x297F1DCC
     </programlisting>
     then verify that the fingerprint is the expected value:
--- a/doc/appendix-support.xml
+++ b/doc/appendix-support.xml
@@ -0,0 +1,99 @@
+<appendix id="appendix-support" xreflabel="repmgr support">
+
+  <title>&repmgr; support</title>
+
+  <indexterm>
+    <primary>support</primary>
+  </indexterm>
+
+  <para>
+    <ulink url="https://2ndquadrant.com/">2ndQuadrant</ulink> provides 24x7
+    production support for &repmgr; and other PostgreSQL
+    products, including configuration assistance, installation
+    verification and training for running a robust replication cluster.
+  </para>
+  <para>
+    For further details see: <ulink url="https://2ndquadrant.com/en/support/">https://2ndquadrant.com/en/support/</ulink>
+  </para>
+
+  <para>
+    A mailing list/forum is provided via Google groups to discuss contributions or issues: <ulink url="https://groups.google.com/group/repmgr">https://groups.google.com/group/repmgr</ulink>.
+  </para>
+  <para>
+    Please report bugs and other issues to: <ulink url="https://github.com/2ndQuadrant/repmgr">https://github.com/2ndQuadrant/repmgr</ulink>.
+  </para>
+
+  <important>
+    <para>
+      Please read the <link linkend="appendix-support-reporting-issues">following section</link> before submitting questions or issue reports.
+    </para>
+  </important>
+
+  <sect1 id="appendix-support-reporting-issues" xreflabel="Reportins Issues">
+    <title>Reporting Issues</title>
+
+    <indexterm>
+      <primary>support</primary>
+      <secondary>reporting issues</secondary>
+    </indexterm>
+
+
+    <para>
+      When asking questions or reporting issues, it is extremely helpful if the following information is included:
+
+    <itemizedlist spacing="compact" mark="bullet">
+
+     <listitem>
+      <simpara>
+        &repmgr; version
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+        How was &repmgr; installed? From source? From packages? If
+        so from which repository?
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+        <filename>repmpgr.conf</filename> files (suitably anonymized if necessary)
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+        Contents of the <literal>repmgr.nodes</literal> table (suitably anonymized if necessary)
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+        PostgreSQL version
+      </simpara>
+     </listitem>
+
+    </itemizedlist>
+    </para>
+    <para>
+      If issues are encountered with a &repmgr; client command, please provide
+      the output of that command executed with the options
+      <option>-LDEBUG --verbose</option>, which will ensure &repmgr; emits
+      the maximum level of logging output.
+    </para>
+    <para>
+      If issues are encountered with &repmgrd;,
+      please provide relevant extracts from the &repmgr; log files
+      and if possible the PostgreSQL log itself. Please ensure these
+      logs do not contain any confidential data.
+    </para>
+    <para>
+      In all cases it is <emphasis>extremely</emphasis> useful to receive
+      information on how to reliably reproduce an issue with as much detail as
+      possible.
+    </para>
+
+  </sect1>
+
+</appendix>
--- a/doc/bdr-failover.md
+++ b/doc/bdr-failover.md
@@ -4,5 +4,5 @@ BDR failover with repmgrd
 This document has been integrated into the main `repmgr` documentation
 and is now located here:

-> [BDR failover with repmgrd](https://repmgr.org/docs/4.0/repmgrd-bdr.html)
+> [BDR failover with repmgrd](https://repmgr.org/docs/current/repmgrd-bdr.html)

--- a/doc/changes-in-repmgr4.md
+++ b/doc/changes-in-repmgr4.md
@@ -4,4 +4,4 @@ Changes in repmgr 4
 This document has been integrated into the main `repmgr` documentation
 and is now located here:

-> [Release notes](https://repmgr.org/docs/4.0/release-4.0.html)
+> [Release notes](https://repmgr.org/docs/current/release-4.0.html)
--- a/doc/cloning-standbys.sgml
+++ b/doc/cloning-standbys.sgml
@@ -2,6 +2,8 @@
 <title>Cloning standbys</title>

 <sect1 id="cloning-from-barman" xreflabel="Cloning from Barman">
+   <title>Cloning a standby from Barman</title>
+
   <indexterm>
    <primary>cloning</primary>
    <secondary>from Barman</secondary>
@@ -11,9 +13,8 @@
    <secondary>cloning a standby</secondary>
   </indexterm>

-   <title>Cloning a standby from Barman</title>
   <para>
-    <xref linkend="repmgr-standby-clone"> can use
+    <xref linkend="repmgr-standby-clone"/> can use
    <ulink url="https://www.2ndquadrant.com/">2ndQuadrant</ulink>'s
    <ulink url="https://www.pgbarman.org/">Barman</ulink> application
    to clone a standby (and also as a fallback source for WAL files).
@@ -51,6 +52,24 @@
   </itemizedlist>
   </para>

+
+   <note>
+    <para>
+      Currently &repmgr;'s support for cloning from Barman is implemented by using
+      <productname>rsync</productname> to clone from the Barman server.
+    </para>
+    <para>
+      It is therefore not able to make use of Barman's parallel restore facility, which
+      is executed on the Barman server and clones to the target server.
+    </para>
+    <para>
+      Barman's parallel restore facility can be used by executing it manually on
+      the Barman server and integrating the resulting cloned standby using
+      <command><link linkend="repmgr-standby-clone">repmgr standby clone --recovery-conf-only</link></command>.
+    </para>
+   </note>
+
+
  <sect2 id="cloning-from-barman-prerequisites">
   <title>Prerequisites for cloning from Barman</title>
   <para>
@@ -59,8 +78,7 @@
   <itemizedlist spacing="compact" mark="bullet">
     <listitem>
      <para>
-        the <varname>barman_server</varname> setting in <filename>repmgr.conf</filename> is the same as the
-        server configured in Barman;
+        the Barman catalogue must include at least one valid backup for this server;
      </para>
     </listitem>
     <listitem>
@@ -71,19 +89,68 @@
     </listitem>
     <listitem>
      <para>
-        the <varname>restore_command</varname> setting in <filename>repmgr.conf</filename> is configured to
-        use a copy of the <command>barman-wal-restore</command> script shipped with the
-        <literal>barman-cli</literal> package (see section <xref linkend="cloning-from-barman-restore-command">
-        below).
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-        the Barman catalogue includes at least one valid backup for this  server.
+        the <varname>barman_server</varname> setting in <filename>repmgr.conf</filename> is the same as the
+        server configured in Barman.
      </para>
     </listitem>
+
   </itemizedlist>
   </para>
+
+   <para>
+     For example, assuming Barman is located on the host &quot;<literal>barmansrv</literal>&quot;
+     under the &quot;<literal>barman</literal>&quot; user account,
+     <filename>repmgr.conf</filename> should contain the following entries:
+    <programlisting>
+    barman_host='barman@barmansrv'
+    barman_server='somedb'</programlisting>
+   </para>
+
+   <note>
+    <para>
+     To use a non-default Barman configuration file on the Barman server,
+     specify this in <filename>repmgr.conf</filename> with <filename>barman_config</filename>:
+     <programlisting>
+      barman_config=/path/to/barman.conf</programlisting>
+    </para>
+   </note>
+
+
+   <para>
+     We also recommend configuring the <varname>restore_command</varname> setting in <filename>repmgr.conf</filename>
+     to use the <command>barman-wal-restore</command> script
+     (see section <xref linkend="cloning-from-barman-restore-command"/> below).
+   </para>
+
+
+   <tip>
+    <simpara>
+      If you have a non-default SSH configuration on the Barman
+      server, e.g. using a port other than 22, then you can set those
+      parameters in a dedicated Host section in <filename>~/.ssh/config</filename>
+      corresponding to the value of <varname>barman_host</varname> in
+      <filename>repmgr.conf</filename>. See the <literal>Host</literal>
+      section in <command>man 5 ssh_config</command> for more details.
+    </simpara>
+   </tip>
+   <para>
+    It's now possible to clone a standby from Barman, e.g.:
+    <programlisting>
+    $ repmgr -f /etc/repmgr.conf -h node1 -U repmgr -d repmgr standby clone
+    NOTICE: destination directory "/var/lib/postgresql/data" provided
+    INFO: connecting to Barman server to verify backup for "test_cluster"
+    INFO: checking and correcting permissions on existing directory "/var/lib/postgresql/data"
+    INFO: creating directory "/var/lib/postgresql/data/repmgr"...
+    INFO: connecting to Barman server to fetch server parameters
+    INFO: connecting to source node
+    DETAIL: current installation size is 30 MB
+    NOTICE: retrieving backup from Barman...
+    (...)
+    NOTICE: standby clone (from Barman) complete
+    NOTICE: you can now start your PostgreSQL server
+    HINT: for example: pg_ctl -D /var/lib/postgresql/data start</programlisting>
+   </para>
+
   <note>
    <simpara>
     Barman support is automatically enabled if <varname>barman_server</varname>
@@ -93,45 +160,16 @@
     command line option.
    </simpara>
   </note>
-   <tip>
-    <simpara>
-      If you have a non-default SSH configuration on the Barman
-      server, e.g. using a port other than 22, then you can set those
-      parameters in a dedicated Host section in <filename>~/.ssh/config</filename>
-      corresponding to the value of<varname>barman_host</varname> in
-      <filename>repmgr.conf</filename>. See the <literal>Host</literal>
-      section in <command>man 5 ssh_config</command> for more details.
-    </simpara>
-   </tip>
-   <para>
-    It's now possible to clone a standby from Barman, e.g.:
-    <programlisting>
-    NOTICE: using configuration file "/etc/repmgr.conf"
-    NOTICE: destination directory "/var/lib/postgresql/data" provided
-    INFO: connecting to Barman server to verify backup for test_cluster
-    INFO: checking and correcting permissions on existing directory "/var/lib/postgresql/data"
-    INFO: creating directory "/var/lib/postgresql/data/repmgr"...
-    INFO: connecting to Barman server to fetch server parameters
-    INFO: connecting to upstream node
-    INFO: connected to source node, checking its state
-    INFO: successfully connected to source node
-    DETAIL: current installation size is 29 MB
-    NOTICE: retrieving backup from Barman...
-    receiving file list ...
-    (...)
-    NOTICE: standby clone (from Barman) complete
-    NOTICE: you can now start your PostgreSQL server
-    HINT: for example: pg_ctl -D /var/lib/postgresql/data start</programlisting>

-   </para>
  </sect2>
  <sect2 id="cloning-from-barman-restore-command" xreflabel="Using Barman as a WAL file source">
-  <indexterm>
+   <title>Using Barman as a WAL file source</title>
+
+   <indexterm>
    <primary>Barman</primary>
    <secondary>fetching archived WAL</secondary>
   </indexterm>

-   <title>Using Barman as a WAL file source</title>
   <para>
    As a fallback in case streaming replication is interrupted, PostgreSQL can optionally
    retrieve WAL files from an archive, such as that provided by Barman. This is done by
@@ -140,39 +178,34 @@
   </para>
   <para>
     <command>barman-wal-restore</command> is a Python script provided as part of the <literal>barman-cli</literal>
-     package (Barman 2.0 and later; for Barman 1.x the script is provided separately as
-     <command>barman-wal-restore.py</command>) which performs this function for Barman.
+     package (Barman 2.0 ~ 2.7) or as part of the core Barman distribution (Barman 2.8 and later).
   </para>
   <para>
-    To use <command>barman-wal-restore</command> with &repmgr;
-    and assuming Barman is located on the <literal>barmansrv</literal> host
+    To use <command>barman-wal-restore</command> with &repmgr;,
+    assuming Barman is located on the host &quot;<literal>barmansrv</literal>&quot;
+    under the &quot;<literal>barman</literal>&quot; user account,
    and that <command>barman-wal-restore</command> is located as an executable at
    <filename>/usr/bin/barman-wal-restore</filename>,
    <filename>repmgr.conf</filename> should include the following lines:
    <programlisting>
-    barman_host=barmansrv
-    barman_server=somedb
-    restore_command=/usr/bin/barman-wal-restore barmansrv somedb %f %p</programlisting>
+    barman_host='barman@barmansrv'
+    barman_server='somedb'
+    restore_command='/usr/bin/barman-wal-restore barmansrv somedb %f %p'</programlisting>
   </para>
   <note>
    <simpara>
      <command>barman-wal-restore</command> supports command line switches to
-      control parallelism (<literal>--parallel=N</literal>) and compression (
-      <literal>--bzip2</literal>, <literal>--gzip</literal>).
+      control parallelism (<literal>--parallel=N</literal>) and compression
+      (<literal>--bzip2</literal>, <literal>--gzip</literal>).
    </simpara>
   </note>
-   <note>
-    <para>
-     To use a non-default Barman configuration file on the Barman server,
-     specify this in <filename>repmgr.conf</filename> with <filename>barman_config</filename>:
-     <programlisting>
-      barman_config=/path/to/barman.conf</programlisting>
-    </para>
-   </note>
+
  </sect2>
 </sect1>

-<sect1 id="cloning-replication-slots" xreflabel="Cloning and replication slots">
+ <sect1 id="cloning-replication-slots" xreflabel="Cloning and replication slots">
+   <title>Cloning and replication slots</title>
+
   <indexterm>
     <primary>cloning</primary>
     <secondary>replication slots</secondary>
@@ -182,7 +215,6 @@
     <primary>replication slots</primary>
     <secondary>cloning</secondary>
   </indexterm>
-   <title>Cloning and replication slots</title>
   <para>
    Replication slots were introduced with PostgreSQL 9.4 and are designed to ensure
    that any standby connected to the primary using a replication slot will always
@@ -243,26 +275,28 @@
    </simpara>
    <simpara>
     As an alternative we recommend using 2ndQuadrant's <ulink url="https://www.pgbarman.org/">Barman</ulink>,
-     which offloads WAL management to a separate server, negating the need to use replication
-     slots to reserve WAL. See section <xref linkend="cloning-from-barman">
+     which offloads WAL management to a separate server, removing the requirement to use a replication
+     slot for each individual standby to reserve WAL. See section <xref linkend="cloning-from-barman"/>
     for more details on using &repmgr; together with Barman.
    </simpara>
   </tip>
 </sect1>

 <sect1 id="cloning-cascading" xreflabel="Cloning and cascading replication">
+   <title>Cloning and cascading replication</title>
+
   <indexterm>
     <primary>cloning</primary>
     <secondary>cascading replication</secondary>
   </indexterm>
-   <title>Cloning and cascading replication</title>
+
   <para>
    Cascading replication, introduced with PostgreSQL 9.2, enables a standby server
    to replicate from another standby server rather than directly from the primary,
    meaning replication changes "cascade" down through a hierarchy of servers. This
    can be used to reduce load on the primary and minimize bandwith usage between
    sites. For more details, see the
-    <ulink url="https://www.postgresql.org/docs/current/static/warm-standby.html#CASCADING-REPLICATION">
+    <ulink url="https://www.postgresql.org/docs/current/warm-standby.html#CASCADING-REPLICATION">
    PostgreSQL cascading replication documentation</ulink>.
   </para>
   <para>
@@ -276,7 +310,7 @@
   </para>
   <para>
    To demonstrate cascading replication, first ensure you have a primary and standby
-    set up as shown in the <xref linkend="quickstart">.
+    set up as shown in the <xref linkend="quickstart"/>.
    Then create an additional standby server with <filename>repmgr.conf</filename> looking
    like this:
    <programlisting>
@@ -339,11 +373,11 @@
 </sect1>

 <sect1 id="cloning-advanced" xreflabel="Advanced cloning options">
+   <title>Advanced cloning options</title>
   <indexterm>
     <primary>cloning</primary>
     <secondary>advanced options</secondary>
   </indexterm>
-   <title>Advanced cloning options</title>

   <sect2 id="cloning-advanced-pg-basebackup-options" xreflabel="pg_basebackup options when cloning a standby">
    <title>pg_basebackup options when cloning a standby</title>
@@ -352,10 +386,12 @@
      provide additional parameters for <command>pg_basebackup</command> to customise the
      cloning process.
    </para>
+
    <para>
     By default, <command>pg_basebackup</command> performs a checkpoint before beginning the backup
     process. However, a normal checkpoint may take some time to complete;
-     a fast checkpoint can be forced with the <literal>-c/--fast-checkpoint</literal> option.
+     a fast checkpoint can be forced with <command><link linkend="repmgr-standby-clone">repmgr standby clone</link></command>'s
+     <literal>-c/--fast-checkpoint</literal> option.
     Note that this may impact performance of the server being cloned from (typically the primary)
     so should be used with care.
    </para>
@@ -363,13 +399,25 @@
      <simpara>
        If <application>Barman</application> is set up for the cluster, it's possible to
        clone the standby directly from Barman, without any impact on the server the standby
-        is being cloned from. For more details see <xref linkend="cloning-from-barman">.
+        is being cloned from. For more details see <xref linkend="cloning-from-barman"/>.
      </simpara>
    </tip>
    <para>
      Other options can be passed to <command>pg_basebackup</command> by including them
      in the <filename>repmgr.conf</filename> setting <varname>pg_basebackup_options</varname>.
    </para>
+
+    <para>
+      Not that by default, &repmgr; executes <command>pg_basebackup</command> with <option>-X/--wal-method</option>
+      (PostgreSQL 9.6 and earlier: <option>-X/--xlog-method</option>) set to <literal>stream</literal>.
+      From PostgreSQL 9.6, if replication slots are in use, it will also create a replication slot before
+      running the base backup, and execute <command>pg_basebackup</command> with the
+      <option>-S/--slot</option> option set to the name of the previously created replication slot.
+    </para>
+    <para>
+      These parameters can set by the user in <varname>pg_basebackup_options</varname>, in which case they
+      will override the &repmgr; default values. However normally there's no reason to do this.
+    </para>
    <para>
      If using a separate directory to store WAL files, provide the option <literal>--waldir</literal>
      (<literal>--xlogdir</literal> in PostgreSQL 9.6 and earlier) with the absolute path to the
@@ -377,7 +425,7 @@
      a symlink will automatically be created from the main data directory.
    </para>
    <para>
-     See the <ulink url="https://www.postgresql.org/docs/current/static/app-pgbasebackup.html">PostgreSQL pg_basebackup documentation</ulink>
+     See the <ulink url="https://www.postgresql.org/docs/current/app-pgbasebackup.html">PostgreSQL pg_basebackup documentation</ulink>
     for more details of available options.
    </para>
   </sect2>
@@ -399,7 +447,7 @@
     user's <filename>~/.pgpass</filename> file. It's also possible to store the password in the
     environment variable <varname>PGPASSWORD</varname>, however this is not recommended for
     security reasons. For more details see the
-     <ulink url="https://www.postgresql.org/docs/current/static/libpq-pgpass.html">PostgreSQL password file documentation</ulink>.
+     <ulink url="https://www.postgresql.org/docs/current/libpq-pgpass.html">PostgreSQL password file documentation</ulink>.
    </para>

    <note>
@@ -419,7 +467,7 @@
     (but not <filename>~/.pgpass</filename>) and place it into the <varname>primary_conninfo</varname>
     string in <filename>recovery.conf</filename>. Note that <varname>PGPASSWORD</varname>
     will need to be set during any action which causes <filename>recovery.conf</filename> to be
-     rewritten, e.g. <xref linkend="repmgr-standby-follow">.
+     rewritten, e.g. <xref linkend="repmgr-standby-follow"/>.
    </para>
    <para>
     It is of course also possible to include the password value in the <varname>conninfo</varname>
@@ -446,7 +494,7 @@
     replication connections and generating <filename>recovery.conf</filename>. This
     value will also be stored in the parameter <literal>repmgr.nodes</literal>
     table for each node; it no longer needs to be explicitly specified when
-     cloning a node or executing <xref linkend="repmgr-standby-follow">.
+     cloning a node or executing <xref linkend="repmgr-standby-follow"/>.
    </para>
   </sect2>
 </sect1>
--- a/doc/configuration-file-log-settings.sgml
+++ b/doc/configuration-file-log-settings.sgml
@@ -1,4 +1,6 @@
 <sect1 id="configuration-file-log-settings" xreflabel="log settings">
+  <title>Log settings</title>
+
  <indexterm>
    <primary>repmgr.conf</primary>
    <secondary>log settings</secondary>
@@ -7,10 +9,9 @@
    <primary>log settings</primary>
    <secondary>configuration in repmgr.conf</secondary>
  </indexterm>
-  <title>Log settings</title>

  <para>
-    By default, &repmgr; and <application>repmgrd</application> write log output to
+    By default, &repmgr; and &repmgrd; write log output to
    <literal>STDERR</literal>. An alternative log destination can be specified
    (either a file or <literal>syslog</literal>).
  </para>
@@ -24,7 +25,7 @@
    <para>
      This behaviour can be overriden with the command line option <option>--log-to-file</option>,
      which will redirect all logging output to the configured log destination. This is recommended
-      when &repmgr; is executed by another application, particularly <application>repmgrd</application>,
+      when &repmgr; is executed by another application, particularly &repmgrd;,
      to enable log output generated by the &repmgr; application to be stored for later reference.
    </para>
  </note>
@@ -32,12 +33,11 @@
  <variablelist>

   <varlistentry id="repmgr-conf-log-level" xreflabel="log_level">
-    <term><varname>log_level</varname> (<type>string</type>)
+    <term><varname>log_level</varname> (<type>string</type>)</term>
+    <listitem>
     <indexterm>
      <primary><varname>log_level</varname> configuration file parameter</primary>
     </indexterm>
-    </term>
-    <listitem>
     <para>
       One of <option>DEBUG</option>, <option>INFO</option>, <option>NOTICE</option>,
       <option>WARNING</option>, <option>ERROR</option>, <option>ALERT</option>, <option>CRIT</option>
@@ -76,11 +76,11 @@
    </term>
    <listitem>
     <para>
-       If <xref linkend="repmgr-conf-log-facility"> is set to <option>STDERR</option>, log output
+       If <xref linkend="repmgr-conf-log-facility"/> is set to <option>STDERR</option>, log output
       can be redirected to the specified file.
     </para>
     <para>
-       See <xref linkend="repmgrd-log-rotation"> for information on configuring log rotation.
+       See <xref linkend="repmgrd-log-rotation"/> for information on configuring log rotation.
     </para>
    </listitem>
   </varlistentry>
@@ -93,12 +93,12 @@
    </term>
    <listitem>
     <para>
-       This setting causes <application>repmgrd</application> to emit a status log
+       This setting causes &repmgrd; to emit a status log
       line at the specified interval (in seconds, default <literal>300</literal>)
-       describing <application>repmgrd</application>'s current state, e.g.:
+       describing &repmgrd;'s current state, e.g.:
     </para>
     <programlisting>
-      [2018-07-12 00:47:32] [INFO] monitoring connection to upstream node "node1" (node ID: 1)</programlisting>
+      [2018-07-12 00:47:32] [INFO] monitoring connection to upstream node "node1" (ID: 1)</programlisting>
    </listitem>
   </varlistentry>

--- a/doc/configuration-file-optional-settings.xml
+++ b/doc/configuration-file-optional-settings.xml
@@ -0,0 +1,124 @@
+<sect1 id="configuration-file-optional-settings" xreflabel="optional configuration file settings">
+
+  <title>Optional configuration file settings</title>
+
+  <indexterm>
+    <primary>repmgr.conf</primary>
+    <secondary>optional settings</secondary>
+  </indexterm>
+
+  <variablelist>
+
+
+    <varlistentry id="repmgr-conf-config-directory" xreflabel="config_directory">
+      <term><varname>config_directory</varname> (<type>string</type>)
+        <indexterm>
+          <primary><varname>config_directory</varname> configuration file parameter</primary>
+        </indexterm>
+      </term>
+      <listitem>
+        <para>
+          If PostgreSQL configuration files are located outside the data
+	  directory, specify the directory where the main
+	  <filename>postgresql.conf</filename> file is located.
+        </para>
+        <para>
+          This enables explicit provision of an external configuration file
+          directory, which if set will be passed to <command>pg_ctl</command> as the
+          <option>-D</option> parameter. Otherwise <command>pg_ctl</command> will
+          default to using the data directory, which will cause some operations
+          to fail if the configuration files are not present there.
+        </para>
+        <note>
+          <para>
+           This is implemented primarily for feature completeness and for
+           development/testing purposes. Users who have installed &repmgr; from
+           a package should <emphasis>not</emphasis> rely on  to stop/start/restart PostgreSQL,
+           instead they should set the appropriate <option>service_..._command</option>
+           for their operating system. For more details see
+           <xref linkend="configuration-file-service-commands"/>.
+          </para>
+        </note>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id="repmgr-conf-replication-user" xreflabel="replication_user">
+      <term><varname>replication_user</varname> (<type>string</type>)
+        <indexterm>
+          <primary><varname>replication_user</varname> configuration file parameter</primary>
+        </indexterm>
+      </term>
+      <listitem>
+        <para>
+          PostgreSQL user to make replication connections with.
+          If not set defaults, to the user defined in <xref linkend="repmgr-conf-conninfo"/>.
+        </para>
+      </listitem>
+    </varlistentry>
+
+
+
+    <varlistentry id="repmgr-conf-replication-type" xreflabel="replication_type">
+      <term><varname>replication_type</varname> (<type>string</type>)
+        <indexterm>
+          <primary><varname>replication_type</varname> configuration file parameter</primary>
+        </indexterm>
+      </term>
+      <listitem>
+        <para>
+          Must be one of <literal>physical</literal> (for standard streaming replication)
+          or <literal>bdr</literal>.
+        </para>
+        <note>
+          <para>
+	    Replication type <literal>bdr</literal> can only be used with BDR 2.x
+          </para>
+          <para>
+            BDR 3.x users should use <literal>physical</literal>.
+          </para>
+        </note>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id="repmgr-conf-location" xreflabel="location">
+      <term><varname>location</varname> (<type>string</type>)
+        <indexterm>
+          <primary><varname>location</varname> configuration file parameter</primary>
+        </indexterm>
+      </term>
+      <listitem>
+        <para>
+          An arbitrary string defining the location of the node; this
+	  is used during failover to check visibility of the
+	  current primary node.
+        </para>
+        <para>
+          For more details see <xref linkend="repmgrd-network-split"/>.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id="repmgr-conf-use-replication-slots" xreflabel="use_replication_slots">
+      <term><varname>use_replication_slots</varname> (<type>boolean</type>)
+        <indexterm>
+          <primary><varname>use_replication_slots</varname> configuration file parameter</primary>
+        </indexterm>
+      </term>
+      <listitem>
+        <para>
+          Whether to use physical replication slots.
+        </para>
+        <note>
+          <para>
+	    When using replication slots,
+	    <varname>max_replication_slots</varname> should be configured for
+	    at least the number of standbys which will connect
+	    to the primary.
+          </para>
+        </note>
+      </listitem>
+    </varlistentry>
+
+
+  </variablelist>
+</sect1>
--- a/doc/configuration-file-required-settings.sgml
+++ b/doc/configuration-file-required-settings.sgml
@@ -1,10 +1,12 @@
 <sect1 id="configuration-file-settings" xreflabel="required configuration file settings">
+
+ <title>Required configuration file settings</title>
+
  <indexterm>
    <primary>repmgr.conf</primary>
    <secondary>required settings</secondary>
  </indexterm>

- <title>Required configuration file settings</title>
 <para>
   Each <filename>repmgr.conf</filename> file must contain the following parameters:
 </para>
@@ -39,6 +41,10 @@
       called <varname>standby1</varname> (for example), things will be confusing
       to say the least.
     </para>
+     <para>
+       The string's maximum length is 63 characters and it should
+       contain only printable ASCII characters.
+     </para>
    </listitem>
   </varlistentry>

@@ -56,7 +62,7 @@
     </para>
     <para>
       For details on conninfo strings, see section <ulink
-       url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING">Connection Strings</>
+       url="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING">Connection Strings</ulink>
        in the PosgreSQL documentation.
     </para>
     <para>
@@ -64,19 +70,19 @@
        <varname>connect_timeout</varname> in the <varname>conninfo</varname>
        string to determine the length of time which elapses before a network
        connection attempt is abandoned; for details see <ulink
-        url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT">
-        the PostgreSQL documentation</>.
+        url="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT">
+        the PostgreSQL documentation</ulink>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="repmgr-conf-data-directory" xreflabel="data_directory">
-    <term><varname>data_directory</varname> (<type>string</type>)
-     <indexterm>
-      <primary><varname>data_directory</varname> configuration file parameter</primary>
-     </indexterm>
-    </term>
+    <term><varname>data_directory</varname> (<type>string</type>)</term>
    <listitem>
+      <indexterm>
+        <primary><varname>data_directory</varname> configuration file parameter</primary>
+      </indexterm>
+
     <para>
       The node's data directory. This is needed by repmgr
       when performing operations when the PostgreSQL instance
@@ -90,33 +96,6 @@
  </variablelist>
 </para>

-  <para>
-    For a full list of annotated configuration items, see the file
-    <ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</ulink>.
-  </para>
-  <para>
-    For <application>repmgrd</application>-specific settings, see <xref linkend="repmgrd-configuration">.
-  </para>

-  <note>
-    <para>
-    The following parameters in the configuration file can be overridden with
-    command line options:
-    <itemizedlist>
-     <listitem>
-       <simpara>
-         <literal>-L/--log-level</literal> overrides <literal>log_level</literal> in
-         <filename>repmgr.conf</filename>
-       </simpara>
-     </listitem>
-     <listitem>
-       <simpara>
-         <literal>-b/--pg_bindir</literal> overrides <literal>pg_bindir</literal> in
-         <filename>repmgr.conf</filename>
-       </simpara>
-     </listitem>
-    </itemizedlist>
-    </para>
-  </note>

 </sect1>
--- a/doc/configuration-file-service-commands.sgml
+++ b/doc/configuration-file-service-commands.sgml
@@ -1,4 +1,6 @@
 <sect1 id="configuration-file-service-commands" xreflabel="service command settings">
+  <title>Service command settings</title>
+
  <indexterm>
    <primary>repmgr.conf</primary>
    <secondary>service command settings</secondary>
@@ -7,25 +9,24 @@
    <primary>service command settings</primary>
    <secondary>configuration in repmgr.conf</secondary>
  </indexterm>
-  <title>Service command settings</title>

  <para>
-    In some circumstances, &repmgr; (and <application>repmgrd</application>) need to
+    In some circumstances, &repmgr; (and &repmgrd;) need to
    be able to stop, start or restart PostgreSQL. &repmgr; commands which need to do this
    include <link linkend="repmgr-standby-follow"><command>repmgr standby follow</command></link>,
    <link linkend="repmgr-standby-switchover"><command>repmgr standby switchover</command></link> and
    <link linkend="repmgr-node-rejoin"><command>repmgr node rejoin</command></link>.
  </para>
  <para>
-    By default, &repmgr; will use PostgreSQL's <command>pg_ctl</command> to control the PostgreSQL
+    By default, &repmgr; will use PostgreSQL's <command>pg_ctl</command> utility to control the PostgreSQL
    server. However this can lead to various problems, particularly when PostgreSQL has been
-    installed from packages, and expecially so if <application>systemd</application> is in use.
+    installed from packages, and especially so if <application>systemd</application> is in use.
  </para>


  <note>
    <para>
-      If using <application>systemd</application>, ensure you have <varname>RemoteIPC</varname> set to <literal>off</literal>.
+      If using <application>systemd</application>, ensure you have <varname>RemoveIPC</varname> set to <literal>off</literal>.
      See the <ulink url="https://wiki.postgresql.org/wiki/Systemd">systemd</ulink>
      entry in the <ulink url="https://wiki.postgresql.org/wiki/Main_Page">PostgreSQL wiki</ulink> for details.
    </para>
@@ -48,6 +49,13 @@
    service_reload_command</programlisting>
  </para>

+  <note>
+    <para>
+      &repmgr; will not apply <option>pg_bindir</option> when executing any of these commands;
+      these can be user-defined scripts so must always be specified with the full path.
+    </para>
+  </note>
+
  <note>
    <para>
      It's also possible to specify a <varname>service_promote_command</varname>.
@@ -61,18 +69,18 @@
    </para>
    <para>
      Do not confuse this with <varname>promote_command</varname>, which is used
-      by <application>repmgrd</application> to execute <xref linkend="repmgr-standby-promote">.
+      by &repmgrd; to execute <xref linkend="repmgr-standby-promote"/>.
    </para>
  </note>

  <para>
    To confirm which command &repmgr; will execute for each action, use
-    <command>repmgr node service --list --action=...</command>, e.g.:
+    <command><link linkend="repmgr-node-service">repmgr node service --list-actions --action=...</link></command>, e.g.:
    <programlisting>
-      repmgr -f /etc/repmgr.conf node service --list --action=stop
-      repmgr -f /etc/repmgr.conf node service --list --action=start
-      repmgr -f /etc/repmgr.conf node service --list --action=restart
-      repmgr -f /etc/repmgr.conf node service --list --action=reload</programlisting>
+      repmgr -f /etc/repmgr.conf node service --list-actions --action=stop
+      repmgr -f /etc/repmgr.conf node service --list-actions --action=start
+      repmgr -f /etc/repmgr.conf node service --list-actions --action=restart
+      repmgr -f /etc/repmgr.conf node service --list-actions --action=reload</programlisting>
  </para>

  <para>
@@ -92,7 +100,7 @@
      Defaults:postgres !requiretty
      postgres ALL = NOPASSWD: /usr/bin/systemctl stop postgresql-9.6, \
        /usr/bin/systemctl start postgresql-9.6, \
-        /usr/bin/systemctl restart postgresql-9.6 \
+        /usr/bin/systemctl restart postgresql-9.6, \
        /usr/bin/systemctl reload postgresql-9.6</programlisting>
  </para>

--- a/doc/configuration-file.sgml
+++ b/doc/configuration-file.sgml
@@ -1,69 +0,0 @@
-<sect1 id="configuration-file" xreflabel="configuration file location">
-  <indexterm>
-    <primary>repmgr.conf</primary>
-    <secondary>location</secondary>
-  </indexterm>
-
-  <indexterm>
-    <primary>configuration</primary>
-    <secondary>repmgr.conf location</secondary>
-  </indexterm>
-
-  <title>Configuration file location</title>
-  <para>
-    <application>repmgr</application> and <application>repmgrd</application>
-    use a common configuration file, by default called
-    <filename>repmgr.conf</filename> (although any name can be used if explicitly specified).
-    <filename>repmgr.conf</filename> must contain a number of required parameters, including
-    the database connection string for the local node and the location
-    of its data directory; other values will be inferred from defaults if
-    not explicitly supplied. See section <xref linkend="configuration-file-settings">
-    for more details.
-  </para>
-
-  <para>
-   The configuration file will be searched for in the following locations:
-   <itemizedlist spacing="compact" mark="bullet">
-    <listitem>
-     <para>a configuration file specified by the <literal>-f/--config-file</literal> command line option</para>
-    </listitem>
-    <listitem>
-     <para>
-      a location specified by the package maintainer (if <application>repmgr</application>
-      as installed from a package and the package maintainer has specified the configuration
-      file location)
-     </para>
-    </listitem>
-    <listitem>
-     <para><filename>repmgr.conf</filename> in the local directory</para>
-    </listitem>
-    <listitem>
-      <para><filename>/etc/repmgr.conf</filename></para>
-    </listitem>
-    <listitem>
-     <para>the directory reported by <application>pg_config --sysconfdir</application></para>
-    </listitem>
-   </itemizedlist>
-  </para>
-
-  <para>
-   Note that if a file is explicitly specified with <literal>-f/--config-file</literal>,
-   an error will be raised if it is not found or not readable, and no attempt will be made to
-   check default locations; this is to prevent <application>repmgr</application> unexpectedly
-   reading the wrong configuraton file.
-  </para>
-
-  <note>
-    <para>
-      If providing the configuration file location with <literal>-f/--config-file</literal>,
-      avoid using a relative path, particularly when executing <xref linkend="repmgr-primary-register">
-      and <xref linkend="repmgr-standby-register">, 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>
-</sect1>
--- a/doc/configuration-file.xml
+++ b/doc/configuration-file.xml
@@ -0,0 +1,207 @@
+<sect1 id="configuration-file" xreflabel="configuration file">
+
+  <title>Configuration file</title>
+
+  <indexterm>
+    <primary>repmgr.conf</primary>
+  </indexterm>
+
+  <indexterm>
+    <primary>configuration</primary>
+    <secondary>repmgr.conf</secondary>
+  </indexterm>
+
+  <para>
+    <application>repmgr</application> and &repmgrd;
+    use a common configuration file, by default called
+    <filename>repmgr.conf</filename> (although any name can be used if explicitly specified).
+    <filename>repmgr.conf</filename> must contain a number of required parameters, including
+    the database connection string for the local node and the location
+    of its data directory; other values will be inferred from defaults if
+    not explicitly supplied. See section <xref linkend="configuration-file-settings"/>
+    for more details.
+  </para>
+
+  <sect2 id="configuration-file-format" xreflabel="configuration file format">
+
+    <title>Configuration file format</title>
+
+    <indexterm>
+      <primary>repmgr.conf</primary>
+      <secondary>format</secondary>
+    </indexterm>
+
+
+
+    <para>
+      <filename>repmgr.conf</filename> is a plain text file with one parameter/value
+      combination per line.
+    </para>
+    <para>
+      Whitespace is insignificant (except within a quoted parameter value) and blank lines are ignored.
+      Hash marks (<literal>#</literal>) designate the remainder of the line as a comment.
+      Parameter values that are not simple identifiers or numbers should be single-quoted.
+    </para>
+    <para>
+      To embed a single quote in a parameter value, write either two quotes (preferred) or backslash-quote.
+    </para>
+
+    <para>
+      Example of a valid <filename>repmgr.conf</filename> file:
+      <programlisting>
+# repmgr.conf
+
+node_id=1
+node_name= node1
+conninfo ='host=node1 dbname=repmgr user=repmgr connect_timeout=2'
+data_directory = '/var/lib/pgsql/12/data'</programlisting>
+
+    </para>
+
+    <note>
+      <para>
+        Beginning with <link linkend="release-5.0">repmgr 5.0</link>, configuration
+        file parsing has been tightened up and now matches the way PostgreSQL
+        itself parses configuration files.
+      </para>
+      <para>
+        This means <filename>repmgr.conf</filename> files used with earlier &repmgr;
+        versions may need slight modification before they can be used with &repmgr; 5
+        and later.
+      </para>
+      <para>
+        The main change is that &repmgr; requires most string values to be
+        enclosed in single quotes. For example, this was previously valid:
+          <programlisting>
+conninfo=host=node1 user=repmgr dbname=repmgr connect_timeout=2</programlisting>
+          but must now be changed to:
+          <programlisting>
+conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'</programlisting>
+      </para>
+    </note>
+
+  </sect2>
+
+
+  <sect2 id="configuration-file-items" xreflabel="configuration file items">
+
+    <title>Configuration file items</title>
+    <para>
+      The following sections document some sections of the configuration file:
+       <itemizedlist>
+          <listitem>
+            <simpara>
+              <xref linkend="configuration-file-settings"/>
+            </simpara>
+          </listitem>
+
+          <listitem>
+            <simpara>
+              <xref linkend="configuration-file-optional-settings"/>
+            </simpara>
+          </listitem>
+
+          <listitem>
+            <simpara>
+              <xref linkend="configuration-file-log-settings"/>
+            </simpara>
+          </listitem>
+
+
+          <listitem>
+            <simpara>
+              <xref linkend="configuration-file-service-commands"/>
+            </simpara>
+          </listitem>
+
+       </itemizedlist>
+
+    </para>
+    <para>
+      For a full list of annotated configuration items, see the file
+      <ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</ulink>.
+    </para>
+    <para>
+      For &repmgrd;-specific settings, see <xref linkend="repmgrd-configuration"/>.
+    </para>
+
+    <note>
+      <para>
+        The following parameters in the configuration file can be overridden with
+        command line options:
+        <itemizedlist>
+          <listitem>
+            <simpara>
+              <literal>-L/--log-level</literal> overrides <literal>log_level</literal> in
+              <filename>repmgr.conf</filename>
+            </simpara>
+          </listitem>
+          <listitem>
+            <simpara>
+              <literal>-b/--pg_bindir</literal> overrides <literal>pg_bindir</literal> in
+              <filename>repmgr.conf</filename>
+            </simpara>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </note>
+
+  </sect2>
+
+  <sect2 id="configuration-file-location" xreflabel="configuration file location">
+  <title>Configuration file location</title>
+
+  <indexterm>
+    <primary>repmgr.conf</primary>
+    <secondary>location</secondary>
+  </indexterm>
+
+
+  <para>
+   The configuration file will be searched for in the following locations:
+   <itemizedlist spacing="compact" mark="bullet">
+    <listitem>
+     <para>a configuration file specified by the <literal>-f/--config-file</literal> command line option</para>
+    </listitem>
+    <listitem>
+     <para>
+      a location specified by the package maintainer (if <application>repmgr</application>
+      as installed from a package and the package maintainer has specified the configuration
+      file location)
+     </para>
+    </listitem>
+    <listitem>
+     <para><filename>repmgr.conf</filename> in the local directory</para>
+    </listitem>
+    <listitem>
+      <para><filename>/etc/repmgr.conf</filename></para>
+    </listitem>
+    <listitem>
+     <para>the directory reported by <application>pg_config --sysconfdir</application></para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   Note that if a file is explicitly specified with <literal>-f/--config-file</literal>,
+   an error will be raised if it is not found or not readable, and no attempt will be made to
+   check default locations; this is to prevent <application>repmgr</application> unexpectedly
+   reading the wrong configuration file.
+  </para>
+
+  <note>
+    <para>
+      If providing the configuration file location with <literal>-f/--config-file</literal>,
+      avoid using a relative path, particularly when executing <xref linkend="repmgr-primary-register"/>
+      and <xref linkend="repmgr-standby-register"/>, 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>
+
+   </sect2>
+ </sect1>
--- a/doc/configuration.sgml
+++ b/doc/configuration.sgml
@@ -1,26 +0,0 @@
-<chapter id="configuration" xreflabel="Configuration">
-  <title>repmgr configuration</title>
-
-  &configuration-file;
-  &configuration-file-required-settings;
-  &configuration-file-log-settings;
-  &configuration-file-service-commands;
-
-  <sect1 id="configuration-permissions" xreflabel="Database user permissions">
-    <indexterm>
-      <primary>configuration</primary>
-      <secondary>database user permissions</secondary>
-    </indexterm>
-
-    <title>repmgr database user permissions</title>
-    <para>
-      &repmgr; will create an extension database containing objects
-      for administering &repmgr; metadata. The user defined in the <varname>conninfo</varname>
-      setting must be able to access all objects. Additionally, superuser permissions
-      are required to install the &repmgr; extension. The easiest way to do this
-      is create the &repmgr; user as a superuser, however if this is not
-      desirable, the &repmgr; user can be created as a normal user and a
-      superuser specified with <literal>--superuser</literal> when registering a &repmgr; node.
-    </para>
-  </sect1>
-</chapter>
--- a/doc/configuration.xml
+++ b/doc/configuration.xml
@@ -0,0 +1,340 @@
+<chapter id="configuration" xreflabel="Configuration">
+  <title>repmgr configuration</title>
+
+  <sect1 id="configuration-prerequisites" xreflabel="Prerequisites for configuration">
+    <title>Prerequisites for configuration</title>
+
+    <indexterm>
+      <primary>configuration</primary>
+      <secondary>prerequisites</secondary>
+    </indexterm>
+
+    <indexterm>
+      <primary>configuration</primary>
+      <secondary>ssh</secondary>
+    </indexterm>
+
+    <para>
+     Following software must be installed on both servers:
+     <itemizedlist spacing="compact" mark="bullet">
+      <listitem>
+       <simpara><application>PostgreSQL</application></simpara>
+      </listitem>
+      <listitem>
+       <simpara>
+        <application>repmgr</application>
+       </simpara>
+      </listitem>
+     </itemizedlist>
+    </para>
+
+    <para>
+      At network level, connections between the PostgreSQL port (default: <literal>5432</literal>)
+      must be possible between all nodes.
+    </para>
+
+    <para>
+      Passwordless <command>SSH</command> connectivity between all servers in the replication cluster
+      is not required, but is necessary in the following cases:
+      <itemizedlist>
+        <listitem>
+          <simpara>if you need &repmgr; to copy configuration files from outside the PostgreSQL
+            data directory (as is the case with e.g. <link linkend="packages-debian-ubuntu">Debian packages</link>);
+            in this case <command>rsync</command> must also be installed on all servers.
+          </simpara>
+        </listitem>
+        <listitem>
+          <simpara>to perform <link linkend="performing-switchover">switchover operations</link></simpara>
+        </listitem>
+        <listitem>
+          <simpara>
+            when executing <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command>
+            and <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>
+          </simpara>
+        </listitem>
+      </itemizedlist>
+    </para>
+
+    <tip>
+      <simpara>
+        Consider setting <varname>ConnectTimeout</varname> to a low value in your SSH configuration.
+        This will make it faster to detect any SSH connection errors.
+      </simpara>
+    </tip>
+
+  <sect2 id="configuration-postgresql" xreflabel="PostgreSQL configuration">
+      <title>PostgreSQL configuration for &repmgr;</title>
+
+    <indexterm>
+      <primary>configuration</primary>
+      <secondary>PostgreSQL</secondary>
+    </indexterm>
+
+    <indexterm>
+      <primary>PostgreSQL configuration</primary>
+    </indexterm>
+
+    <para>
+      The following PostgreSQL configuration parameters may need to be changed in order
+      for &repmgr; (and replication itself) to function correctly.
+    </para>
+    <variablelist>
+
+
+      <varlistentry>
+
+        <term><option>hot_standby</option></term>
+        <listitem>
+
+          <indexterm>
+            <primary>hot_standby</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+          <para>
+            <option>hot_standby</option> must always be set to <literal>on</literal>, as &repmgr; needs
+            to be able to connect to each server it manages.
+          </para>
+          <para>
+            Note that <option>hot_standby</option> defaults to <literal>on</literal> from PostgreSQL 10
+            and later; in PostgreSQL 9.6 and earlier, the default was <literal>off</literal>.
+          </para>
+          <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</ulink>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
+        <term><option>wal_level</option></term>
+
+        <listitem>
+
+          <indexterm>
+            <primary>wal_level</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+          <para>
+            <option>wal_level</option> must be one of <option>replica</option> or <option>logical</option>
+            (PostgreSQL 9.5 and earlier: one of <option>hot_standby</option> or <option>logical</option>).
+          </para>
+          <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</ulink>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
+        <term><option>max_wal_senders</option></term>
+
+        <listitem>
+
+          <indexterm>
+            <primary>max_wal_senders</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+          <para>
+            <option>max_wal_senders</option> must be set to a value of <literal>2</literal> or greater.
+            In general you will need one WAL sender for each standby which will attach to the PostgreSQL
+            instance; additionally &repmgr; will require two free WAL senders in order to clone further
+            standbys.
+          </para>
+          <para>
+            <option>max_wal_senders</option> should be set to an appropriate value on all PostgreSQL
+            instances in the replication cluster which may potentially become a primary server or
+            (in cascading replication) the upstream server of a standby.
+          </para>
+         <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</ulink>.
+          </para>
+          <note>
+            <para>
+              From <productname>PostgreSQL 12</productname>, <option>max_wal_senders</option>
+              <emphasis>must</emphasis> be set to the same or a higher value as the primary node
+              (at the time the node was cloned), otherwise the standby will refuse
+              to start (unless <option>hot_standby</option> is set to <literal>off</literal>, which
+              will prevent the node from accepting queries).
+            </para>
+          </note>
+
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
+        <term><option>max_replication_slots</option></term>
+
+        <listitem>
+
+          <indexterm>
+            <primary>max_replication_slots</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+          <para>
+            If you are intending to use replication slots, <option>max_replication_slots</option>
+            must be set to a non-zero value.
+          </para>
+          <para>
+            <option>max_replication_slots</option> should be set to an appropriate value on all PostgreSQL
+            instances in the replication cluster which may potentially become a primary server or
+            (in cascading replication) the upstream server of a standby.
+          </para>
+          <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS">max_replication_slots</ulink>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+
+        <term><option>wal_log_hints</option></term>
+        <listitem>
+          <indexterm>
+            <primary>wal_log_hints</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+
+          <para>If you are intending to use <application>pg_rewind</application>,
+            and the cluster was not initialised using data checksums, you may want to consider enabling
+            <option>wal_log_hints</option>.
+          </para>
+          <para>
+            For more details see <xref linkend="repmgr-node-rejoin-pg-rewind"/>.
+          </para>
+          <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-WAL-LOG-HINTS">wal_log_hints</ulink>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
+        <term><option>archive_mode</option></term>
+
+        <listitem>
+
+          <indexterm>
+            <primary>archive_mode</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+          <para>
+            We suggest setting <option>archive_mode</option> to <literal>on</literal> (and
+            <option>archive_command</option> to <literal>/bin/true</literal>; see below)
+            even if you are currently not planning to use WAL file archiving.
+          </para>
+          <para>
+            This will make it simpler to set up WAL file archiving if it is ever required,
+            as changes to <option>archive_mode</option> require a full PostgreSQL server
+            restart, while <option>archive_command</option> changes can be applied via a normal
+            configuration reload.
+          </para>
+          <para>
+            However, &repmgr; itself does not require WAL file archiving.
+          </para>
+          <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</ulink>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
+        <term><option>archive_command</option></term>
+
+        <listitem>
+
+          <indexterm>
+            <primary>archive_command</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+          <para>
+            If you have set  <option>archive_mode</option> to <literal>on</literal> but are not currently planning
+            to use WAL file archiving, set <option>archive_command</option> to a command which does nothing but returns
+            <literal>true</literal>, such as <command>/bin/true</command>. See above for details.
+          </para>
+          <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</ulink>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+
+        <term><option>wal_keep_segments</option></term>
+
+        <listitem>
+
+          <indexterm>
+            <primary>wal_keep_segments</primary>
+            <secondary>PostgreSQL configuration</secondary>
+          </indexterm>
+
+          <para>
+            Normally there is no need to set <option>wal_keep_segments</option> (default: <literal>0</literal>), as it
+            is <emphasis>not</emphasis> a reliable way of ensuring that all required WAL segments are available to standbys.
+            Replication slots and/or an archiving solution such as Barman are recommended to ensure standbys have a reliable
+            source of WAL segments at all times.
+          </para>
+          <para>
+            The only reason ever to set  <option>wal_keep_segments</option> is you have
+            you have configured <option>pg_basebackup_options</option>
+            in <filename>repmgr.conf</filename> to include the setting <literal>--wal-method=fetch</literal>
+            (PostgreSQL 9.6 and earlier: <literal>--xlog-method=fetch</literal>)
+            <emphasis>and</emphasis> you have <emphasis>not</emphasis> set <option>restore_command</option>
+            in <filename>repmgr.conf</filename> to fetch WAL files from a reliable source such as Barman,
+            in which case you'll need to set <option>wal_keep_segments</option>
+            to a sufficiently high number to ensure that all WAL files required by the standby
+            are retained. However we do not recommend managing replication in this way.
+          </para>
+          <para>
+            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-KEEP-SEGMENTS">wal_keep_segments</ulink>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+    <para>
+      See also the <link linkend="quickstart-postgresql-configuration">PostgreSQL configuration</link> section in the
+      <link linkend="quickstart">Quick-start guide</link>.
+    </para>
+  </sect2>
+
+
+  </sect1>
+
+
+  &configuration-file;
+  &configuration-file-required-settings;
+  &configuration-file-optional-settings;
+  &configuration-file-log-settings;
+  &configuration-file-service-commands;
+
+  <sect1 id="configuration-permissions" xreflabel="Database user permissions">
+    <title>repmgr database user permissions</title>
+
+    <indexterm>
+      <primary>configuration</primary>
+      <secondary>database user permissions</secondary>
+    </indexterm>
+
+    <para>
+      &repmgr; will create an extension database containing objects
+      for administering &repmgr; metadata. The user defined in the <varname>conninfo</varname>
+      setting must be able to access all objects. Additionally, superuser permissions
+      are required to install the &repmgr; extension. The easiest way to do this
+      is create the &repmgr; user as a superuser, however if this is not
+      desirable, the &repmgr; user can be created as a normal user and a
+      superuser specified with <literal>--superuser</literal> when registering a &repmgr; node.
+    </para>
+  </sect1>
+</chapter>
--- a/doc/configuring-witness-server.sgml
+++ b/doc/configuring-witness-server.sgml
@@ -1,86 +0,0 @@
-<chapter id="using-witness-server">
- <indexterm>
-  <primary>witness server</primary>
-  <seealso>Using a witness server with repmgrd</seealso>
- </indexterm>
-
-
- <title>Using a witness server</title>
- <para>
-   A <xref linkend="witness-server"> is a normal PostgreSQL instance which
-   is not part of the streaming replication cluster; its purpose is, if a
-   failover situation occurs, to provide proof that the primary server
-   itself is unavailable.
- </para>
-
- <para>
-   A typical use case for a witness server is a two-node streaming replication
-   setup, where the primary and standby are in different locations (data centres).
-   By creating a witness server in the same location as the primary, if the primary
-   becomes unavailable  it's possible for the standby to decide whether it can
-   promote itself without risking a "split brain" scenario: if it can't see either the
-   witness or the primary server, it's likely there's a network-level interruption
-   and it should not promote itself. If it can seen the witness but not the primary,
-   this proves there is no network interruption and the primary itself is unavailable,
-   and it can therefore promote itself (and ideally take action to fence the
-   former primary).
- </para>
- <para>
-   For more complex replication scenarios,e.g. with multiple datacentres, it may
-   be preferable to use location-based failover, which ensures that only nodes
-   in the same location as the primary will ever be promotion candidates;
-   see <xref linkend="repmgrd-network-split"> for more details.
- </para>
-
- <note>
-   <simpara>
-     A witness server will only be useful if <application>repmgrd</application>
-     is in use.
-   </simpara>
- </note>
-
- <sect1 id="creating-witness-server">
-   <title>Creating a witness server</title>
- <para>
-   To create a witness server, set up a normal PostgreSQL instance on a server
-   in the same physical location as the cluster's primary server.
- </para>
- <para>
-   This instance should *not* be on the same physical host as the primary server,
-   as otherwise if the primary server fails due to hardware issues, the witness
-   server will be lost too.
- </para>
- <note>
-   <simpara>
-     &repmgr; 3.3 and earlier provided a <command>repmgr create witness</command>
-     command, which would automatically create a PostgreSQL instance. However
-     this often resulted in an unsatisfactory, hard-to-customise instance.
-   </simpara>
- </note>
- <para>
-   The witness server should be configured in the same way as a normal
-   &repmgr; node; see section <xref linkend="configuration">.
- </para>
- <para>
-   Register the witness server with <xref linkend="repmgr-witness-register">.
-   This will create the &repmgr; extension on the witness server, and make
-   a copy of the &repmgr; metadata.
- </para>
- <note>
-   <simpara>
-    As the witness server is not part of the replication cluster, further
-    changes to the &repmgr; metadata will be synchronised by
-    <application>repmgrd</application>.
-   </simpara>
- </note>
- <para>
-   Once the witness server has been configured, <application>repmgrd</application>
-   should be started; for more details see <xref linkend="repmgrd-witness-server">.
- </para>
-
- <para>
-  To unregister a witness server, use <xref linkend="repmgr-witness-unregister">.
- </para>
-
- </sect1>
-</chapter>
--- a/doc/event-notifications.sgml
+++ b/doc/event-notifications.sgml
@@ -1,12 +1,12 @@
 <chapter id="event-notifications" xreflabel="event notifications">
+ <title>Event Notifications</title>

 <indexterm>
   <primary>event notifications</primary>
 </indexterm>

- <title>Event Notifications</title>
 <para>
-  Each time &repmgr; or <application>repmgrd</application> perform a significant event, a record
+  Each time &repmgr; or &repmgrd; perform a significant event, a record
  of that event is written into the <literal>repmgr.events</literal> table together with
  a timestamp, an indication of failure or success, and further details
  if appropriate. This is useful for gaining an overview of events
@@ -27,7 +27,7 @@
    (3 rows)</programlisting>
 </para>
 <para>
-  Alternatively, use <xref linkend="repmgr-cluster-event"> to output a
+  Alternatively, use <xref linkend="repmgr-cluster-event"/> to output a
  formatted list of events.
 </para>
 <para>
@@ -88,11 +88,10 @@

 <para>
  The values provided for <literal>%t</literal> and <literal>%d</literal>
-  will probably contain spaces, so should be quoted in the provided command
+  may contain spaces, so should be quoted in the provided command
  configuration, e.g.:
  <programlisting>
-    event_notification_command='/path/to/some/script %n %e %s "%t" "%d"'
-  </programlisting>
+    event_notification_command='/path/to/some/script %n %e %s "%t" "%d"'</programlisting>
 </para>

 <para>
@@ -104,10 +103,10 @@
   <term><option>%p</option></term>
   <listitem>
    <para>
-     node ID of the current primary (<xref linkend="repmgr-standby-register"> and <xref linkend="repmgr-standby-follow">)
+     node ID of the current primary (<xref linkend="repmgr-standby-register"/> and <xref linkend="repmgr-standby-follow"/>)
    </para>
    <para>
-     node ID of the demoted primary (<xref linkend="repmgr-standby-switchover"> only)
+     node ID of the demoted primary (<xref linkend="repmgr-standby-switchover"/> only)
    </para>
   </listitem>
  </varlistentry>
@@ -116,7 +115,7 @@
   <listitem>
    <para>
     <literal>conninfo</literal> string of the primary node
-     (<xref linkend="repmgr-standby-register"> and <xref linkend="repmgr-standby-follow">)
+     (<xref linkend="repmgr-standby-register"/> and <xref linkend="repmgr-standby-follow"/>)
    </para>
    <para>
      <literal>conninfo</literal> string of the next available node
@@ -129,7 +128,7 @@
   <term><option>%a</option></term>
   <listitem>
    <para>
-     name of the current primary node (<xref linkend="repmgr-standby-register"> and <xref linkend="repmgr-standby-follow">)
+     name of the current primary node (<xref linkend="repmgr-standby-register"/> and <xref linkend="repmgr-standby-follow"/>)
    </para>
    <para>
     name of the next available node (<varname>bdr_failover</varname> and  <varname>bdr_recovery</varname>)
@@ -147,58 +146,79 @@
 <para>
  By default, all notification types will be passed to the designated script;
  the notification types can be filtered to explicitly named ones using the
-  <varname>event_notifications</varname> parameter:
+  <varname>event_notifications</varname> parameter, e.g.:
+    <programlisting>
+    event_notifications=primary_register,standby_register,witness_register</programlisting>
+
+ </para>
+
+ <para>
+   Events generated by the &repmgr; command:

  <itemizedlist spacing="compact" mark="bullet">

   <listitem>
-    <simpara><literal>primary_register</literal></simpara>
+     <simpara><literal><link linkend="repmgr-primary-register-events">cluster_created</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>primary_unregister</literal></simpara>
+     <simpara><literal><link linkend="repmgr-primary-register-events">primary_register</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_register</literal></simpara>
+     <simpara><literal><link linkend="repmgr-primary-unregister-events">primary_unregister</link></literal></simpara>
+   </listitem>
+
+   <listitem>
+    <simpara><literal><link linkend="repmgr-standby-clone-events">standby_clone</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_register_sync</literal></simpara>
+    <simpara><literal><link linkend="repmgr-standby-register-events">standby_register</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_unregister</literal></simpara>
+    <simpara><literal><link linkend="repmgr-standby-register-events">standby_register_sync</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_clone</literal></simpara>
+    <simpara><literal><link linkend="repmgr-standby-unregister-events">standby_unregister</link></literal></simpara>
+   </listitem>
+
+   <listitem>
+    <simpara><literal><link linkend="repmgr-standby-promote-events">standby_promote</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_promote</literal></simpara>
+    <simpara><literal><link linkend="repmgr-standby-follow-events">standby_follow</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_follow</literal></simpara>
+     <simpara><literal><link linkend="repmgr-standby-switchover-events">standby_switchover</link></literal></simpara>
+   </listitem>
+
+   <listitem>
+     <simpara><literal><link linkend="repmgr-witness-register-events">witness_register</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_disconnect_manual</literal></simpara>
+    <simpara><literal><link linkend="repmgr-witness-unregister-events">witness_unregister</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_failure</literal></simpara>
+    <simpara><literal><link linkend="repmgr-node-rejoin-events">node_rejoin</link></literal></simpara>
   </listitem>
   <listitem>
-    <simpara><literal>standby_recovery</literal></simpara>
-   </listitem>
-   <listitem>
-    <simpara><literal>witness_register</literal></simpara>
-   </listitem>
-   <listitem>
-    <simpara><literal>witness_unregister</literal></simpara>
-   </listitem>
-   <listitem>
-    <simpara><literal>node_rejoin</literal></simpara>
+    <simpara><literal><link linkend="repmgr-cluster-cleanup-events">cluster_cleanup</link></literal></simpara>
   </listitem>
+
+  </itemizedlist>
+ </para>
+
+ <para>
+   Events generated by &repmgrd; (streaming replication mode):
+
+   <itemizedlist spacing="compact" mark="bullet">
   <listitem>
    <simpara><literal>repmgrd_start</literal></simpara>
   </listitem>
   <listitem>
    <simpara><literal>repmgrd_shutdown</literal></simpara>
   </listitem>
+   <listitem>
+    <simpara><literal>repmgrd_reload</literal></simpara>
+   </listitem>
   <listitem>
    <simpara><literal>repmgrd_failover_promote</literal></simpara>
   </listitem>
@@ -208,15 +228,54 @@
   <listitem>
    <simpara><literal>repmgrd_failover_aborted</literal></simpara>
   </listitem>
+   <listitem>
+    <simpara><literal>repmgrd_standby_reconnect</literal></simpara>
+   </listitem>
+   <listitem>
+    <simpara><literal>repmgrd_promote_error</literal></simpara>
+   </listitem>
+   <listitem>
+    <simpara><literal>repmgrd_local_disconnect</literal></simpara>
+   </listitem>
+   <listitem>
+    <simpara><literal>repmgrd_local_reconnect</literal></simpara>
+   </listitem>
   <listitem>
    <simpara><literal>repmgrd_upstream_disconnect</literal></simpara>
   </listitem>
   <listitem>
    <simpara><literal>repmgrd_upstream_reconnect</literal></simpara>
   </listitem>
+
   <listitem>
-    <simpara><literal>repmgrd_promote_error</literal></simpara>
+    <simpara><literal>standby_disconnect_manual</literal></simpara>
   </listitem>
+   <listitem>
+    <simpara><literal>standby_failure</literal></simpara>
+   </listitem>
+   <listitem>
+    <simpara><literal>standby_recovery</literal></simpara>
+   </listitem>
+
+   <listitem>
+     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_node_disconnect</link></literal></simpara>
+   </listitem>
+   <listitem>
+     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_node_reconnect</link></literal></simpara>
+   </listitem>
+   <listitem>
+     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_node_new_connect</link></literal></simpara>
+   </listitem>
+   <listitem>
+     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_nodes_disconnect_command</link></literal></simpara>
+   </listitem>
+
+   </itemizedlist>
+ </para>
+
+  <para>
+   Events generated by &repmgrd; (BDR mode):
+   <itemizedlist spacing="compact" mark="bullet">
   <listitem>
    <simpara><literal>bdr_failover</literal></simpara>
   </listitem>
--- a/doc/filelist.sgml
+++ b/doc/filelist.sgml
@@ -1,88 +0,0 @@
-<!-- doc/filelist.sgml -->
-
-<!ENTITY legal      SYSTEM "legal.sgml">
-
-<!ENTITY bookindex  SYSTEM "bookindex.sgml">
-
-<!--
- Some parts of the documentation are also source for some plain-text
- files used during installation.  To selectively ignore or include
- some parts (e.g., external xref's) when generating these files we use
- these parameter entities.  See also standalone-install.sgml.
- -->
-<!ENTITY % standalone-ignore  "INCLUDE">
-<!ENTITY % standalone-include "IGNORE">
-
-<!-- doc/filelist.sgml -->
-
-<!--
- By default, no index is included.  Use -i include-index on the command line
- to include it.
- -->
-<!ENTITY % include-index "IGNORE">
-
-<!--
- Create empty index element for processing by XSLT stylesheet.
- -->
-<!ENTITY % include-xslt-index "IGNORE">
-
-<!--
- Include external documentation sections
- -->
-
-<!ENTITY overview      SYSTEM "overview.sgml">
-<!ENTITY install SYSTEM "install.sgml">
-<!ENTITY install-requirements      SYSTEM "install-requirements.sgml">
-<!ENTITY install-packages      SYSTEM "install-packages.sgml">
-<!ENTITY install-source      SYSTEM "install-source.sgml">
-<!ENTITY quickstart      SYSTEM "quickstart.sgml">
-<!ENTITY configuration      SYSTEM "configuration.sgml">
-<!ENTITY configuration-file      SYSTEM "configuration-file.sgml">
-<!ENTITY configuration-file-required-settings      SYSTEM "configuration-file-required-settings.sgml">
-<!ENTITY configuration-file-log-settings      SYSTEM "configuration-file-log-settings.sgml">
-<!ENTITY configuration-file-service-commands   SYSTEM "configuration-file-service-commands.sgml">
-<!ENTITY cloning-standbys  SYSTEM "cloning-standbys.sgml">
-<!ENTITY promoting-standby  SYSTEM "promoting-standby.sgml">
-<!ENTITY follow-new-primary  SYSTEM "follow-new-primary.sgml">
-<!ENTITY switchover  SYSTEM "switchover.sgml">
-<!ENTITY configuring-witness-server SYSTEM "configuring-witness-server.sgml">
-
-<!ENTITY event-notifications  SYSTEM "event-notifications.sgml">
-<!ENTITY upgrading-repmgr  SYSTEM "upgrading-repmgr.sgml">
-
-<!ENTITY repmgrd-automatic-failover SYSTEM "repmgrd-automatic-failover.sgml">
-<!ENTITY repmgrd-configuration SYSTEM "repmgrd-configuration.sgml">
-<!ENTITY repmgrd-demonstration SYSTEM "repmgrd-demonstration.sgml">
-<!ENTITY repmgrd-monitoring SYSTEM "repmgrd-monitoring.sgml">
-<!ENTITY repmgrd-degraded-monitoring SYSTEM "repmgrd-degraded-monitoring.sgml">
-<!ENTITY repmgrd-cascading-replication SYSTEM "repmgrd-cascading-replication.sgml">
-<!ENTITY repmgrd-network-split SYSTEM "repmgrd-network-split.sgml">
-<!ENTITY repmgrd-witness-server SYSTEM "repmgrd-witness-server.sgml">
-<!ENTITY repmgrd-bdr SYSTEM "repmgrd-bdr.sgml">
-
-<!ENTITY repmgr-primary-register SYSTEM "repmgr-primary-register.sgml">
-<!ENTITY repmgr-primary-unregister SYSTEM "repmgr-primary-unregister.sgml">
-<!ENTITY repmgr-standby-clone SYSTEM "repmgr-standby-clone.sgml">
-<!ENTITY repmgr-standby-register SYSTEM "repmgr-standby-register.sgml">
-<!ENTITY repmgr-standby-unregister SYSTEM "repmgr-standby-unregister.sgml">
-<!ENTITY repmgr-standby-promote SYSTEM "repmgr-standby-promote.sgml">
-<!ENTITY repmgr-standby-follow SYSTEM "repmgr-standby-follow.sgml">
-<!ENTITY repmgr-standby-switchover SYSTEM "repmgr-standby-switchover.sgml">
-<!ENTITY repmgr-witness-register SYSTEM "repmgr-witness-register.sgml">
-<!ENTITY repmgr-witness-unregister SYSTEM "repmgr-witness-unregister.sgml">
-<!ENTITY repmgr-node-status SYSTEM "repmgr-node-status.sgml">
-<!ENTITY repmgr-node-check SYSTEM "repmgr-node-check.sgml">
-<!ENTITY repmgr-node-rejoin SYSTEM "repmgr-node-rejoin.sgml">
-<!ENTITY repmgr-cluster-show SYSTEM "repmgr-cluster-show.sgml">
-<!ENTITY repmgr-cluster-matrix SYSTEM "repmgr-cluster-matrix.sgml">
-<!ENTITY repmgr-cluster-crosscheck SYSTEM "repmgr-cluster-crosscheck.sgml">
-<!ENTITY repmgr-cluster-event SYSTEM "repmgr-cluster-event.sgml">
-<!ENTITY repmgr-cluster-cleanup SYSTEM "repmgr-cluster-cleanup.sgml">
-
-<!ENTITY appendix-release-notes  SYSTEM "appendix-release-notes.sgml">
-<!ENTITY appendix-faq      SYSTEM "appendix-faq.sgml">
-<!ENTITY appendix-signatures      SYSTEM "appendix-signatures.sgml">
-<!ENTITY appendix-packages      SYSTEM "appendix-packages.sgml">
-
-<!ENTITY bookindex  SYSTEM "bookindex.sgml">
-
--- a/doc/filelist.xml
+++ b/doc/filelist.xml
@@ -0,0 +1,70 @@
+<!-- doc/filelist.xml -->
+
+<!ENTITY legal      SYSTEM "legal.xml">
+
+<!ENTITY bookindex  SYSTEM "bookindex.xml">
+
+
+<!--
+ Include external documentation sections
+ -->
+
+<!ENTITY overview      SYSTEM "overview.xml">
+<!ENTITY install SYSTEM "install.xml">
+<!ENTITY install-requirements      SYSTEM "install-requirements.xml">
+<!ENTITY install-packages      SYSTEM "install-packages.xml">
+<!ENTITY install-source      SYSTEM "install-source.xml">
+<!ENTITY quickstart      SYSTEM "quickstart.xml">
+<!ENTITY configuration      SYSTEM "configuration.xml">
+<!ENTITY configuration-file      SYSTEM "configuration-file.xml">
+<!ENTITY configuration-file-required-settings      SYSTEM "configuration-file-required-settings.xml">
+<!ENTITY configuration-file-optional-settings      SYSTEM "configuration-file-optional-settings.xml">
+<!ENTITY configuration-file-log-settings      SYSTEM "configuration-file-log-settings.xml">
+<!ENTITY configuration-file-service-commands   SYSTEM "configuration-file-service-commands.xml">
+<!ENTITY cloning-standbys  SYSTEM "cloning-standbys.xml">
+<!ENTITY promoting-standby  SYSTEM "promoting-standby.xml">
+<!ENTITY follow-new-primary  SYSTEM "follow-new-primary.xml">
+<!ENTITY switchover  SYSTEM "switchover.xml">
+
+<!ENTITY event-notifications  SYSTEM "event-notifications.xml">
+<!ENTITY upgrading-repmgr  SYSTEM "upgrading-repmgr.xml">
+
+<!ENTITY repmgrd-overview SYSTEM "repmgrd-overview.xml">
+<!ENTITY repmgrd-automatic-failover SYSTEM "repmgrd-automatic-failover.xml">
+<!ENTITY repmgrd-configuration SYSTEM "repmgrd-configuration.xml">
+<!ENTITY repmgrd-operation SYSTEM "repmgrd-operation.xml">
+<!ENTITY repmgrd-bdr SYSTEM "repmgrd-bdr.xml">
+
+<!ENTITY repmgr-primary-register SYSTEM "repmgr-primary-register.xml">
+<!ENTITY repmgr-primary-unregister SYSTEM "repmgr-primary-unregister.xml">
+<!ENTITY repmgr-standby-clone SYSTEM "repmgr-standby-clone.xml">
+<!ENTITY repmgr-standby-register SYSTEM "repmgr-standby-register.xml">
+<!ENTITY repmgr-standby-unregister SYSTEM "repmgr-standby-unregister.xml">
+<!ENTITY repmgr-standby-promote SYSTEM "repmgr-standby-promote.xml">
+<!ENTITY repmgr-standby-follow SYSTEM "repmgr-standby-follow.xml">
+<!ENTITY repmgr-standby-switchover SYSTEM "repmgr-standby-switchover.xml">
+<!ENTITY repmgr-witness-register SYSTEM "repmgr-witness-register.xml">
+<!ENTITY repmgr-witness-unregister SYSTEM "repmgr-witness-unregister.xml">
+<!ENTITY repmgr-node-status SYSTEM "repmgr-node-status.xml">
+<!ENTITY repmgr-node-check SYSTEM "repmgr-node-check.xml">
+<!ENTITY repmgr-node-rejoin SYSTEM "repmgr-node-rejoin.xml">
+<!ENTITY repmgr-node-service SYSTEM "repmgr-node-service.xml">
+<!ENTITY repmgr-cluster-show SYSTEM "repmgr-cluster-show.xml">
+<!ENTITY repmgr-cluster-matrix SYSTEM "repmgr-cluster-matrix.xml">
+<!ENTITY repmgr-cluster-crosscheck SYSTEM "repmgr-cluster-crosscheck.xml">
+<!ENTITY repmgr-cluster-event SYSTEM "repmgr-cluster-event.xml">
+<!ENTITY repmgr-cluster-cleanup SYSTEM "repmgr-cluster-cleanup.xml">
+<!ENTITY repmgr-service-status SYSTEM "repmgr-service-status.xml">
+<!ENTITY repmgr-service-pause SYSTEM "repmgr-service-pause.xml">
+<!ENTITY repmgr-service-unpause SYSTEM "repmgr-service-unpause.xml">
+<!ENTITY repmgr-daemon-start SYSTEM "repmgr-daemon-start.xml">
+<!ENTITY repmgr-daemon-stop SYSTEM "repmgr-daemon-stop.xml">
+
+<!ENTITY appendix-release-notes  SYSTEM "appendix-release-notes.xml">
+<!ENTITY appendix-faq      SYSTEM "appendix-faq.xml">
+<!ENTITY appendix-signatures      SYSTEM "appendix-signatures.xml">
+<!ENTITY appendix-packages      SYSTEM "appendix-packages.xml">
+<!ENTITY appendix-support SYSTEM "appendix-support.xml">
+
+<!ENTITY bookindex  SYSTEM "bookindex.xml">
+
--- a/doc/follow-new-primary.sgml
+++ b/doc/follow-new-primary.sgml
@@ -1,21 +1,22 @@
 <chapter id="follow-new-primary">
+ <title>Following a new primary</title>
+
 <indexterm>
  <primary>Following a new primary</primary>
  <seealso>repmgr standby follow</seealso>
 </indexterm>

- <title>Following a new primary</title>
 <para>
   Following the failure or removal of the replication cluster's existing primary
-   server, <xref linkend="repmgr-standby-follow"> can be used to make 'orphaned' standbys
+   server, <xref linkend="repmgr-standby-follow"/> can be used to make &quot;orphaned&quot; standbys
   follow the new primary and catch up to its current state.
 </para>
 <para>
  To demonstrate this, assuming a replication cluster in the same state as the
-  end of the preceding section (<xref linkend="promoting-standby">),
+  end of the preceding section (<xref linkend="promoting-standby"/>),
  execute this:
  <programlisting>
-    $ repmgr -f /etc/repmgr.conf repmgr standby follow
+    $ repmgr -f /etc/repmgr.conf standby follow
    INFO: changing node 3's primary to node 2
    NOTICE: restarting server using "pg_ctl -l /var/log/postgresql/startup.log -w -D '/var/lib/postgresql/data' restart"
    waiting for server to shut down......... done
--- a/doc/install-packages.sgml
+++ b/doc/install-packages.sgml
@@ -1,249 +0,0 @@
-<sect1 id="installation-packages" xreflabel="Installing from packages">
- <title>Installing &repmgr; from packages</title>
- <para>
-  We recommend installing &repmgr; using the available packages for your
-  system.
- </para>
-
- <sect2 id="installation-packages-redhat" xreflabel="Installing from packages on RHEL, CentOS and Fedora">
-
-  <indexterm>
-   <primary>installation</primary>
-   <secondary>on Red Hat/CentOS/Fedora etc.</secondary>
-  </indexterm>
-
-  <title>RedHat/CentOS/Fedora</title>
-  <para>
-	&repmgr; RPM packages for RedHat/CentOS variants and Fedora are available from the
-	<ulink url="https://2ndquadrant.com">2ndQuadrant</ulink>
-	<ulink url="https://rpm.2ndquadrant.com/">public RPM repository</ulink>; see following
-	section for details.
-  </para>
-  <para>
-   RPM packages for &repmgr; are also available via Yum through
-   the PostgreSQL Global Development Group RPM repository
-   (<ulink url="https://yum.postgresql.org/">http://yum.postgresql.org/</ulink>).
-   Follow the instructions for your distribution (RedHat, CentOS,
-   Fedora, etc.) and architecture as detailed there. Note that it can take some days
-   for new &repmgr; packages to become available via the this repository.
-  </para>
-  <note>
-    <para>
-      &repmgr; packages are designed to be compatible with the community-provided PostgreSQL packages.
-      They may not work with vendor-specific packages such as those provided by RedHat for RHEL
-      customers, as the filesystem layout may be different to the community RPMs.
-      Please contact your support vendor for assistance.
-    </para>
-  </note>
-
-  <para>
-    For more information on the package contents, including details of installation
-    paths and relevant <link linkend="configuration-file-service-commands">service commands</link>,
-    see the appendix section <xref linkend="packages-centos">.
-  </para>
-
-
-  <sect3 id="installation-packages-redhat-2ndq">
-    <title>2ndQuadrant public RPM yum repository</title>
-
-	<note>
-	  <para>
-		<ulink url="https://2ndquadrant.com">2ndQuadrant</ulink> previously provided a dedicated
-        &repmgr; repository at
-        <ulink url="http://packages.2ndquadrant.com/repmgr/">http://packages.2ndquadrant.com/repmgr/</ulink>.
-		This repository will be deprecated in a future release as it is now replaced by
-		the <ulink url="https://rpm.2ndquadrant.com/">public RPM repository</ulink>
-		documented below.
-	  </para>
-	</note>
-
-    <para>
-      Beginning with <ulink url="https://repmgr.org/docs/4.0/release-4.0.5.html">repmgr 4.0.5</ulink>,
-      <ulink url="https://2ndquadrant.com/">2ndQuadrant</ulink> provides a dedicated <literal>yum</literal>
-	  <ulink url="https://rpm.2ndquadrant.com/">public RPM repository</ulink> for 2ndQuadrant software,
-	  including &repmgr;. We recommend using this for all future &repmgr; releases.
-	</para>
-	<para>
-	  General instructions for using this repository can be found on its
-	  <ulink url="https://rpm.2ndquadrant.com/">homepage</ulink>. Specific instructions
-	  for installing &repmgr; follow below.
-	</para>
-    <para>
-      <emphasis>Installation</emphasis>
-
-      <itemizedlist>
-		<listitem>
-		  <para>
-			Locate the repository RPM for your PostgreSQL version from the list at:
-			<ulink url="https://rpm.2ndquadrant.com/">https://rpm.2ndquadrant.com/</ulink>
-		  </para>
-		</listitem>
-
-        <listitem>
-          <para>
-            Install the repository RPM for your distribution and PostgreSQL version
-			(this enables the 2ndQuadrant repository as a source of &repmgr; packages).
-		  </para>
-		  <para>
-			For example, for PostgreSQL 10 on CentOS, execute:
-			<programlisting>
-sudo yum install https://rpm.2ndquadrant.com/site/content/2ndquadrant-repo-10-1-1.el7.noarch.rpm
-			</programlisting>
-		  </para>
-		  <para>
-			Verify that the repository is installed with:
-			<programlisting>
-sudo yum repolist</programlisting>
-			The output should contain two entries like this:
-			<programlisting>
-2ndquadrant-repo-10/7/x86_64         2ndQuadrant packages for PG10 for rhel 7 - x86_64           1
-2ndquadrant-repo-10-debug/7/x86_64   2ndQuadrant packages for PG10 for rhel 7 - x86_64 - Debug   1</programlisting>
-		  </para>
-		</listitem>
-
-        <listitem>
-          <para>
-            Install the &repmgr version appropriate for your PostgreSQL version (e.g. <literal>repmgr10</literal>):
-            <programlisting>
-$ yum install repmgr10</programlisting>
-          </para>
-        </listitem>
-      </itemizedlist>
-    </para>
-
-    <para>
-      <emphasis>Compatibility with PGDG Repositories</emphasis>
-    </para>
-    <para>
-      The 2ndQuadrant &repmgr; yum repository packages use the same definitions and file system layout as the
-      main PGDG repository.
-    </para>
-    <para>
-      Normally <application>yum</application> will prioritize the repository with the most recent &repmgr; version.
-      Once the PGDG repository has been updated, it doesn't matter which repository
-      the packages are installed from.
-    </para>
-    <para>
-      To ensure the 2ndQuadrant repository is always prioritised, install <literal>yum-plugin-priorities</literal>
-      and set the repository priorities accordingly.
-    </para>
-
-    <para>
-      <emphasis>Installing a specific package version</emphasis>
-    </para>
-    <para>
-      To install a specific package version, execute <command>yum --showduplicates list</command>
-      for the package in question:
-      <programlisting>
-        [root@localhost ~]# yum --showduplicates list repmgr10
-        Loaded plugins: fastestmirror
-        Loading mirror speeds from cached hostfile
-         * base: ftp.iij.ad.jp
-         * extras: ftp.iij.ad.jp
-         * updates: ftp.iij.ad.jp
-        Available Packages
-		repmgr10.x86_64                       4.0.3-1.rhel7                        pgdg10
-		repmgr10.x86_64                       4.0.4-1.rhel7                        pgdg10
-		repmgr10.x86_64                       4.0.5-1.el7                          2ndquadrant-repo-10</programlisting>
-      then append the appropriate version number to the package name with a hyphen, e.g.:
-      <programlisting>
-        [root@localhost ~]# yum install repmgr10-4.0.3-1.rhel7</programlisting>
-    </para>
-  </sect3>
- </sect2>
-
- <sect2 id="installation-packages-debian" xreflabel="Installing from packages on Debian or Ubuntu">
-
-  <indexterm>
-   <primary>installation</primary>
-   <secondary>on Debian/Ubuntu etc.</secondary>
-  </indexterm>
-
-  <title>Debian/Ubuntu</title>
-  <para>.deb packages for &repmgr; are available from the
-  PostgreSQL Community APT repository (<ulink url="http://apt.postgresql.org/">http://apt.postgresql.org/</ulink>).
-  Instructions can be found in the APT section of the PostgreSQL Wiki
-  (<ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</ulink>).
-  </para>
-  <para>
-    For more information on the package contents, including details of installation
-    paths and relevant <link linkend="configuration-file-service-commands">service commands</link>,
-    see the appendix section <xref linkend="packages-debian-ubuntu">.
-  </para>
-
-  <sect3 id="installation-packages-debian-ubuntu-2ndq">
-    <title>2ndQuadrant public apt repository for Debian/Ubuntu</title>
-
-    <para>
-      Beginning with <ulink url="https://repmgr.org/docs/4.0/release-4.0.5.html">repmgr 4.0.5</ulink>,
-      <ulink url="https://2ndquadrant.com/">2ndQuadrant</ulink> provides a
-	  <ulink url="https://apt.2ndquadrant.com/">public apt repository</ulink> for 2ndQuadrant software,
-	  including &repmgr;.
-	</para>
-	<para>
-	  General instructions for using this repository can be found on its
-	  <ulink url="https://apt.2ndquadrant.com/">homepage</ulink>. Specific instructions
-	  for installing &repmgr; follow below.
-	</para>
-
-    <para>
-      <emphasis>Installation</emphasis>
-
-      <itemizedlist>
-
-		<listitem>
-		  <para>
-			If not already present, install the  <application>apt-transport-https</application> package:
-			<programlisting>
-sudo apt-get install apt-transport-https</programlisting>
-		  </para>
-		</listitem>
-
-		<listitem>
-		  <para>
-			Create <filename>/etc/apt/sources.list.d/2ndquadrant.list</filename> as follows:
-			<programlisting>
-sudo sh -c 'echo "deb https://apt.2ndquadrant.com/ $(lsb_release -cs)-2ndquadrant main" > /etc/apt/sources.list.d/2ndquadrant.list'</programlisting>
-		  </para>
-		</listitem>
-
-		<listitem>
-		  <para>
-			Install the 2ndQuadrant <ulink url="https://apt.2ndquadrant.com/site/keys/9904CD4BD6BAF0C3.asc">repository key</ulink>:
-			<programlisting>
-sudo apt-get install curl ca-certificates
-curl https://apt.2ndquadrant.com/site/keys/9904CD4BD6BAF0C3.asc | sudo apt-key add -</programlisting>
-		  </para>
-		</listitem>
-
-		<listitem>
-		  <para>
-			Update the package list
-			<programlisting>
- sudo apt-get update</programlisting>
-		  </para>
-		</listitem>
-
-		<listitem>
-		  <para>
-            Install the &repmgr version appropriate for your PostgreSQL version (e.g. <literal>repmgr10</literal>):
-            <programlisting>
-$ apt-get install postgresql-10-repmgr</programlisting>
-		  </para>
-          <note>
-            <para>
-            For packages for PostgreSQL 9.6 and earlier, the package name includes
-            a period between major and minor version numbers, e.g.
-            <literal>postgresql-9.6-repmgr</literal>.
-            </para>
-          </note>
-		</listitem>
-
-	  </itemizedlist>
-
-	</para>
-
-  </sect3>
- </sect2>
-
-</sect1>
--- a/doc/install-packages.xml
+++ b/doc/install-packages.xml
@@ -0,0 +1,284 @@
+<sect1 id="installation-packages" xreflabel="Installing from packages">
+ <title>Installing &repmgr; from packages</title>
+
+  <indexterm>
+   <primary>installation</primary>
+   <secondary>from packages</secondary>
+  </indexterm>
+
+ <para>
+  We recommend installing &repmgr; using the available packages for your
+  system.
+ </para>
+
+ <sect2 id="installation-packages-redhat" xreflabel="Installing from packages on RHEL, CentOS and Fedora">
+
+  <title>RedHat/CentOS/Fedora</title>
+
+  <indexterm>
+   <primary>installation</primary>
+   <secondary>on Red Hat/CentOS/Fedora etc.</secondary>
+  </indexterm>
+
+  <para>
+	&repmgr; RPM packages for RedHat/CentOS variants and Fedora are available from the
+	<ulink url="https://2ndquadrant.com">2ndQuadrant</ulink>
+	<ulink url="https://dl.2ndquadrant.com/">public repository</ulink>; see following
+	section for details.
+  </para>
+  <para>
+   RPM packages for &repmgr; are also available via Yum through
+   the PostgreSQL Global Development Group RPM repository
+   (<ulink url="https://yum.postgresql.org/">http://yum.postgresql.org/</ulink>).
+   Follow the instructions for your distribution (RedHat, CentOS,
+   Fedora, etc.) and architecture as detailed there. Note that it can take some days
+   for new &repmgr; packages to become available via the this repository.
+  </para>
+  <note>
+    <para>
+      &repmgr; RPM packages are designed to be compatible with the community-provided PostgreSQL packages
+      and 2ndQuadrant's <ulink url="https://www.2ndquadrant.com/en/resources/2ndqpostgres/">2ndQPostgres</ulink>.
+      They may not work with vendor-specific packages such as those provided by RedHat for RHEL
+      customers, as the PostgreSQL filesystem layout may be different to the community RPMs.
+      Please contact your support vendor for assistance.
+    </para>
+    <para>
+      See also <link linkend="appendix-faq">FAQ</link> entry
+      <xref linkend="faq-third-party-packages"/>.
+    </para>
+  </note>
+
+  <para>
+    For more information on the package contents, including details of installation
+    paths and relevant <link linkend="configuration-file-service-commands">service commands</link>,
+    see the appendix section <xref linkend="packages-centos"/>.
+  </para>
+
+
+  <sect3 id="installation-packages-redhat-2ndq">
+    <title>2ndQuadrant public RPM yum repository</title>
+
+    <para>
+      <ulink url="https://2ndquadrant.com/">2ndQuadrant</ulink> provides a dedicated <literal>yum</literal>
+      <ulink url="https://dl.2ndquadrant.com/">public repository</ulink> for 2ndQuadrant software,
+      including &repmgr;. We recommend using this for all future &repmgr; releases.
+    </para>
+    <para>
+      General instructions for using this repository can be found on its
+      <ulink url="https://dl.2ndquadrant.com/">homepage</ulink>. Specific instructions
+      for installing &repmgr; follow below.
+    </para>
+    <para>
+      <emphasis>Installation</emphasis>
+
+      <itemizedlist>
+	<listitem>
+	  <para>
+	    Locate the repository RPM for your PostgreSQL version from the list at:
+	    <ulink url="https://dl.2ndquadrant.com/">https://dl.2ndquadrant.com/</ulink>
+	  </para>
+	</listitem>
+
+        <listitem>
+          <para>
+            Install the repository definition for your distribution and PostgreSQL version
+	    (this enables the 2ndQuadrant repository as a source of &repmgr; packages).
+	  </para>
+	  <para>
+	    For example, for PostgreSQL 11 on CentOS, execute:
+	    <programlisting>
+curl https://dl.2ndquadrant.com/default/release/get/11/rpm | sudo bash</programlisting>
+	  </para>
+
+	  <para>
+	    For PostgreSQL 9.6 on CentOS, execute:
+	    <programlisting>
+curl https://dl.2ndquadrant.com/default/release/get/9.6/rpm | sudo bash</programlisting>
+	  </para>
+
+
+	  <para>
+	    Verify that the repository is installed with:
+	    <programlisting>
+sudo yum repolist</programlisting>
+	    The output should contain two entries like this:
+	    <programlisting>
+2ndquadrant-dl-default-release-pg11/7/x86_64         2ndQuadrant packages (PG11) for 7 - x86_64               18
+2ndquadrant-dl-default-release-pg11-debug/7/x86_64   2ndQuadrant packages (PG11) for 7 - x86_64 - Debug        8</programlisting>
+	  </para>
+	</listitem>
+
+        <listitem>
+          <para>
+            Install the &repmgr; version appropriate for your PostgreSQL version (e.g. <literal>repmgr10</literal>):
+            <programlisting>
+sudo yum install repmgr11</programlisting>
+          </para>
+          <note>
+            <para>
+              For packages for PostgreSQL 9.6 and earlier, the package name does not contain
+              a period between major and minor version numbers, e.g.
+              <literal>repmgr96</literal>.
+            </para>
+          </note>
+          <tip>
+            <para>
+              To determine the names of available packages, execute:
+              <programlisting>
+yum search repmgr</programlisting>
+            </para>
+          </tip>
+
+        </listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      <emphasis>Compatibility with PGDG Repositories</emphasis>
+    </para>
+    <para>
+      The 2ndQuadrant &repmgr; yum repository packages use the same definitions and file system layout as the
+      main PGDG repository.
+    </para>
+    <para>
+      Normally <application>yum</application> will prioritize the repository with the most recent &repmgr; version.
+      Once the PGDG repository has been updated, it doesn't matter which repository
+      the packages are installed from.
+    </para>
+    <para>
+      To ensure the 2ndQuadrant repository is always prioritised, install <literal>yum-plugin-priorities</literal>
+      and set the repository priorities accordingly.
+    </para>
+
+    <para>
+      <emphasis>Installing a specific package version</emphasis>
+    </para>
+    <para>
+      To install a specific package version, execute <command>yum --showduplicates list</command>
+      for the package in question:
+      <programlisting>
+[root@localhost ~]# yum --showduplicates list repmgr11
+Loaded plugins: fastestmirror
+Loading mirror speeds from cached hostfile
+ * base: ftp.tsukuba.wide.ad.jp
+ * epel: nrt.edge.kernel.org
+ * extras: ftp.tsukuba.wide.ad.jp
+ * updates: ftp.tsukuba.wide.ad.jp
+Installed Packages
+repmgr11.x86_64                        4.4.0-1.rhel7                         @pgdg11
+Available Packages
+repmgr11.x86_64                        4.2-1.el7                             2ndquadrant-dl-default-release-pg11
+repmgr11.x86_64                        4.2-2.el7                             2ndquadrant-dl-default-release-pg11
+repmgr11.x86_64                        4.3-1.el7                             2ndquadrant-dl-default-release-pg11
+repmgr11.x86_64                        4.4-1.el7                             2ndquadrant-dl-default-release-pg11</programlisting>
+      then append the appropriate version number to the package name with a hyphen, e.g.:
+      <programlisting>
+[root@localhost ~]# yum install repmgr11-4.3-1.el7</programlisting>
+    </para>
+
+    <para>
+      <emphasis>Installing old packages</emphasis>
+    </para>
+    <para>
+      See appendix <link linkend="packages-old-versions-rhel-centos">Installing old package versions</link>
+      for details on how to retrieve older package versions.
+    </para>
+
+  </sect3>
+
+ </sect2>
+
+ <sect2 id="installation-packages-debian" xreflabel="Installing from packages on Debian or Ubuntu">
+
+  <title>Debian/Ubuntu</title>
+
+  <indexterm>
+   <primary>installation</primary>
+   <secondary>on Debian/Ubuntu etc.</secondary>
+  </indexterm>
+
+  <para>.deb packages for &repmgr; are available from the
+  PostgreSQL Community APT repository (<ulink url="http://apt.postgresql.org/">http://apt.postgresql.org/</ulink>).
+  Instructions can be found in the APT section of the PostgreSQL Wiki
+  (<ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</ulink>).
+  </para>
+  <para>
+    For more information on the package contents, including details of installation
+    paths and relevant <link linkend="configuration-file-service-commands">service commands</link>,
+    see the appendix section <xref linkend="packages-debian-ubuntu"/>.
+  </para>
+
+  <sect3 id="installation-packages-debian-ubuntu-2ndq">
+    <title>2ndQuadrant public apt repository for Debian/Ubuntu</title>
+
+    <para>
+      <ulink url="https://2ndquadrant.com/">2ndQuadrant</ulink> provides a
+      <ulink url="https://dl.2ndquadrant.com/">public apt repository</ulink> for 2ndQuadrant software,
+      including &repmgr;.
+    </para>
+    <para>
+      General instructions for using this repository can be found on its
+      <ulink url="https://dl.2ndquadrant.com/">homepage</ulink>. Specific instructions
+      for installing &repmgr; follow below.
+    </para>
+
+    <para>
+
+      <emphasis>Installation</emphasis>
+
+      <itemizedlist>
+
+	    <listitem>
+	      <para>
+            Install the repository definition for your distribution and PostgreSQL version
+	        (this enables the 2ndQuadrant repository as a source of &repmgr; packages) by executing:
+            <programlisting>
+              curl https://dl.2ndquadrant.com/default/release/get/deb | sudo bash</programlisting>
+	      </para>
+          <note>
+            <para>
+              This will automatically install the following additional packages, if not already present:
+              <itemizedlist spacing="compact" mark="bullet">
+                <listitem>
+                  <simpara><literal>lsb-release</literal></simpara>
+                </listitem>
+                <listitem>
+                  <simpara><literal>apt-transport-https</literal></simpara>
+                </listitem>
+              </itemizedlist>
+            </para>
+          </note>
+        </listitem>
+
+	    <listitem>
+	      <para>
+            Install the &repmgr; version appropriate for your PostgreSQL version (e.g. <literal>repmgr11</literal>):
+            <programlisting>
+              sudo apt-get install postgresql-11-repmgr</programlisting>
+	      </para>
+          <note>
+            <para>
+              For packages for PostgreSQL 9.6 and earlier, the package name includes
+              a period between major and minor version numbers, e.g.
+              <literal>postgresql-9.6-repmgr</literal>.
+            </para>
+          </note>
+	    </listitem>
+
+      </itemizedlist>
+
+    </para>
+
+    <para>
+      <emphasis>Installing old packages</emphasis>
+    </para>
+    <para>
+      See appendix <link linkend="packages-old-versions-debian">Installing old package versions</link>
+      for details on how to retrieve older package versions.
+    </para>
+
+
+  </sect3>
+ </sect2>
+
+</sect1>
--- a/doc/install-requirements.sgml
+++ b/doc/install-requirements.sgml
@@ -1,72 +0,0 @@
-<sect1 id="install-requirements" xreflabel="installation requirements">
-
-  <indexterm>
-   <primary>installation</primary>
-   <secondary>requirements</secondary>
-  </indexterm>
-
-  <title>Requirements for installing repmgr</title>
-  <para>
-    repmgr is developed and tested on Linux and OS X, but should work on any
-    UNIX-like system supported by PostgreSQL itself. There is no support for
-    Microsoft Windows.
-  </para>
-
-  <para>
-   From version 4.0, repmgr is compatible with all PostgreSQL versions from 9.3, including PostgreSQL 10.
-   Note that some &repmgr; functionality is not available in PostgreSQL 9.3 and PostgreSQL 9.4.
-  </para>
-
-  <note>
-   <simpara>
-    If upgrading from &repmgr; 3.x, please see the section <xref linkend="upgrading-from-repmgr-3">.
-   </simpara>
-  </note>
-
-  <para>
-   All servers in the replication cluster must be running the same major version of
-   PostgreSQL, and we recommend that they also run the same minor version.
-  </para>
-
-  <para>
-   &repmgr; must be installed on each server in the replication cluster.
-   If installing repmgr from packages, the package version must match the PostgreSQL
-   version. If installing from source, repmgr must be compiled against the same
-   major version.
-  </para>
-
-  <para>
-   A dedicated system user for &repmgr; is *not* required; as many &repmgr; and
-   <application>repmgrd</application> actions require direct access to the PostgreSQL data directory,
-   these commands should be executed by the <literal>postgres</literal> user.
-  </para>
-
-  <para>
-   Passwordless <command>ssh</command> connectivity between all servers in the replication cluster
-   is not required, but is necessary in the following cases:
-   <itemizedlist>
-     <listitem>
-       <simpara>if you need &repmgr; to copy configuration files from outside the PostgreSQL
-       data directory (in which case <command>rsync</command> is also required)</simpara>
-     </listitem>
-     <listitem>
-       <simpara>to perform <link linkend="performing-switchover">switchover operations</link></simpara>
-     </listitem>
-     <listitem>
-       <simpara>
-        when executing <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command>
-        and <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>
-       </simpara>
-     </listitem>
-   </itemizedlist>
-  </para>
-
-  <tip>
-   <simpara>
-    We recommend using a session multiplexer utility such as <command>screen</command> or
-    <command>tmux</command> when performing long-running actions (such as cloning a database)
-    on a remote server - this will ensure the &repmgr; action won't be prematurely
-    terminated if your <command>ssh</command> session to the server is interrupted or closed.
-    </simpara>
-  </tip>
- </sect1>
--- a/doc/install-requirements.xml
+++ b/doc/install-requirements.xml
@@ -0,0 +1,226 @@
+<sect1 id="install-requirements" xreflabel="installation requirements">
+
+  <title>Requirements for installing repmgr</title>
+
+  <indexterm>
+   <primary>installation</primary>
+   <secondary>requirements</secondary>
+  </indexterm>
+
+  <para>
+    repmgr is developed and tested on Linux and OS X, but should work on any
+    UNIX-like system supported by PostgreSQL itself. There is no support for
+    Microsoft Windows.
+  </para>
+
+  <para>
+   &repmgr; &repmgrversion; is compatible with all PostgreSQL versions from 9.3. See
+   section <link linkend="install-compatibility-matrix">&repmgr; compatibility matrix</link>
+   for an overview of version compatibility.
+  </para>
+
+  <note>
+   <simpara>
+    If upgrading from &repmgr; 3.x, please see the section <xref linkend="upgrading-from-repmgr-3"/>.
+   </simpara>
+  </note>
+
+  <para>
+   All servers in the replication cluster must be running the same major version of
+   PostgreSQL, and we recommend that they also run the same minor version.
+  </para>
+
+  <para>
+   &repmgr; must be installed on each server in the replication cluster.
+   If installing repmgr from packages, the package version must match the PostgreSQL
+   version. If installing from source, &repmgr; must be compiled against the same
+   major version.
+  </para>
+
+  <note>
+   <simpara>
+     The same &quot;major&quot; &repmgr; version (e.g. <literal>&repmgrversion;.x</literal>) <emphasis>must</emphasis>
+     be installed on all node in the replication cluster. We strongly recommend keeping all
+     nodes on the same (preferably latest) &quot;minor&quot; &repmgr; version to minimize the risk
+     of incompatibilities.
+   </simpara>
+   <simpara>
+     If different &quot;major&quot; &repmgr; versions (e.g. 4.1.x and &repmgrversion;.x)
+     are installed on different nodes, in the best case &repmgr; (in particular &repmgrd;)
+     will not run. In the worst case, you will end up with a broken cluster.
+   </simpara>
+  </note>
+
+  <para>
+   A dedicated system user for &repmgr; is <emphasis>not</emphasis> required; as many &repmgr; and
+   &repmgrd; actions require direct access to the PostgreSQL data directory,
+   these commands should be executed by the <literal>postgres</literal> user.
+  </para>
+
+  <para>
+    See also <link linkend="configuration-prerequisites">Prerequisites for configuration</link>
+    for information on networking requirements.
+  </para>
+
+  <tip>
+   <simpara>
+    We recommend using a session multiplexer utility such as <command>screen</command> or
+    <command>tmux</command> when performing long-running actions (such as cloning a database)
+    on a remote server - this will ensure the &repmgr; action won't be prematurely
+    terminated if your <command>ssh</command> session to the server is interrupted or closed.
+    </simpara>
+  </tip>
+
+  <sect2 id="install-compatibility-matrix">
+
+    <title>&repmgr; compatibility matrix</title>
+
+    <indexterm>
+      <primary>repmgr</primary>
+      <secondary>compatibility matrix</secondary>
+    </indexterm>
+
+    <indexterm>
+      <primary>compatibility matrix</primary>
+    </indexterm>
+
+    <para>
+      The following table provides an overview of which &repmgr; version supports
+      which PostgreSQL version.
+    </para>
+
+
+    <table id="repmgr-compatibility-matrix">
+      <title>&repmgr; compatibility matrix</title>
+
+      <tgroup cols="3">
+        <thead>
+          <row>
+            <entry>
+              &repmgr; version
+            </entry>
+            <entry>
+              Latest release
+            </entry>
+            <entry>
+              Supported PostgreSQL versions
+            </entry>
+          </row>
+        </thead>
+
+        <tbody>
+
+          <row>
+            <entry>
+              &repmgr; 5.x
+            </entry>
+            <entry>
+              <link linkend="release-current">&repmgrversion;</link> (&releasedate;)
+            </entry>
+            <entry>
+              9.3, 9.4, 9.5, 9.6, 10, 11, 12
+            </entry>
+          </row>
+
+          <row>
+            <entry>
+              &repmgr; 4.x
+            </entry>
+            <entry>
+              <link linkend="release-4.4">4.4</link> (2019-06-27)
+            </entry>
+            <entry>
+              9.3, 9.4, 9.5, 9.6, 10, 11
+            </entry>
+          </row>
+
+          <row>
+            <entry>
+              &repmgr; 3.x
+            </entry>
+            <entry>
+              <ulink url="https://repmgr.org/release-notes-3.3.2.html">3.3.2</ulink> (2017-05-30)
+            </entry>
+            <entry>
+              9.3, 9.4, 9.5, 9.6
+            </entry>
+          </row>
+
+          <row>
+            <entry>
+              &repmgr; 2.x
+            </entry>
+            <entry>
+              <ulink url="https://repmgr.org/release-notes-2.0.3.html">2.0.3</ulink> (2015-04-16)
+            </entry>
+            <entry>
+              9.0, 9.1, 9.2, 9.3, 9.4
+            </entry>
+          </row>
+        </tbody>
+
+      </tgroup>
+    </table>
+
+    <important>
+      <para>
+        The &repmgr; 2.x and 3.x series are no longer maintained or supported.
+        We strongly recommend  upgrading to the latest &repmgr; version.
+      </para>
+      <para>
+        Following the release of &repmgr; 5.0, there will be no further releases of
+        the &repmgr; 4.x series. Note that &repmgr; 5.x is an incremental development
+        of the 4.x series and &repmgr; 4.x users should upgrade to this as soon as possible.
+      </para>
+    </important>
+
+  </sect2>
+
+  <sect2 id="install-postgresql-93-94">
+
+    <title>PostgreSQL 9.3 and 9.4 support</title>
+
+    <indexterm>
+      <primary>PostgreSQL 9.3</primary>
+      <secondary>repmgr support</secondary>
+    </indexterm>
+
+    <para>
+      Note that some &repmgr; functionality is not available in PostgreSQL 9.3 and PostgreSQL 9.4:
+    </para>
+    <itemizedlist spacing="compact" mark="bullet">
+
+      <listitem>
+        <para>
+          PostgreSQL 9.3 does not support replication slots, so corresponding &repmgr; functionality
+          is not available.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          In PostgreSQL 9.3 and PostgreSQL 9.4, <command>pg_rewind</command> is not part of the core
+          distribution. <command>pg_rewind</command> will need to be compiled separately to be able
+          to use any &repmgr; functionality which takes advantage of it.
+        </para>
+      </listitem>
+    </itemizedlist>
+
+    <important>
+      <para>
+        PostgreSQL 9.3 has reached the end of its community support period (final release was
+        <ulink url="https://www.postgresql.org/docs/9.3/release-9-3-25.html">9.3.25</ulink>)
+        and will no longer be updated with security or bugfixes.
+      </para>
+      <para>
+        PostgreSQL 9.4. is scheduled for its final release in February 2020
+        (see <ulink url="https://www.postgresql.org/support/versioning/">PostgreSQL Versioning Policy</ulink>).
+      </para>
+      <para>
+        We recommend that users of these versions migrate to a recent PostgreSQL version
+        as soon as possible.
+      </para>
+    </important>
+
+  </sect2>
+
+ </sect1>
--- a/doc/install-source.sgml
+++ b/doc/install-source.sgml
@@ -1,175 +0,0 @@
-<sect1 id="installation-source" xreflabel="Installing from source code">
-  <indexterm>
-   <primary>installation</primary>
-   <secondary>from source</secondary>
-  </indexterm>
-
- <title>Installing &repmgr; from source</title>
-
- <sect2 id="installation-source-prereqs">
-  <title>Prerequisites for installing from source</title>
-  <para>
-   To install &repmgr; the prerequisites for compiling
-   &postgres; must be installed. These are described in &postgres;'s
-   documentation
-   on <ulink url="https://www.postgresql.org/docs/current/install-requirements.html">build requirements</ulink>
-   and <ulink url="https://www.postgresql.org/docs/current/docguide-toolsets.html">build requirements for documentation</ulink>.
-  </para>
-
-  <para>
-   Most mainstream Linux distributions and other UNIX variants provide simple
-   ways to install the prerequisites from packages.
-   <itemizedlist spacing="compact" mark="bullet">
-    <listitem>
-     <para>
-      <literal>Debian</literal> and <literal>Ubuntu</literal>: First
-      add the <ulink
-      url="http://apt.postgresql.org/">apt.postgresql.org</ulink>
-      repository to your <filename>sources.list</filename> if you
-      have not already done so. Then install the pre-requisites for
-      building PostgreSQL with:
-      <programlisting>
-       sudo apt-get update
-       sudo apt-get build-dep postgresql-9.6</programlisting>
-      </para>
-    </listitem>
-    <listitem>
-     <para>
-      <literal>RHEL or CentOS 6.x or 7.x</literal>: install the appropriate repository RPM
-      for your system from <ulink url="https://yum.postgresql.org/repopackages.php">
-      yum.postgresql.org</ulink>. Then install the prerequisites for building
-      PostgreSQL with:
-      <programlisting>
-       sudo yum check-update
-       sudo yum groupinstall "Development Tools"
-       sudo yum install yum-utils openjade docbook-dtds docbook-style-dsssl docbook-style-xsl
-       sudo yum-builddep postgresql96</programlisting>
-     </para>
-    </listitem>
-   </itemizedlist>
-  </para>
-
-  <note>
-    <simpara>
-      Select the appropriate PostgreSQL versions for your target repmgr version.
-    </simpara>
-  </note>
- </sect2>
-
-
-<sect2 id="installation-get-source">
-  <title>Getting &repmgr; source code</title>
-
-  <para>
-   There are two ways to get the &repmgr; source code: with git, or by downloading tarballs of released versions.
-  </para>
-
-  <sect3>
-   <title>Using <application>git</application> to get the &repmgr; sources</title>
-
-   <para>
-    Use <application><ulink url="https://git-scm.com">git</ulink></application> if you expect
-    to update often, you want to keep track of development or if you want to contribute
-    changes to &repmgr;. There is no reason <emphasis>not</emphasis> to use <application>git</application>
-    if you're familiar with it.
-   </para>
-
-   <para>
-    The source for &repmgr; is maintained at
-    <ulink url="https://github.com/2ndQuadrant/repmgr">https://github.com/2ndQuadrant/repmgr</ulink>.
-   </para>
-
-   <para>
-    There are also tags for each &repmgr; release, e.g. <filename>4.0.5</filename>.
-   </para>
-
-   <para>
-    Clone the source code using <application>git</application>:
-    <programlisting>
-     git clone https://github.com/2ndQuadrant/repmgr</programlisting>
-   </para>
-
-   <para>
-    For more information on using <application>git</application> see
-    <ulink url="https://git-scm.com/">git-scm.com</ulink>.
-   </para>
-
-  </sect3>
-
-  <sect3>
-   <title>Downloading release source tarballs</title>
-
-   <para>
-    Official release source code is uploaded as tarballs to the
-    &repmgr; website along with a tarball checksum and a matching GnuPG
-    signature. See
-    <ulink url="http://repmgr.org/">http://repmgr.org/</ulink>
-    for the download information. See <xref linkend="appendix-signatures">
-    for information on verifying digital signatures.
-   </para>
-
-   <para>
-    You will need to download the repmgr source, e.g. <filename>repmgr-4.0.tar.gz</filename>.
-    You may optionally verify the package checksums from the
-    <literal>.md5</literal> files and/or verify the GnuPG signatures
-    per <xref linkend="appendix-signatures">.
-   </para>
-
-   <para>
-    After you unpack the source code archives using <literal>tar xf</literal>
-    the installation process is the same as if you were installing from a git
-    clone.
-   </para>
-
-  </sect3>
-
- </sect2>
-
- <sect2 id="installation-repmgr-source">
-  <title>Installation of &repmgr; from source</title>
-  <para>
-   To installing &repmgr; from source, simply execute:
-
-   <programlisting>
-    ./configure && make install</programlisting>
-
-   Ensure <command>pg_config</command> for the target PostgreSQL version is in
-   <varname>$PATH</varname>.
-  </para>
- </sect2>
-
-
-
- <sect2 id="installation-build-repmgr-docs">
-   <title>Building &repmgr; documentation</title>
-   <para>
-    The &repmgr; documentation is (like the main PostgreSQL project)
-    written in DocBook format. To build it locally as HTML, you'll need to
-    install the required packages as described in the
-    <ulink url="https://www.postgresql.org/docs/9.6/static/docguide-toolsets.html">
-      PostgreSQL documentation</ulink> then execute:
-   <programlisting>
-    ./configure && make install-doc</programlisting>
-   </para>
-   <para>
-     The generated HTML files will be placed in the <filename>doc/html</filename>
-     subdirectory of your source tree.
-   </para>
-
-   <para>
-     To build the documentation as a single HTML file, execute:
-   <programlisting>
-    cd doc/ && make repmgr.html</programlisting>
-   </para>
-
-   <note>
-     <simpara>
-       Due to changes in PostgreSQL's documentation build system from PostgreSQL 10,
-       the documentation can currently only be built agains PostgreSQL 9.6 or earlier.
-       This limitation will be fixed when time and resources permit.
-     </simpara>
-   </note>
- </sect2>
-
-
-</sect1>
--- a/doc/install-source.xml
+++ b/doc/install-source.xml
@@ -0,0 +1,294 @@
+<sect1 id="installation-source" xreflabel="Installing from source code">
+
+ <title>Installing &repmgr; from source</title>
+
+ <indexterm>
+  <primary>installation</primary>
+  <secondary>from source</secondary>
+ </indexterm>
+
+ <sect2 id="installation-source-prereqs">
+  <title>Prerequisites for installing from source</title>
+  <para>
+   To install &repmgr; the prerequisites for compiling
+   &postgres; must be installed. These are described in &postgres;'s
+   documentation
+   on <ulink url="https://www.postgresql.org/docs/current/install-requirements.html">build requirements</ulink>
+   and <ulink url="https://www.postgresql.org/docs/current/docguide-toolsets.html">build requirements for documentation</ulink>.
+  </para>
+
+  <para>
+   Most mainstream Linux distributions and other UNIX variants provide simple
+   ways to install the prerequisites from packages.
+   <itemizedlist spacing="compact" mark="bullet">
+    <listitem>
+     <para>
+      <literal>Debian</literal> and <literal>Ubuntu</literal>: First
+      add the <ulink
+      url="http://apt.postgresql.org/">apt.postgresql.org</ulink>
+      repository to your <filename>sources.list</filename> if you
+      have not already done so, and ensure the source repository is enabled.
+     </para>
+     <tip>
+       <para>
+         If not configured, the source repository can be added by including
+         a <literal>deb-src</literal> line as a copy of the existing <literal>deb</literal>
+         line in the repository file, which is usually
+         <filename>/etc/apt/sources.list.d/pgdg.list</filename>, e.g.:
+         <programlisting>
+deb http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main
+deb-src http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main</programlisting>
+       </para>
+     </tip>
+     <para>
+      Then install the prerequisites for
+      building PostgreSQL with e.g.:
+      <programlisting>
+       sudo apt-get update
+       sudo apt-get build-dep postgresql-9.6</programlisting>
+      </para>
+
+     <important>
+       <simpara>
+         Select the appropriate PostgreSQL version for your target repmgr version.
+       </simpara>
+     </important>
+
+     <note>
+       <para>
+       If using <command>apt-get build-dep</command> is not possible, the
+       following packages may need to be installed manually:
+
+         <itemizedlist spacing="compact" mark="bullet">
+
+           <listitem>
+             <simpara><literal>flex</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libedit-dev</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libkrb5-dev</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libpam0g-dev</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libreadline-dev</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libselinux1-dev</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libssl-dev</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libxml2-dev</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libxslt1-dev</literal></simpara>
+           </listitem>
+         </itemizedlist>
+       </para>
+     </note>
+
+    </listitem>
+    <listitem>
+     <para>
+      <literal>RHEL or CentOS 6.x or 7.x</literal>: install the appropriate repository RPM
+      for your system from <ulink url="https://yum.postgresql.org/repopackages.php">
+      yum.postgresql.org</ulink>. Then install the prerequisites for building
+      PostgreSQL with:
+      <programlisting>
+       sudo yum check-update
+       sudo yum groupinstall "Development Tools"
+       sudo yum install yum-utils openjade docbook-dtds docbook-style-dsssl docbook-style-xsl
+       sudo yum-builddep postgresql96</programlisting>
+     </para>
+
+     <important>
+       <simpara>
+         Select the appropriate PostgreSQL version for your target repmgr version.
+       </simpara>
+     </important>
+     <note>
+       <para>
+         If using <command>yum-builddep</command> is not possible, the
+         following packages may need to be installed manually:
+
+         <itemizedlist spacing="compact" mark="bullet">
+
+           <listitem>
+             <simpara><literal>flex</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libselinux-devel</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libxml2-devel</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>libxslt-devel</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>openssl-devel</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>pam-devel</literal></simpara>
+           </listitem>
+           <listitem>
+             <simpara><literal>readline-devel</literal></simpara>
+           </listitem>
+
+         </itemizedlist>
+       </para>
+     </note>
+
+     <tip>
+       <para>
+         If building against PostgreSQL 11 or later configured with the <option>--with-llvm</option> option
+         (this is the case with the PGDG-provided packages) you'll also need to install the
+         <literal>llvm-toolset-7-clang</literal> package. This is available via the
+         <ulink url="https://wiki.centos.org/AdditionalResources/Repositories/SCL">Software Collections (SCL) Repository</ulink>.
+       </para>
+     </tip>
+
+    </listitem>
+   </itemizedlist>
+  </para>
+
+ </sect2>
+
+
+<sect2 id="installation-get-source">
+  <title>Getting &repmgr; source code</title>
+
+  <para>
+   There are two ways to get the &repmgr; source code: with git, or by downloading tarballs of released versions.
+  </para>
+
+  <sect3>
+   <title>Using <application>git</application> to get the &repmgr; sources</title>
+
+   <para>
+    Use <application><ulink url="https://git-scm.com">git</ulink></application> if you expect
+    to update often, you want to keep track of development or if you want to contribute
+    changes to &repmgr;. There is no reason <emphasis>not</emphasis> to use <application>git</application>
+    if you're familiar with it.
+   </para>
+
+   <para>
+    The source for &repmgr; is maintained at
+    <ulink url="https://github.com/2ndQuadrant/repmgr">https://github.com/2ndQuadrant/repmgr</ulink>.
+   </para>
+
+   <para>
+    There are also tags for each <ulink url="https://github.com/2ndQuadrant/repmgr/releases">&repmgr; release</ulink>, e.g.
+    <literal><ulink url="https://github.com/2ndQuadrant/repmgr/releases/tag/v4.4.0">v4.4.0</ulink></literal>.
+   </para>
+
+   <para>
+    Clone the source code using <application>git</application>:
+    <programlisting>
+     git clone https://github.com/2ndQuadrant/repmgr</programlisting>
+   </para>
+
+   <para>
+    For more information on using <application>git</application> see
+    <ulink url="https://git-scm.com/">git-scm.com</ulink>.
+   </para>
+
+  </sect3>
+
+  <sect3>
+   <title>Downloading release source tarballs</title>
+
+   <para>
+    Official release source code is uploaded as tarballs to the
+    &repmgr; website along with a tarball checksum and a matching GnuPG
+    signature. See
+    <ulink url="http://repmgr.org/">http://repmgr.org/</ulink>
+    for the download information. See <xref linkend="appendix-signatures"/>
+    for information on verifying digital signatures.
+   </para>
+
+   <para>
+    You will need to download the repmgr source, e.g. <filename>repmgr-4.0.tar.gz</filename>.
+    You may optionally verify the package checksums from the
+    <literal>.md5</literal> files and/or verify the GnuPG signatures
+    per <xref linkend="appendix-signatures"/>.
+   </para>
+
+   <para>
+    After you unpack the source code archives using <command>tar xf</command>
+    the installation process is the same as if you were installing from a git
+    clone.
+   </para>
+
+  </sect3>
+
+ </sect2>
+
+ <sect2 id="installation-repmgr-source">
+  <title>Installation of &repmgr; from source</title>
+  <para>
+   To installing &repmgr; from source, simply execute:
+
+   <programlisting>
+    ./configure &amp;&amp; make install</programlisting>
+
+   Ensure <command>pg_config</command> for the target PostgreSQL version is in
+   <varname>$PATH</varname>.
+  </para>
+ </sect2>
+
+
+
+ <sect2 id="installation-build-repmgr-docs" xreflabel="Building repmgr documentation">
+   <title>Building &repmgr; documentation</title>
+   <para>
+    The &repmgr; documentation is (like the main PostgreSQL project)
+    written in DocBook XML format. To build it locally as HTML, you'll need to
+    install the required packages as described in the
+    <ulink url="https://www.postgresql.org/docs/current/docguide-toolsets.html">PostgreSQL documentation</ulink>.
+   </para>
+   <para>
+	 The minimum PostgreSQL version for building the &repmgr; documentation is
+	 PostgreSQL 9.5.
+   </para>
+
+   <note>
+     <simpara>
+       In &repmgr; 4.3 and earlier, the documentation can only be built against
+       PostgreSQL 9.6 or earlier.
+     </simpara>
+   </note>
+
+   <para>
+     To build the documentation as HTML, execute:
+   <programlisting>
+    ./configure &amp;&amp; make doc</programlisting>
+   </para>
+   <para>
+     The generated HTML files will be placed in the <filename>doc/html</filename>
+     subdirectory of your source tree.
+   </para>
+
+   <para>
+     To build the documentation as a single HTML file, after configuring and building
+     the main &repmgr; source as described above, execute:
+   <programlisting>
+     ./configure &amp;&amp; make doc-repmgr.html</programlisting>
+   </para>
+
+   <para>
+     To build the documentation as a PDF file, after configuring and building
+     the main &repmgr; source as described above, execute:
+   <programlisting>
+     ./configure &amp;&amp; make doc-repmgr-A4.pdf</programlisting>
+   </para>
+
+
+ </sect2>
+
+</sect1>
--- a/doc/install.sgml
+++ b/doc/install.sgml
@@ -1,10 +1,11 @@
 <chapter id="installation" xreflabel="Installation">
+
+ <title>Installation</title>
+
 <indexterm>
  <primary>installation</primary>
 </indexterm>

- <title>Installation</title>
-
 <para>
  &repmgr; can be installed from binary packages provided by your operating
  system's packaging system, or from source.
@@ -18,7 +19,7 @@
  only option if there are no packages for your operating system yet.
 </para>
 <para>
-  Before installing &repmgr; make sure you satisfy the <xref linkend="install-requirements">.
+  Before installing &repmgr; make sure you satisfy the <xref linkend="install-requirements"/>.
 </para>

 &install-requirements;
--- a/doc/legal.sgml
+++ b/doc/legal.sgml
@@ -1,9 +1,9 @@
-<!-- doc/legal.sgml -->
+<!-- doc/legal.xml -->

 <date>2017</date>

 <copyright>
- <year>2010-2018</year>
+ <year>2010-2019</year>
 <holder>2ndQuadrant, Ltd.</holder>
 </copyright>

@@ -11,7 +11,7 @@
 <title>Legal Notice</title>

 <para>
-  <productname>repmgr</productname> is Copyright &copy; 2010-2018
+  <productname>repmgr</productname> is Copyright &copy; 2010-2019
  by 2ndQuadrant, Ltd. All rights reserved.
 </para>

--- a/doc/overview.sgml
+++ b/doc/overview.sgml
@@ -7,18 +7,18 @@
 </para>
 <sect1 id="repmgr-concepts" xreflabel="Concepts">

+  <title>Concepts</title>
+
  <indexterm>
    <primary>concepts</primary>
  </indexterm>

-  <title>Concepts</title>
-
  <para>
   This guide assumes that you are familiar with PostgreSQL administration and
   streaming replication concepts. For further details on streaming
   replication, see the PostgreSQL documentation section on <ulink
-   url="https://www.postgresql.org/docs/current/interactive/warm-standby.html#STREAMING-REPLICATION">
-   streaming replication</>.
+   url="https://www.postgresql.org/docs/current/warm-standby.html#STREAMING-REPLICATION">
+   streaming replication</ulink>.
  </para>
  <para>
   The following terms are used throughout the &repmgr; documentation.
@@ -58,7 +58,7 @@
     <listitem>
      <simpara>
       This is the action which occurs if a primary server fails and a suitable standby
-       is  promoted as the new primary. The <application>repmgrd</application> daemon supports automatic failover
+       is  promoted as the new primary. The &repmgrd; daemon supports automatic failover
       to minimise downtime.
      </simpara>
     </listitem>
@@ -107,7 +107,7 @@
        promotes a (local) standby.
      </para>
      <para>
-        A witness server only needs to be created if <application>repmgrd</application>
+        A witness server only needs to be created if &repmgrd;
        is in use.
      </para>
     </listitem>
@@ -198,7 +198,7 @@
        </listitem>
        <listitem>
          <simpara><literal>repmgr.monitoring_history</literal>: historical standby monitoring information
-            written by <application>repmgrd</application></simpara>
+            written by &repmgrd;</simpara>
        </listitem>
       </itemizedlist>
      </para>
@@ -214,7 +214,7 @@
           name of the server's upstream node</simpara>
        </listitem>
        <listitem>
-          <simpara>repmgr.replication_status: when <application>repmgrd</application>'s monitoring is enabled, shows
+          <simpara>repmgr.replication_status: when &repmgrd;'s monitoring is enabled, shows
            current monitoring status for each standby.</simpara>
        </listitem>
       </itemizedlist>
--- a/doc/promoting-standby.sgml
+++ b/doc/promoting-standby.sgml
@@ -1,13 +1,13 @@
 <chapter id="promoting-standby" xreflabel="Promoting a standby">
+ <title>Promoting a standby server with repmgr</title>
 <indexterm>
   <primary>promoting a standby</primary>
   <seealso>repmgr standby promote</seealso>
 </indexterm>
- <title>Promoting a standby server with repmgr</title>
 <para>
   If a primary server fails or needs to be removed from the replication cluster,
   a new primary server must be designated, to ensure the cluster continues
-   to function correctly. This can be done with <xref linkend="repmgr-standby-promote">,
+   to function correctly. This can be done with <xref linkend="repmgr-standby-promote"/>,
   which promotes the standby on the current server to primary.
 </para>

@@ -31,7 +31,7 @@
  At this point the replication cluster will be in a partially disabled state, with
  both standbys accepting read-only connections while attempting to connect to the
  stopped primary. Note that the &repmgr; metadata table will not yet have been updated;
-  executing <xref linkend="repmgr-cluster-show"> will note the discrepancy:
+  executing <xref linkend="repmgr-cluster-show"/> will note the discrepancy:
  <programlisting>
    $ repmgr -f /etc/repmgr.conf cluster show
     ID | Name  | Role    | Status        | Upstream | Location | Connection string
@@ -60,7 +60,7 @@
    DETAIL: node 2 was successfully promoted to primary</programlisting>
 </para>
 <para>
-  Executing <xref linkend="repmgr-cluster-show"> will show the current state; as there is now an
+  Executing <xref linkend="repmgr-cluster-show"/> will show the current state; as there is now an
  active primary, the previous warning will not be displayed:
  <programlisting>
    $ repmgr -f /etc/repmgr.conf cluster show
@@ -72,8 +72,8 @@
 </para>
 <para>
  However the sole remaining standby (<literal>node3</literal>) is still trying to replicate from the failed
-  primary; <xref linkend="repmgr-standby-follow"> must now be executed to rectify this situation
-  (see <xref linkend="follow-new-primary"> for example).
+  primary; <xref linkend="repmgr-standby-follow"/> must now be executed to rectify this situation
+  (see <xref linkend="follow-new-primary"/> for example).
 </para>
 </chapter>

--- a/doc/quickstart.sgml
+++ b/doc/quickstart.sgml
@@ -1,6 +1,10 @@
 <chapter id="quickstart" xreflabel="Quick-start guide">
 <title>Quick-start guide</title>

+ <indexterm>
+   <primary>quickstart</primary>
+ </indexterm>
+
 <para>
  This section gives a quick introduction to &repmgr;, including setting up a
  sample &repmgr; installation and a basic replication cluster.
@@ -13,7 +17,7 @@
 <note>
   <simpara>
     To upgrade an existing &repmgr; 3.x installation, see section
-     <xref linkend="upgrading-from-repmgr-3">.
+     <xref linkend="upgrading-from-repmgr-3"/>.
   </simpara>
 </note>

@@ -50,7 +54,8 @@
    </para>
    <para>
      If you want <application>repmgr</application> to copy configuration files which are
-      located outside the PostgreSQL data directory, and/or to test <command>switchover</command>
+      located outside the PostgreSQL data directory, and/or to test
+      <command><link linkend="repmgr-standby-switchover">switchover</link></command>
      functionality, you will also need passwordless SSH connections between both servers, and
      <application>rsync</application> should be installed.
    </para>
@@ -63,7 +68,7 @@
    </tip>
 </sect1>

- <sect1 id="quickstart-postgresql-configuration">
+ <sect1 id="quickstart-postgresql-configuration" xreflabel="PostgreSQL configuration">
   <title>PostgreSQL configuration</title>
   <para>
    On the primary server, a PostgreSQL instance must be initialised and running.
@@ -71,13 +76,26 @@
   </para>
   <programlisting>

-    # Enable replication connections; set this figure to at least one more
+    # Enable replication connections; set this value to at least one more
    # than the number of standbys which will connect to this server
-    # (note that repmgr will execute `pg_basebackup` in WAL streaming mode,
-    # which requires two free WAL senders)
+    # (note that repmgr will execute "pg_basebackup" in WAL streaming mode,
+    # which requires two free WAL senders).
+    #
+    # See: https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-WAL-SENDERS

    max_wal_senders = 10

+    # If using replication slots, set this value to at least one more
+    # than the number of standbys which will connect to this server.
+    # Note that repmgr will only make use of replication slots if
+    # "use_replication_slots" is set to "true" in "repmgr.conf".
+    # (If you are not intending to use replication slots, this value
+    # can be set to "0").
+    #
+    # See: https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS
+
+    max_replication_slots = 10
+
    # Ensure WAL files contain enough information to enable read-only queries
    # on the standby.
    #
@@ -85,47 +103,48 @@
    #  PostgreSQL 9.6 and later: one of 'replica' or 'logical'
    #    ('hot_standby' will still be accepted as an alias for 'replica')
    #
-    # See: https://www.postgresql.org/docs/current/static/runtime-config-wal.html#GUC-WAL-LEVEL
+    # See: https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-WAL-LEVEL

    wal_level = 'hot_standby'

    # Enable read-only queries on a standby
    # (Note: this will be ignored on a primary but we recommend including
-    # it anyway)
+    # it anyway, in case the primary later becomes a standby)
+    #
+    # See: https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-HOT-STANDBY

    hot_standby = on

    # Enable WAL file archiving
+    #
+    # See: https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-MODE
+
    archive_mode = on

-    # Set archive command to a script or application that will safely store
-    # you WALs in a secure place. /bin/true is an example of a command that
-    # ignores archiving. Use something more sensible.
-    archive_command = '/bin/true'
-
-    # If you have configured "pg_basebackup_options"
-    # in "repmgr.conf" to include the setting "--xlog-method=fetch" (from
-    # PostgreSQL 10 "--wal-method=fetch"), *and* you have not set
-    # "restore_command" in "repmgr.conf"to fetch WAL files from another
-    # source such as Barman, you'll need to set "wal_keep_segments" to a
-    # high enough value to ensure that all WAL files generated while
-    # the standby is being cloned are retained until the standby starts up.
+    # Set archive command to a dummy command; this can later be changed without
+    # needing to restart the PostgreSQL instance.
    #
-    # wal_keep_segments = 5000
+    # See: https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND
+
+    archive_command = '/bin/true'
   </programlisting>
   <tip>
    <simpara>
      Rather than editing these settings in the default <filename>postgresql.conf</filename>
-     file, create a separate file such as <filename>postgresql.replication.conf</filename> and
+      file, create a separate file such as <filename>postgresql.replication.conf</filename> and
      include it from the end of the main configuration file with:
-     <command>include 'postgresql.replication.conf</command>.
+     <command>include 'postgresql.replication.conf'</command>.
    </simpara>
   </tip>
   <para>
     Additionally, if you are intending to use <application>pg_rewind</application>,
     and the cluster was not initialised using data checksums, you may want to consider enabling
-     <varname>wal_log_hints</varname>; for more details see <xref linkend="repmgr-node-rejoin-pg-rewind">.
+     <varname>wal_log_hints</varname>; for more details see <xref linkend="repmgr-node-rejoin-pg-rewind"/>.
   </para>
+    <para>
+      See also the <link linkend="configuration-postgresql">PostgreSQL configuration</link> section in the
+      <link linkend="configuration">repmgr configuration guide</link>.
+    </para>
 </sect1>

 <sect1 id="quickstart-repmgr-user-database">
@@ -196,11 +215,20 @@
 <sect1 id="quickstart-standby-preparation">
  <title>Preparing the standby</title>
  <para>
-   On the standby, do not create a PostgreSQL instance, but do ensure the destination
+   On the standby, do <emphasis>not</emphasis> create a PostgreSQL instance (i.e.
+   do not execute <application>initdb</application> or any database creation
+   scripts provided by packages), but do ensure the destination
   data directory (and any other directories which you want PostgreSQL to use)
   exist and are owned by the <literal>postgres</literal> system user. Permissions
   must be set to <literal>0700</literal> (<literal>drwx------</literal>).
  </para>
+  <tip>
+    <simpara>
+      &repmgr; will place a copy of the primary's database files in this directory.
+      It will however refuse to run if a PostgreSQL instance has already been
+      created there.
+    </simpara>
+  </tip>
  <para>
   Check the primary database is reachable from the standby using <application>psql</application>:
  </para>
@@ -210,7 +238,7 @@
  <note>
   <para>
    &repmgr; stores connection information as <ulink
-    url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING">libpq
+    url="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING">libpq
    connection strings</ulink> throughout. This documentation refers to them as <literal>conninfo</literal>
    strings; an alternative name is <literal>DSN</literal> (<literal>data source name</literal>).
    We'll use these in place of the <command>-h hostname -d databasename -U username</command> syntax.
@@ -226,7 +254,7 @@
  </para>
  <programlisting>
    node_id=1
-    node_name=node1
+    node_name='node1'
    conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'
    data_directory='/var/lib/postgresql/data'
  </programlisting>
@@ -234,20 +262,47 @@
  <para>
   <filename>repmgr.conf</filename> should not be stored inside the PostgreSQL data directory,
   as it could be overwritten when setting up or reinitialising the PostgreSQL
-   server. See sections <xref linkend="configuration"> and <xref linkend="configuration-file">
+   server. See sections <xref linkend="configuration"/> and <xref linkend="configuration-file"/>
   for further details about <filename>repmgr.conf</filename>.
  </para>
+  <note>
+    <para>
+      &repmgr; only uses <option>pg_bindir</option> when it executes
+      PostgreSQL binaries directly.
+    </para>
+    <para>
+      For user-defined scripts such as <option>promote_command</option> and the
+      various <option>service_*_command</option>s, you <emphasis>must</emphasis>
+      always explicitly provide the full path to the binary or script being
+      executed, even if it is &repmgr; itself.
+    </para>
+    <para>
+      This is because these options can contain user-defined scripts in arbitrary
+      locations, so prepending <option>pg_bindir</option> may break them.
+    </para>
+  </note>
+
  <tip>
   <simpara>
    For Debian-based distributions we recommend explictly setting
-    <literal>pg_bindir</literal> to the directory where <command>pg_ctl</command> and other binaries
+    <option>pg_bindir</option> to the directory where <command>pg_ctl</command> and other binaries
    not in the standard path are located. For PostgreSQL 9.6 this would be <filename>/usr/lib/postgresql/9.6/bin/</filename>.
   </simpara>
  </tip>

+  <tip>
+    <simpara>
+      If your distribution places the &repmgr; binaries in a location other than the
+      PostgreSQL installation directory, specify this with <option>repmgr_bindir</option>
+      to enable &repmgr; to perform operations (e.g.
+      <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>)
+      on other nodes.
+    </simpara>
+  </tip>
+
  <para>
   See the file
-   <ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</>
+   <ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</ulink>
    for details of all available configuration parameters.
  </para>

@@ -296,7 +351,7 @@
    slot_name        |
    config_file      | /etc/repmgr.conf</programlisting>
  <para>
-    Each server in the replication cluster will have its own record. If <application>repmgrd</application>
+    Each server in the replication cluster will have its own record. If &repmgrd;
    is in use, the fields <literal>upstream_node_id</literal>, <literal>active</literal> and
    <literal>type</literal> will be updated when the node's status or role changes.
  </para>
@@ -312,7 +367,7 @@
  </para>
  <programlisting>
    node_id=2
-    node_name=node2
+    node_name='node2'
    conninfo='host=node2 user=repmgr dbname=repmgr connect_timeout=2'
    data_directory='/var/lib/postgresql/data'</programlisting>
  <para>
@@ -404,7 +459,7 @@
  </para>
  <para>
    From PostgreSQL 9.6 you can also use the view
-    <ulink url="https://www.postgresql.org/docs/current/static/monitoring-stats.html#PG-STAT-WAL-RECEIVER-VIEW">
+    <ulink url="https://www.postgresql.org/docs/current/monitoring-stats.html#PG-STAT-WAL-RECEIVER-VIEW">
    <literal>pg_stat_wal_receiver</literal></ulink> to check the replication status from the standby.

   <programlisting>
@@ -422,6 +477,8 @@
    latest_end_lsn        | 0/7000538
    latest_end_time       | 2017-08-28 15:20:56.418735+09
    slot_name             |
+    sender_host           | node1
+    sender_port           | 5432
    conninfo              | user=repmgr dbname=replication host=node1 application_name=node2
   </programlisting>
   Note that the <varname>conninfo</varname> value is that generated in <filename>recovery.conf</filename>
@@ -441,11 +498,12 @@
  <para>
    Check the node is registered by executing <command>repmgr cluster show</command> on the standby:
    <programlisting>
-    $ repmgr -f /etc/repmgr.conf cluster show
-     ID | Name  | Role    | Status    | Upstream | Location | Connection string
-    ----+-------+---------+-----------+----------+----------+--------------------------------------
-     1  | node1 | primary | * running |          | default  | host=node1 dbname=repmgr user=repmgr
-     2  | node2 | standby |   running | node1    | default  | host=node2 dbname=repmgr user=repmgr</programlisting>
+      $ repmgr -f /etc/repmgr.conf cluster show
+
+     ID | Name  | Role    | Status    | Upstream | Location | Priority | Timeline | Connection string
+    ----+-------+---------+-----------+----------+----------+----------+----------+--------------------------------------
+     1  | node1 | primary | * running |          | default  | 100      | 1        | host=node1 dbname=repmgr user=repmgr
+     2  | node2 | standby |   running | node1    | default  | 100      | 1        | host=node2 dbname=repmgr user=repmgr</programlisting>
  </para>
  <para>
   Both nodes are now registered with &repmgr; and the records have been copied to the standby server.
--- a/doc/repmgr-cluster-cleanup.sgml
+++ b/doc/repmgr-cluster-cleanup.sgml
@@ -1,41 +0,0 @@
-<refentry id="repmgr-cluster-cleanup">
-  <indexterm>
-    <primary>repmgr cluster cleanup</primary>
-  </indexterm>
- <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>
--- a/doc/repmgr-cluster-cleanup.xml
+++ b/doc/repmgr-cluster-cleanup.xml
@@ -0,0 +1,77 @@
+<refentry id="repmgr-cluster-cleanup">
+  <indexterm>
+    <primary>repmgr cluster cleanup</primary>
+  </indexterm>
+ <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.
+    </para>
+    <para>
+      By default <emphasis>all</emphasis> data will be removed; Use the <option>-k/--keep-history</option>
+      option to specify the number of days of monitoring history to retain.
+    </para>
+    <para>
+      This command can be executed 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 &repmgrd; is active, and
+      <varname>monitoring_history</varname> is set to <literal>true</literal> in
+      <filename>repmgr.conf</filename>.
+    </para>
+  </refsect1>
+
+  <refsect1 id="repmgr-cluster-cleanup-events">
+    <title>Event notifications</title>
+    <para>
+      A <literal>cluster_cleanup</literal> <link linkend="event-notifications">event notification</link> will be generated.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--node-id</option></term>
+        <listitem>
+          <para>
+            Only delete monitoring records for the specified node.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      For more details see the sections <xref linkend="repmgrd-monitoring"/> and
+      <xref linkend="repmgrd-monitoring-configuration"/>.
+    </para>
+  </refsect1>
+
+</refentry>
--- a/doc/repmgr-cluster-crosscheck.sgml
+++ b/doc/repmgr-cluster-crosscheck.sgml
@@ -16,9 +16,9 @@
  <refsect1>
    <title>Description</title>
    <para>
-      <command>repmgr cluster crosscheck</command> is similar to <xref linkend="repmgr-cluster-matrix">,
+      <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>.
+        <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>
@@ -42,7 +42,7 @@
  <refsect1>
    <title>Exit codes</title>
    <para>
-      Following exit codes can be emitted by <command>repmgr cluster crosscheck</command>:
+      One of the following exit codes will be emitted by <command>repmgr cluster crosscheck</command>:
    </para>
    <variablelist>

@@ -55,12 +55,37 @@
        </listitem>
      </varlistentry>

+      <varlistentry>
+        <term><option>ERR_BAD_SSH (12)</option></term>
+        <listitem>
+          <para>
+            One or more nodes could not be accessed via SSH.
+          </para>
+          <note>
+            <simpara>
+              This only applies to nodes unreachable from the node where
+              this command is executed.
+            </simpara>
+            <simpara>
+              It's also possible that the crosscheck establishes that
+              connections between PostgreSQL on all nodes are functioning,
+              even if SSH access between some nodes is not possible.
+            </simpara>
+          </note>
+        </listitem>
+      </varlistentry>
+
      <varlistentry>
        <term><option>ERR_NODE_STATUS (25)</option></term>
        <listitem>
          <para>
-            One or more nodes could not be reached.
+            PostgreSQL on one or more nodes could not be reached.
          </para>
+          <note>
+            <simpara>
+              This error code overrides <option>ERR_BAD_SSH</option>.
+            </simpara>
+          </note>
        </listitem>
      </varlistentry>

--- a/doc/repmgr-cluster-event.sgml
+++ b/doc/repmgr-cluster-event.sgml
@@ -40,12 +40,12 @@
          <simpara><literal>--node-name</literal>: restrict entries to node with this name</simpara>
        </listitem>
        <listitem>
-          <simpara><literal>--event</literal>: filter specific event (see <xref linkend="event-notifications"> for a full list)</simpara>
+          <simpara><literal>--event</literal>: filter specific event (see <xref linkend="event-notifications"/> for a full list)</simpara>
        </listitem>
      </itemizedlist>
    </para>
    <para>
-      The "Details" column can be omitted by providing <literal>--terse</literal>.
+      The &quot;Details&quot; column can be omitted by providing <literal>--compact</literal>.
    </para>
  </refsect1>

@@ -71,9 +71,9 @@
      <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>
+    ---------+-------+------------------+----+---------------------+-------------------------------------------------------
+     3       | node3 | standby_register | t  | 2019-04-16 10:59:59 | standby registration succeeded; upstream node ID is 1
+     2       | node2 | standby_register | t  | 2019-04-16 10:59:57 | standby registration succeeded; upstream node ID is 1</programlisting>
    </para>
  </refsect1>
 </refentry>
--- a/doc/repmgr-cluster-matrix.sgml
+++ b/doc/repmgr-cluster-matrix.sgml
@@ -93,7 +93,7 @@
   connection from <literal>node3</literal>.
  </para>
  <para>
-    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.
  </para>
  </refsect1>
@@ -102,7 +102,7 @@
  <refsect1>
    <title>Exit codes</title>
    <para>
-      Following exit codes can be emitted by <command>repmgr cluster matrix</command>:
+      One of the following exit codes will be emitted by <command>repmgr cluster matrix</command>:
    </para>
    <variablelist>

@@ -115,12 +115,26 @@
        </listitem>
      </varlistentry>

+      <varlistentry>
+        <term><option>ERR_BAD_SSH (12)</option></term>
+        <listitem>
+          <para>
+            One or more nodes could not be accessed via SSH.
+          </para>
+        </listitem>
+      </varlistentry>
+
      <varlistentry>
        <term><option>ERR_NODE_STATUS (25)</option></term>
        <listitem>
          <para>
-            One or more nodes could not be reached.
+            PostgreSQL on one or more nodes could not be reached.
          </para>
+          <note>
+            <simpara>
+              This error code overrides <option>ERR_BAD_SSH</option>.
+            </simpara>
+          </note>
        </listitem>
      </varlistentry>

--- a/doc/repmgr-cluster-show.sgml
+++ b/doc/repmgr-cluster-show.sgml
@@ -1,152 +0,0 @@
-<refentry id="repmgr-cluster-show">
-  <indexterm>
-    <primary>repmgr cluster show</primary>
-  </indexterm>
-
-  <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
-
-     ID | Name  | Role    | Status    | Upstream | Location | Connection string
-    ----+-------+---------+-----------+----------+----------+-----------------------------------------
-     1  | node1 | primary | * running |          | default  | host=db_node1 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>
-  </para>
-  </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
-    ----+-------+---------+----------------------+----------+----------+-----------------------------------------
-     1  | node1 | primary | ? unreachable        |          | default  | host=db_node1 dbname=repmgr user=repmgr
-     2  | node2 | standby | ! running as primary | node1    | default  | host=db_node2 dbname=repmgr user=repmgr
-     3  | node3 | standby |   running            | node1    | default  | host=db_node3 dbname=repmgr user=repmgr
-
-    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>
-      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>
-
-  <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>
-  </refsect1>
-
-
-  <refsect1>
-    <title>Exit codes</title>
-    <para>
-      Following exit codes can be emitted by <command>repmgr cluster show</command>:
-    </para>
-    <variablelist>
-
-      <varlistentry>
-        <term><option>SUCCESS (0)</option></term>
-        <listitem>
-          <para>
-            No issues were detected.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>ERR_NODE_STATUS (25)</option></term>
-        <listitem>
-          <para>
-            One or more issues were detected.
-          </para>
-        </listitem>
-      </varlistentry>
-
-   </variablelist>
-  </refsect1>
-
-  <refsect1>
-    <title>See also</title>
-    <para>
-     <xref linkend="repmgr-node-status">, <xref linkend="repmgr-node-check">
-    </para>
-  </refsect1>
-
-</refentry>
--- a/doc/repmgr-cluster-show.xml
+++ b/doc/repmgr-cluster-show.xml
@@ -0,0 +1,240 @@
+<refentry id="repmgr-cluster-show">
+  <indexterm>
+    <primary>repmgr cluster show</primary>
+  </indexterm>
+
+  <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>
+	<para>
+	  For PostgreSQL 9.6 and later, the output will also contain the node's current timeline ID.
+	</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
+      better overviews of connections between nodes.
+    </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
+
+     ID | Name  | Role    | Status    | Upstream | Location | Priority | Timeline | Connection string
+    ----+-------+---------+-----------+----------+----------+----------+-----------------------------------------
+     1  | node1 | primary | * running |          | default  | 100      | 1        | host=db_node1 dbname=repmgr user=repmgr
+     2  | node2 | standby |   running | node1    | default  | 100      | 1        | host=db_node2 dbname=repmgr user=repmgr
+     3  | node3 | standby |   running | node1    | default  | 100      | 1        | host=db_node3 dbname=repmgr user=repmgr</programlisting>
+  </para>
+  </refsect1>
+  <refsect1>
+    <title>Notes</title>
+    <para>
+      The column <literal>Role</literal> shows the expected server role according to the
+      &repmgr; metadata.
+	</para>
+	<para>
+	  <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.
+	  If a connection to the node cannot be made, this will be highlighted with a question mark.
+	  Note that the node will only be shown as <literal>? unreachable</literal>
+	  if a connection is not possible at network level; if the PostgreSQL instance on the
+	  node is pingable but not accepting connections, it will be shown as <literal>? running</literal>.
+	</para>
+	<para>
+	  In the following example, executed on <literal>node3</literal>, <literal>node1</literal> is not reachable
+	  at network level and assumed to be down; <literal>node2</literal> has been promoted to primary
+	  (but <literal>node3</literal> is not attached to it, and its metadata has not yet been updated);
+	  <literal>node4</literal> is running but rejecting connections (from <literal>node3</literal> at least).
+      <programlisting>
+	 ID | Name  | Role    | Status               | Upstream | Location | Priority | Connection string
+	----+-------+---------+----------------------+----------+----------+----------+-----------------------------------------
+	 1  | node1 | primary | ? unreachable        |          | default  | 100      | host=db_node1 dbname=repmgr user=repmgr
+	 2  | node2 | standby | ! running as primary | node1    | default  | 100      | host=db_node2 dbname=repmgr user=repmgr
+	 3  | node3 | standby |   running            | node1    | default  | 100      | host=db_node3 dbname=repmgr user=repmgr
+	 4  | node4 | standby | ? running            | node1    | default  | 100      | host=db_node4 dbname=repmgr user=repmgr
+
+	WARNING: following issues were detected
+	  - unable to connect to node "node1" (ID: 1)
+	  - 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
+	  - unable to connect to node "node4" (ID: 4)
+    HINT: execute with --verbose option to see connection error messages</programlisting>
+    </para>
+	<para>
+	  To diagnose connection issues, execute <command>repmgr cluster show</command>
+	  with the <option>--verbose</option> option; this will display the error message
+	  for each failed connection attempt.
+	</para>
+	<tip>
+	  <para>
+		Use <xref linkend="repmgr-cluster-matrix"/> and <xref linkend="repmgr-cluster-crosscheck"/>
+		to diagnose connection issues across the whole replication cluster.
+	  </para>
+	</tip>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--csv</option></term>
+        <listitem>
+	  <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, e.g.:
+	    <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>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--compact</option></term>
+        <listitem>
+          <para>
+			Suppress display of the <literal>conninfo</literal> column.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--terse</option></term>
+        <listitem>
+          <para>
+			Suppress warnings about connection issues.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--verbose</option></term>
+        <listitem>
+          <para>
+			Display the full text of any database connection error messages
+          </para>
+        </listitem>
+      </varlistentry>
+
+	</variablelist>
+
+  </refsect1>
+
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr cluster show</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            No issues were detected.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_BAD_CONFIG (1)</option></term>
+        <listitem>
+          <para>
+            An issue was encountered while attempting to retrieve
+            &repmgr; metadata.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_DB_CONN (6)</option></term>
+        <listitem>
+          <para>
+            &repmgr; was unable to connect to the local PostgreSQL instance.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_NODE_STATUS (25)</option></term>
+        <listitem>
+          <para>
+            One or more issues were detected with the replication configuration,
+            e.g. a node was not in its expected state.
+          </para>
+        </listitem>
+      </varlistentry>
+
+   </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+     <xref linkend="repmgr-node-status"/>, <xref linkend="repmgr-node-check"/>, <xref linkend="repmgr-service-status"/>
+    </para>
+  </refsect1>
+
+</refentry>
--- a/doc/repmgr-daemon-start.xml
+++ b/doc/repmgr-daemon-start.xml
@@ -0,0 +1,208 @@
+<refentry id="repmgr-daemon-start">
+  <indexterm>
+    <primary>repmgr daemon start</primary>
+  </indexterm>
+
+  <indexterm>
+    <primary>repmgrd</primary>
+    <secondary>starting</secondary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr daemon start</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr daemon start</refname>
+    <refpurpose>Start the &repmgrd; daemon on the local node</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      This command starts the &repmgrd; service on the
+      local node.
+    </para>
+    <para>
+      By default, &repmgr; will wait for up to 15 seconds to confirm that &repmgrd;
+      started. This behaviour can be overridden by specifying a diffent value using the <option>--wait</option>
+      option, or disabled altogether with the <option>--no-wait</option> option.
+    </para>
+
+    <important>
+      <para>
+        The <filename>repmgr.conf</filename> parameter <varname>repmgrd_service_start_command</varname>
+        must be set for <command>repmgr daemon start</command> to work; see section
+        <xref linkend="repmgr-daemon-start-configuration"/> for details.
+      </para>
+    </important>
+  </refsect1>
+
+
+
+  <refsect1>
+
+    <title>Options</title>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check prerequisites but don't actually attempt to start &repmgrd;.
+          </para>
+          <para>
+            This action will output the command which would be executed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-w</option></term>
+        <term><option>--wait</option></term>
+        <listitem>
+          <para>
+            Wait for the specified number of seconds to confirm that &repmgrd;
+            started successfully.
+          </para>
+          <para>
+            Note that providing <option>--wait=0</option> is the equivalent of <option>--no-wait</option>.
+          </para>
+
+         </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--no-wait</option></term>
+        <listitem>
+          <para>
+            Don't wait to confirm that &repmgrd;
+            started successfully.
+          </para>
+          <para>
+            This is equivalent to providing <option>--wait=0</option>.
+          </para>
+         </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="repmgr-daemon-start-configuration" xreflabel="repmgr daemon start configuration">
+    <title>Configuration file settings</title>
+    <para>
+     The following parameter in <filename>repmgr.conf</filename> is relevant
+     to <command>repmgr daemon start</command>:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+
+        <term><option>repmgrd_service_start_command</option></term>
+        <listitem>
+          <indexterm>
+            <primary>repmgrd_service_start_command</primary>
+            <secondary>with &quot;repmgr daemon start&quot;</secondary>
+          </indexterm>
+
+          <para>
+            <command>repmgr daemon start</command> will execute the command defined by the
+            <varname>repmgrd_service_start_command</varname> parameter in <filename>repmgr.conf</filename>.
+            This must be set to a shell command which will start &repmgrd;;
+            if &repmgr; was installed from a package, this will be the service command defined by the
+            package. For more details see <link linkend="appendix-packages">Appendix: &repmgr; package details</link>.
+          </para>
+          <important>
+            <para>
+              If &repmgr; was installed from a system package, and you do not configure
+              <varname>repmgrd_service_start_command</varname> to an appropriate service command, this may
+              result in the system becoming confused about the state of the &repmgrd;
+              service; this is particularly the case with <literal>systemd</literal>.
+            </para>
+          </important>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr daemon start</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            The &repmgrd; start command (defined in
+            <varname>repmgrd_service_start_command</varname>) was successfully executed.
+          </para>
+          <para>
+            If the <option>--wait</option> option was provided, &repmgr; will confirm that
+            &repmgrd; has actually started up.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_BAD_CONFIG (1)</option></term>
+        <listitem>
+          <para>
+            <varname>repmgrd_service_start_command</varname> is not defined in
+            <filename>repmgr.conf</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><option>ERR_DB_CONN (6)</option></term>
+        <listitem>
+          <para>
+            &repmgr; was unable to connect to the local PostgreSQL node.
+          </para>
+          <para>
+            PostgreSQL must be running before &repmgrd;
+            can be started. Additionally, unless the <option>--no-wait</option> option was
+            provided, &repmgr; needs to be able to connect to the local PostgreSQL node
+            to determine the state of &repmgrd;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><option>ERR_REPMGRD_SERVICE (27)</option></term>
+        <listitem>
+          <para>
+            The &repmgrd; start command (defined in
+            <varname>repmgrd_service_start_command</varname>) was not successfully executed.
+          </para>
+          <para>
+            This can also mean that &repmgr; was unable to confirm whether &repmgrd;
+            successfully started (unless the <option>--no-wait</option> option was provided).
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      <xref linkend="repmgr-daemon-stop"/>,
+      <xref linkend="repmgrd-daemon"/>,
+      <xref linkend="repmgr-service-status"/>,
+      <xref linkend="repmgr-service-pause"/>,
+      <xref linkend="repmgr-service-unpause"/>
+    </para>
+  </refsect1>
+
+</refentry>
--- a/doc/repmgr-daemon-stop.xml
+++ b/doc/repmgr-daemon-stop.xml
@@ -0,0 +1,205 @@
+<refentry id="repmgr-daemon-stop">
+  <indexterm>
+    <primary>repmgr daemon stop</primary>
+  </indexterm>
+
+  <indexterm>
+    <primary>repmgrd</primary>
+    <secondary>stopping</secondary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr daemon stop</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr daemon stop</refname>
+    <refpurpose>Stop the &repmgrd; daemon on the local node</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      This command stops the &repmgrd; daemon on the
+      local node.
+    </para>
+
+    <para>
+      By default, &repmgr; will wait for up to 15 seconds to confirm that &repmgrd;
+      stopped. This behaviour can be overridden by specifying a diffent value using the <option>--wait</option>
+      option, or disabled altogether with the <option>--no-wait</option> option.
+    </para>
+    <note>
+      <para>
+        If PostgreSQL is not running on the local node, under some circumstances &repmgr; may not
+        be able to confirm if &repmgrd; has actually stopped.
+      </para>
+    </note>
+
+   <important>
+      <para>
+        The <filename>repmgr.conf</filename> parameter <varname>repmgrd_service_stop_command</varname>
+        must be set for <command>repmgr daemon stop</command> to work; see section
+        <xref linkend="repmgr-daemon-stop-configuration"/> for details.
+      </para>
+    </important>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration</title>
+    <para>
+      <command>repmgr daemon stop</command> will execute the command defined by the
+      <varname>repmgrd_service_stop_command</varname> parameter in <filename>repmgr.conf</filename>.
+      This must be set to a shell command which will stop &repmgrd;;
+      if &repmgr; was installed from a package, this will be the service command defined by the
+      package. For more details see <link linkend="appendix-packages">Appendix: &repmgr; package details</link>.
+    </para>
+
+    <important>
+      <para>
+        If &repmgr; was installed from a system package, and you do not configure
+        <varname>repmgrd_service_stop_command</varname> to an appropriate service command, this may
+        result in the system becoming confused about the state of the &repmgrd;
+        service; this is particularly the case with <literal>systemd</literal>.
+      </para>
+    </important>
+
+  </refsect1>
+
+  <refsect1>
+
+    <title>Options</title>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check prerequisites but don't actually attempt to stop &repmgrd;.
+          </para>
+          <para>
+            This action will output the command which would be executed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-w</option></term>
+        <term><option>--wait</option></term>
+        <listitem>
+          <para>
+            Wait for the specified number of seconds to confirm that &repmgrd;
+            stopped successfully.
+          </para>
+          <para>
+            Note that providing <option>--wait=0</option> is the equivalent of <option>--no-wait</option>.
+          </para>
+
+         </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--no-wait</option></term>
+        <listitem>
+          <para>
+            Don't wait to confirm that &repmgrd;
+            stopped successfully.
+          </para>
+          <para>
+            This is equivalent to providing <option>--wait=0</option>.
+          </para>
+         </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="repmgr-daemon-stop-configuration" xreflabel="repmgr daemon stop configuration">
+    <title>Configuration file settings</title>
+    <para>
+     The following parameter in <filename>repmgr.conf</filename> is relevant
+     to <command>repmgr daemon stop</command>:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+
+        <term><option>repmgrd_service_stop_command</option></term>
+        <listitem>
+          <indexterm>
+            <primary>repmgrd_service_stop_command</primary>
+          <secondary>with &quot;repmgr daemon stop&quot;</secondary>
+          </indexterm>
+
+          <para>
+            <command>repmgr daemon stop</command> will execute the command defined by the
+            <varname>repmgrd_service_stop_command</varname> parameter in <filename>repmgr.conf</filename>.
+            This must be set to a shell command which will stop &repmgrd;;
+            if &repmgr; was installed from a package, this will be the service command defined by the
+            package. For more details see <link linkend="appendix-packages">Appendix: &repmgr; package details</link>.
+          </para>
+          <important>
+            <para>
+              If &repmgr; was installed from a system package, and you do not configure
+              <varname>repmgrd_service_stop_command</varname> to an appropriate service command, this may
+              result in the system becoming confused about the state of the &repmgrd;
+              service; this is particularly the case with <literal>systemd</literal>.
+            </para>
+          </important>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr daemon stop</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            &repmgrd; could be stopped.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_BAD_CONFIG (1)</option></term>
+        <listitem>
+          <para>
+            <varname>repmgrd_service_stop_command</varname> is not defined in
+            <filename>repmgr.conf</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_REPMGRD_SERVICE (27)</option></term>
+        <listitem>
+          <para>
+            &repmgrd; could not be stopped.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      <xref linkend="repmgr-daemon-start"/>,
+      <xref linkend="repmgrd-daemon"/>,
+      <xref linkend="repmgr-service-status"/>,
+      <xref linkend="repmgr-service-pause"/>,
+      <xref linkend="repmgr-service-unpause"/>
+    </para>
+  </refsect1>
+
+</refentry>
--- a/doc/repmgr-node-check.sgml
+++ b/doc/repmgr-node-check.sgml
@@ -18,6 +18,14 @@
      Performs some health checks on a node from a replication perspective.
      This command must be run on the local node.
    </para>
+	<note>
+	  <para>
+		Currently &repmgr; performs health checks on physical replication
+		slots only, with the aim of warning about streaming replication standbys which
+		have become detached and the associated risk of uncontrolled WAL file
+		growth.
+	  </para>
+	</note>
  </refsect1>

  <refsect1>
@@ -30,7 +38,8 @@
            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>
+            Replication slots: OK (node has no physical replication slots)
+            Missing replication slots: OK (node has no missing physical replication slots)</programlisting>
    </para>
  </refsect1>
  <refsect1>
@@ -43,7 +52,7 @@
        OK (node is primary)</programlisting>
    </para>
    <para>
-   Parameters for individual checks are as follows:
+	  Parameters for individual checks are as follows:
    <itemizedlist spacing="compact" mark="bullet">

     <listitem>
@@ -75,16 +84,26 @@

     <listitem>
      <simpara>
-        <literal>--slots</literal>: checks there are no inactive replication slots
+        <literal>--slots</literal>: checks there are no inactive physical replication slots
      </simpara>
     </listitem>

     <listitem>
      <simpara>
-        <literal>--missing-slots</literal>: checks there are no missing replication slots
+        <literal>--missing-slots</literal>: checks there are no missing physical replication slots
      </simpara>
     </listitem>

+     <listitem>
+      <simpara>
+        <literal>--data-directory-config</literal>: checks the data directory configured in
+        <filename>repmgr.conf</filename> matches the actual data directory.
+        This check is not directly related to replication, but is useful to verify &repmgr;
+        is correctly configured.
+      </simpara>
+     </listitem>
+
+
    </itemizedlist>
  </para>
  </refsect1>
@@ -104,6 +123,7 @@
        <listitem>
          <simpara>
            <literal>--nagios</literal>: generate output in a Nagios-compatible format
+            (for individual checks only)
          </simpara>
        </listitem>
      </itemizedlist>
@@ -150,9 +170,10 @@


    <para>
-      Following exit codes can be emitted by <command>repmgr status check</command>
+      One of the following exit codes will be emitted by <command>repmgr status check</command>
      if no individual check was specified.
    </para>
+
    <variablelist>

      <varlistentry>
@@ -174,6 +195,7 @@
      </varlistentry>

   </variablelist>
+
  </refsect1>


@@ -181,7 +203,7 @@
  <refsect1>
    <title>See also</title>
    <para>
-     <xref linkend="repmgr-node-status">, <xref linkend="repmgr-cluster-show">
+     <xref linkend="repmgr-node-status"/>, <xref linkend="repmgr-cluster-show"/>
    </para>
  </refsect1>

--- a/doc/repmgr-node-rejoin.sgml
+++ b/doc/repmgr-node-rejoin.sgml
@@ -1,250 +0,0 @@
-<refentry id="repmgr-node-rejoin">
-
-  <indexterm>
-    <primary>repmgr node rejoin</primary>
-  </indexterm>
-
-  <refmeta>
-    <refentrytitle>repmgr node rejoin</refentrytitle>
-  </refmeta>
-
-  <refnamediv>
-    <refname>repmgr node rejoin</refname>
-    <refpurpose>rejoin a dormant (stopped) node to the replication cluster</refpurpose>
-  </refnamediv>
-
-  <refsect1>
-    <title>Description</title>
-    <para>
-      Enables a dormant (stopped) node to be rejoined to the replication cluster.
-    </para>
-    <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>
-
-    <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>
-      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>
-  </refsect1>
-
-  <refsect1>
-
-    <title>Options</title>
-    <variablelist>
-
-      <varlistentry>
-        <term><option>--dry-run</option></term>
-        <listitem>
-          <para>
-            Check prerequisites but don't actually execute the rejoin.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--force-rewind[=/path/to/pg_rewind]</option></term>
-        <listitem>
-          <para>
-            Execute <application>pg_rewind</application> if necessary.
-          </para>
-          <para>
-            It is only necessary to provide the <application>pg_rewind</application>
-            if using PostgreSQL 9.3 or 9.4, and <application>pg_rewind</application>
-            is not installed in the PostgreSQL <filename>bin</filename> directory.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--config-files</option></term>
-        <listitem>
-          <para>
-            comma-separated list of configuration files to retain after
-            executing <application>pg_rewind</application>.
-          </para>
-          <para>
-            Currently <application>pg_rewind</application> will overwrite
-            the local node's configuration files with the files from the source node,
-            so it's advisable to use this option to ensure they are kept.
-          </para>
-        </listitem>
-      </varlistentry>
-
-
-      <varlistentry>
-        <term><option>--config-archive-dir</option></term>
-        <listitem>
-          <para>
-            Directory to temporarily store configuration files specified with
-            <option>--config-files</option>; default: <filename>/tmp</filename>.
-          </para>
-        </listitem>
-      </varlistentry>
-
-
-      <varlistentry>
-        <term><option>-W/--no-wait</option></term>
-        <listitem>
-          <para>
-            Don't wait for the node to rejoin cluster.
-          </para>
-          <para>
-            If this option is supplied, &repmgr; will restart the node but
-            not wait for it to connect to the primary.
-          </para>
-        </listitem>
-      </varlistentry>
-
-    </variablelist>
-  </refsect1>
- <refsect1>
-    <title>Configuration file settings</title>
-
-    <para>
-      <itemizedlist spacing="compact" mark="bullet">
-       <listitem>
-         <simpara>
-           <literal>node_rejoin_timeout</literal>:
-		   the maximum length of time (in seconds) to wait for
-		   the node to reconnect to the replication cluster (defaults to
-		   the value set in <literal>standby_reconnect_timeout</literal>,
-		   60 seconds).
-		 </simpara>
-	   </listitem>
-	  </itemizedlist>
-	</para>
-
- </refsect1>
-  <refsect1>
-    <title>Event notifications</title>
-    <para>
-      A <literal>node_rejoin</literal> <link linkend="event-notifications">event notification</link> will be generated.
-    </para>
-  </refsect1>
-
-  <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" xreflabel="Using pg_rewind">
-
-   <indexterm>
-      <primary>pg_rewind</primary>
-      <secondary>using with "repmgr node rejoin"</secondary>
-    </indexterm>
-
-    <title>Using <command>pg_rewind</command></title>
-    <para>
-      <command>repmgr node rejoin</command> can optionally use <command>pg_rewind</command> to re-integrate a
-      node which has diverged from the rest of the cluster, typically a failed primary.
-      <command>pg_rewind</command> is available in PostgreSQL 9.5 and later as part of the core distribution,
-      and can be installed from external sources for PostgreSQL 9.3 and 9.4.
-    </para>
-    <note>
-      <para>
-        <command>pg_rewind</command> <emphasis>requires</emphasis> that either
-        <varname>wal_log_hints</varname> is enabled, or that
-        data checksums were enabled when the cluster was initialized. See the
-        <ulink url="https://www.postgresql.org/docs/current/static/app-pgrewind.html"><command>pg_rewind</command> documentation</ulink> for details.
-      </para>
-    </note>
-
-    <para>
-      To have <command>repmgr node rejoin</command> use <command>pg_rewind</command> if required,
-      pass the command line option <literal>--force-rewind</literal>, which will tell &repmgr;
-      to execute <command>pg_rewind</command> to ensure the node can be rejoined successfully.
-    </para>
-
-    <para>
-      Be aware that if <command>pg_rewind</command> is executed and actually performs a
-      rewind operation, any configuration files in the PostgreSQL data directory will be
-      overwritten with those from the source server.
-    </para>
-    <para>
-      To prevent this happening, provide a comma-separated list of files to retain
-      using the <literal>--config-file</literal> command line option; the specified files
-      will be archived in a temporary directory (whose parent directory can be specified with
-      <literal>--config-archive-dir</literal>) and restored once the rewind operation is
-      complete.
-    </para>
-
-    <para>
-      Example, first using <literal>--dry-run</literal>, then actually executing the
-      <literal>node rejoin command</literal>.
-    <programlisting>
-    $ repmgr node rejoin -f /etc/repmgr.conf -d 'host=node1 dbname=repmgr user=repmgr' \
-         --force-rewind --config-files=postgresql.local.conf,postgresql.conf --verbose --dry-run
-    NOTICE: using provided configuration file "/etc/repmgr.conf"
-    INFO: prerequisites for using pg_rewind are met
-    INFO: file "postgresql.local.conf" would be copied to "/tmp/repmgr-config-archive-node1/postgresql.local.conf"
-    INFO: file "postgresql.conf" would be copied to "/tmp/repmgr-config-archive-node1/postgresql.local.conf"
-    INFO: 2 files would have been copied to "/tmp/repmgr-config-archive-node1"
-    INFO: directory "/tmp/repmgr-config-archive-node1" deleted
-    INFO: pg_rewind would now be executed
-    DETAIL: pg_rewind command is:
-      pg_rewind -D '/var/lib/postgresql/data' --source-server='host=node1 dbname=repmgr user=repmgr'</programlisting>
-    <programlisting>
-    $ repmgr node rejoin -f /etc/repmgr.conf -d 'host=node1 dbname=repmgr user=repmgr' \
-         --force-rewind --config-files=postgresql.local.conf,postgresql.conf --verbose
-    NOTICE: using provided configuration file "/etc/repmgr.conf"
-    INFO: prerequisites for using pg_rewind are met
-    INFO: 2 files copied to "/tmp/repmgr-config-archive-node1"
-    NOTICE: executing pg_rewind
-    NOTICE: 2 files copied to /var/lib/pgsql/data
-    INFO: directory "/tmp/repmgr-config-archive-node1" deleted
-    INFO: deleting "recovery.done"
-    INFO: setting node 1's primary to node 2
-    NOTICE: starting server using "pg_ctl-l /var/log/postgres/startup.log -w -D '/var/lib/pgsql/data' start"
-    waiting for server to start.... done
-    server started
-    NOTICE: NODE REJOIN successful
-    DETAIL: node 1 is now attached to node 2</programlisting>
-    </para>
-
-  </refsect1>
-
-  <refsect1>
-    <title>See also</title>
-    <para>
-     <xref linkend="repmgr-standby-follow">
-    </para>
-  </refsect1>
-</refentry>
--- a/doc/repmgr-node-rejoin.xml
+++ b/doc/repmgr-node-rejoin.xml
@@ -0,0 +1,389 @@
+<refentry id="repmgr-node-rejoin">
+
+  <indexterm>
+    <primary>repmgr node rejoin</primary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr node rejoin</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr node rejoin</refname>
+    <refpurpose>rejoin a dormant (stopped) node to the replication cluster</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      Enables a dormant (stopped) node to be rejoined to the replication cluster.
+    </para>
+    <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>
+
+    <tip>
+      <para>
+        If the node is running and needs to be attached to the current primary, use
+        <xref linkend="repmgr-standby-follow"/>.
+      </para>
+      <para>
+        Note <xref linkend="repmgr-standby-follow"/> can only be used for standbys which have not diverged
+        from the rest of the cluster.
+      </para>
+    </tip>
+  </refsect1>
+
+
+  <refsect1>
+    <title>Usage</title>
+
+    <para>
+      <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>
+  </refsect1>
+
+  <refsect1>
+
+    <title>Options</title>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check prerequisites but don't actually execute the rejoin.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--force-rewind[=/path/to/pg_rewind]</option></term>
+        <listitem>
+          <para>
+            Execute <application>pg_rewind</application>.
+          </para>
+          <para>
+            It is only necessary to provide the <application>pg_rewind</application> path
+            if using PostgreSQL 9.3 or 9.4, and <application>pg_rewind</application>
+            is not installed in the PostgreSQL <filename>bin</filename> directory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--config-files</option></term>
+        <listitem>
+          <para>
+            comma-separated list of configuration files to retain after
+            executing <application>pg_rewind</application>.
+          </para>
+          <para>
+            Currently <application>pg_rewind</application> will overwrite
+            the local node's configuration files with the files from the source node,
+            so it's advisable to use this option to ensure they are kept.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><option>--config-archive-dir</option></term>
+        <listitem>
+          <para>
+            Directory to temporarily store configuration files specified with
+            <option>--config-files</option>; default: <filename>/tmp</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><option>-W/--no-wait</option></term>
+        <listitem>
+          <para>
+            Don't wait for the node to rejoin cluster.
+          </para>
+          <para>
+            If this option is supplied, &repmgr; will restart the node but
+            not wait for it to connect to the primary.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration file settings</title>
+
+    <para>
+      <itemizedlist spacing="compact" mark="bullet">
+       <listitem>
+         <simpara>
+           <literal>node_rejoin_timeout</literal>:
+		   the maximum length of time (in seconds) to wait for
+		   the node to reconnect to the replication cluster (defaults to
+		   the value set in <literal>standby_reconnect_timeout</literal>,
+		   60 seconds).
+		 </simpara>
+         <simpara>
+           Note that <literal>standby_reconnect_timeout</literal> must be
+           set to a value equal to or greater than
+           <literal>node_rejoin_timeout</literal>.
+         </simpara>
+	   </listitem>
+	  </itemizedlist>
+	</para>
+
+  </refsect1>
+
+  <refsect1 id="repmgr-node-rejoin-events">
+    <title>Event notifications</title>
+    <para>
+      A <literal>node_rejoin</literal> <link linkend="event-notifications">event notification</link> will be generated.
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr node rejoin</command>:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            The node rejoin succeeded; or if <option>--dry-run</option> was provided,
+            no issues were detected which would prevent the node rejoin.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_BAD_CONFIG (1)</option></term>
+        <listitem>
+          <para>
+            A configuration issue was detected which prevented &repmgr; from
+            continuing with the node rejoin.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_NO_RESTART (4)</option></term>
+        <listitem>
+          <para>
+            The node could not be restarted.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_REJOIN_FAIL (24)</option></term>
+        <listitem>
+          <para>
+            The node rejoin operation failed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+  <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>
+    <para>
+      &repmgr; will attempt to verify whether the node can rejoin as-is, or whether
+      <command>pg_rewind</command> must be used (see following section).
+    </para>
+  </refsect1>
+
+  <refsect1 id="repmgr-node-rejoin-pg-rewind" xreflabel="Using pg_rewind">
+
+   <title>Using <command>pg_rewind</command></title>
+
+   <indexterm>
+      <primary>pg_rewind</primary>
+      <secondary>using with "repmgr node rejoin"</secondary>
+    </indexterm>
+
+    <para>
+      <command>repmgr node rejoin</command> can optionally use <command>pg_rewind</command> to re-integrate a
+      node which has diverged from the rest of the cluster, typically a failed primary.
+      <command>pg_rewind</command> is available in PostgreSQL 9.5 and later as part of the core distribution,
+      and can be installed from external sources for PostgreSQL 9.3 and 9.4.
+    </para>
+    <note>
+      <para>
+        <command>pg_rewind</command> <emphasis>requires</emphasis> that either
+        <varname>wal_log_hints</varname> is enabled, or that
+        data checksums were enabled when the cluster was initialized. See the
+        <ulink url="https://www.postgresql.org/docs/current/app-pgrewind.html"><command>pg_rewind</command> documentation</ulink> for details.
+      </para>
+    </note>
+
+    <para>
+      We strongly recommend familiarizing yourself with <command>pg_rewind</command> before attempting
+      to use it with &repmgr;, as while it is an extremely useful tool, it is <emphasis>not</emphasis>
+      a &quot;magic bullet&quot; which can resolve all problematic replication situations.
+    </para>
+
+    <para>
+      A typical use-case for <command>pg_rewind</command> is when a scenario like the following
+      is encountered:
+      <programlisting>
+    $ repmgr node rejoin -f /etc/repmgr.conf -d 'host=node3 dbname=repmgr user=repmgr' \
+        --force-rewind --config-files=postgresql.local.conf,postgresql.conf --verbose --dry-run
+    INFO: replication connection to the rejoin target node was successful
+    INFO: local and rejoin target system identifiers match
+    DETAIL: system identifier is 6652184002263212600
+    ERROR: this node cannot attach to rejoin target node 3
+    DETAIL: rejoin target server's timeline 2 forked off current database system timeline 1 before current recovery point 0/610D710
+    HINT: use --force-rewind to execute pg_rewind</programlisting>
+
+      Here, <literal>node3</literal> was promoted to a primary while the local node was
+      still attached to the previous primary; this can potentially happen during e.g. a
+      network split. <command>pg_rewind</command> can re-sync the local node with <literal>node3</literal>,
+      removing the need for a full reclone.
+    </para>
+
+    <para>
+      To have <command>repmgr node rejoin</command> use <command>pg_rewind</command>,
+      pass the command line option <literal>--force-rewind</literal>, which will tell &repmgr;
+      to execute <command>pg_rewind</command> to ensure the node can be rejoined successfully.
+    </para>
+
+    <important>
+      <para>
+        Be aware that if <command>pg_rewind</command> is executed and actually performs a
+        rewind operation, any configuration files in the PostgreSQL data directory will be
+        overwritten with those from the source server.
+      </para>
+      <para>
+        To prevent this happening, provide a comma-separated list of files to retain
+        using the <literal>--config-file</literal> command line option; the specified files
+        will be archived in a temporary directory (whose parent directory can be specified with
+        <literal>--config-archive-dir</literal>) and restored once the rewind operation is
+        complete.
+      </para>
+    </important>
+
+    <para>
+      Example, first using <literal>--dry-run</literal>, then actually executing the
+      <literal>node rejoin command</literal>.
+    <programlisting>
+    $ repmgr node rejoin -f /etc/repmgr.conf -d 'host=node3 dbname=repmgr user=repmgr' \
+        --config-files=postgresql.local.conf,postgresql.conf --verbose --force-rewind --dry-run
+    INFO: replication connection to the rejoin target node was successful
+    INFO: local and rejoin target system identifiers match
+    DETAIL: system identifier is 6652460429293670710
+    NOTICE: pg_rewind execution required for this node to attach to rejoin target node 3
+    DETAIL: rejoin target server's timeline 2 forked off current database system timeline 1 before current recovery point 0/610D710
+    INFO: prerequisites for using pg_rewind are met
+    INFO: file "postgresql.local.conf" would be copied to "/tmp/repmgr-config-archive-node2/postgresql.local.conf"
+    INFO: file "postgresql.replication-setup.conf" would be copied to "/tmp/repmgr-config-archive-node2/postgresql.replication-setup.conf"
+    INFO: pg_rewind would now be executed
+    DETAIL: pg_rewind command is:
+      pg_rewind -D '/var/lib/postgresql/data' --source-server='host=node3 dbname=repmgr user=repmgr'
+    INFO: prerequisites for executing NODE REJOIN are met</programlisting>
+
+    <note>
+      <para>
+        If <option>--force-rewind</option> is used with the <option>--dry-run</option> option,
+        this checks the prerequisites for using <application>pg_rewind</application>, but is
+        not an absolute guarantee that actually executing <application>pg_rewind</application>
+        will succeed. See also section <xref linkend="repmgr-node-rejoin-caveats"/> below.
+      </para>
+
+    </note>
+
+    <programlisting>
+    $ repmgr node rejoin -f /etc/repmgr.conf -d 'host=node3 dbname=repmgr user=repmgr' \
+        --config-files=postgresql.local.conf,postgresql.conf --verbose --force-rewind
+    NOTICE: pg_rewind execution required for this node to attach to rejoin target node 3
+    DETAIL: rejoin target server's timeline 2 forked off current database system timeline 1 before current recovery point 0/610D710
+    NOTICE: executing pg_rewind
+    DETAIL: pg_rewind command is "pg_rewind -D '/var/lib/postgresql/data' --source-server='host=node3 dbname=repmgr user=repmgr'"
+    NOTICE: 2 files copied to /var/lib/postgresql/data
+    NOTICE: setting node 2's upstream to node 3
+    NOTICE: starting server using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/pgsql/data' start"
+    NOTICE: NODE REJOIN successful
+    DETAIL: node 2 is now attached to node 3</programlisting>
+    </para>
+
+  </refsect1>
+
+  <refsect1 id="repmgr-node-rejoin-caveats" xreflabel="Caveats">
+
+   <title>Caveats when using <command>repmgr node rejoin</command></title>
+
+   <indexterm>
+     <primary>repmgr node rejoin</primary>
+     <secondary>caveats</secondary>
+   </indexterm>
+
+   <para>
+     <command>repmgr node rejoin</command> attempts to determine whether it will succeed by
+     comparing the timelines and relative WAL positions of the local node (rejoin candidate) and primary
+     (rejoin target). This is particularly important if planning to use <application>pg_rewind</application>,
+     which currently (as of PostgreSQL 12) may appear to succeed (or indicate there is no action
+     needed) but potentially allow an impossible action, such as trying to rejoin a standby to a
+     primary which is behind the standby. &repmgr; will prevent this situation from occurring.
+   </para>
+   <para>
+     Currently it is <emphasis>not</emphasis> possible to detect a situation where the rejoin target
+     is a standby which has been &quot;promoted&quot; by removing <filename>recovery.conf</filename>
+     (PostgreSQL 12 and later: <filename>standby.signal</filename>) and restarting it.
+     In this case there will be no information about the point the rejoin target diverged
+     from the current standby; the rejoin operation will fail and
+     the current standby's PostgreSQL log will contain entries with the text
+     &quot;<literal>record with incorrect prev-link</literal>&quot;.
+   </para>
+   <para>
+     We strongly recommend running <command>repmgr node rejoin</command> with the
+     <option>--dry-run</option> option first. Additionally it might be a good idea
+     to execute the <application>pg_rewind</application> command displayed by
+     &repmgr; with the <application>pg_rewind</application> <option>--dry-run</option>
+     option. Note that <application>pg_rewind</application> does not indicate that it
+     is running in <option>--dry-run</option> mode.
+   </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+     <xref linkend="repmgr-standby-follow"/>
+    </para>
+  </refsect1>
+</refentry>
--- a/doc/repmgr-node-service.xml
+++ b/doc/repmgr-node-service.xml
@@ -0,0 +1,151 @@
+<refentry id="repmgr-node-service">
+  <indexterm>
+    <primary>repmgr node service</primary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr node service</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr node service</refname>
+    <refpurpose>show or execute the system service command to stop/start/restart/reload/promote a node</refpurpose>
+  </refnamediv>
+
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      Shows or executes the system service command to stop/start/restart/reload a node.
+    </para>
+    <para>
+      This command is mainly meant for internal &repmgr; usage, but is useful for
+      confirming the command configuration.
+    </para>
+  </refsect1>
+
+  <refsect1>
+
+    <title>Options</title>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Log the steps which would be taken, including displaying the command which would be executed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--action</option></term>
+        <listitem>
+          <para>
+            The action to perform. One of <literal>start</literal>, <literal>stop</literal>,
+            <literal>restart</literal>, <literal>reload</literal> or <literal>promote</literal>.
+          </para>
+          <para>
+            If the parameter <option>--list-actions</option> is provided together with
+            <option>--action</option>, the command which would be executed will be printed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><option>--list-actions</option></term>
+        <listitem>
+          <para>
+            List all configured commands.
+          </para>
+          <para>
+            If the parameter <option>--action</option> is provided together with
+            <option>--list-actions</option>, the command which would be executed for that
+            particular action will be printed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+     <varlistentry>
+        <term><option>--checkpoint</option></term>
+        <listitem>
+          <para>
+            Issue a <command>CHECKPOINT</command> before stopping or restarting the node.
+          </para>
+        </listitem>
+     </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr node service</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            No issues were detected.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_LOCAL_COMMAND (5)</option></term>
+        <listitem>
+          <para>
+            Execution of the system service command failed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+   </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+    <para>
+      See what action would be taken for a restart:
+      <programlisting>
+[postgres@node1 ~]$ repmgr -f /etc/repmgr/12/repmgr.conf node service --action=restart --checkpoint --dry-run
+INFO: a CHECKPOINT would be issued here
+INFO: would execute server command "sudo service postgresql-12 restart"</programlisting>
+    </para>
+
+    <para>
+      Restart the PostgreSQL instance:
+      <programlisting>
+[postgres@node1 ~]$ repmgr -f /etc/repmgr/12/repmgr.conf node service --action=restart --checkpoint
+NOTICE: issuing CHECKPOINT
+DETAIL: executing server command "sudo service postgresql-12 restart"
+Redirecting to /bin/systemctl restart postgresql-12.service</programlisting>
+    </para>
+
+    <para>
+      List all commands:
+      <programlisting>
+[postgres@node1 ~]$ repmgr -f /etc/repmgr/12/repmgr.conf node service --list-actions
+Following commands would be executed for each action:
+
+    start: "sudo service postgresql-12 start"
+     stop: "sudo service postgresql-12 stop"
+  restart: "sudo service postgresql-12 restart"
+   reload: "sudo service postgresql-12 reload"
+  promote: "/usr/pgsql-12/bin/pg_ctl  -w -D '/var/lib/pgsql/12/data' promote"</programlisting>
+    </para>
+
+    <para>
+      List a single command:
+      <programlisting>
+[postgres@node1 ~]$ repmgr -f /etc/repmgr/12/repmgr.conf node service --list-actions --action=promote
+/usr/pgsql-12/bin/pg_ctl  -w -D '/var/lib/pgsql/12/data' promote      </programlisting>
+    </para>
+  </refsect1>
+</refentry>
--- a/doc/repmgr-node-status.sgml
+++ b/doc/repmgr-node-status.sgml
@@ -55,7 +55,7 @@
  <refsect1>
    <title>Exit codes</title>
    <para>
-      Following exit codes can be emitted by <command>repmgr node status</command>:
+      One of the following exit codes will be emitted by <command>repmgr node status</command>:
    </para>
    <variablelist>

@@ -84,7 +84,7 @@
  <refsect1>
    <title>See also</title>
    <para>
-      See <xref linkend="repmgr-node-check"> to diagnose issues and <xref linkend="repmgr-cluster-show">
+      See <xref linkend="repmgr-node-check"/> to diagnose issues and <xref linkend="repmgr-cluster-show"/>
      for an overview of all nodes in the cluster.
    </para>
  </refsect1>
--- a/doc/repmgr-primary-register.sgml
+++ b/doc/repmgr-primary-register.sgml
@@ -21,6 +21,15 @@
      installing the &repmgr; extension. This command needs to be executed before any
      standby nodes are registered.
    </para>
+
+    <note>
+      <para>
+        It's possibly to install the &repmgr; extension manually before executing
+        <command>repmgr primary register</command>; in this case &repmgr; will
+        detect the presence of the extension and skip that step.
+      </para>
+    </note>
+
  </refsect1>

  <refsect1>
@@ -29,23 +38,25 @@
      Execute with the <option>--dry-run</option> option to check what would happen without
      actually registering the primary.
    </para>
-    <para>
+
+    <note>
+      <para>
+        If providing the configuration file location with <option>-f/--config-file</option>,
+        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>
+
+	<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 <option>-f/--config-file</option>,
-      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>
@@ -75,10 +86,18 @@
  </refsect1>


-  <refsect1>
+  <refsect1 id="repmgr-primary-register-events">
    <title>Event notifications</title>
    <para>
-      A <literal>primary_register</literal> <link linkend="event-notifications">event notification</link> will be generated.
+      Following <link linkend="event-notifications">event notifications</link> will be generated:
+      <itemizedlist spacing="compact" mark="bullet">
+        <listitem>
+          <simpara><literal>cluster_created</literal></simpara>
+        </listitem>
+        <listitem>
+          <simpara><literal>primary_register</literal></simpara>
+        </listitem>
+      </itemizedlist>
    </para>
  </refsect1>

--- a/doc/repmgr-primary-unregister.sgml
+++ b/doc/repmgr-primary-unregister.sgml
@@ -64,7 +64,7 @@

  </refsect1>

-  <refsect1>
+  <refsect1 id="repmgr-primary-unregister-events">
    <title>Event notifications</title>
    <para>
      A <literal>primary_unregister</literal> <link linkend="event-notifications">event notification</link> will be generated.
--- a/doc/repmgr-service-pause.xml
+++ b/doc/repmgr-service-pause.xml
@@ -0,0 +1,127 @@
+<refentry id="repmgr-service-pause">
+  <indexterm>
+    <primary>repmgr service pause</primary>
+  </indexterm>
+
+  <indexterm>
+    <primary>repmgrd</primary>
+    <secondary>pausing</secondary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr service pause</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr service pause</refname>
+    <refpurpose>Instruct all &repmgrd; instances in the replication cluster to pause failover operations</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      This command can be run on any active node in the replication cluster to instruct all
+      running &repmgrd; instances to &quot;pause&quot; themselves, i.e. take no
+      action (such as promoting themselves or following a new primary) if a failover event is detected.
+    </para>
+    <para>
+      This functionality is useful for performing maintenance operations, such as switchovers
+      or upgrades, which might otherwise trigger a failover if &repmgrd;
+      is running normally.
+    </para>
+    <note>
+      <para>
+        It's important to wait a few seconds after restarting PostgreSQL on any node before running
+        <command>repmgr service pause</command>, as the &repmgrd; instance
+        on the restarted node will take a second or two before it has updated its status.
+      </para>
+    </note>
+    <para>
+      <xref linkend="repmgr-service-unpause"/> will instruct all previously paused &repmgrd;
+      instances to resume normal failover operation.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Prerequisites</title>
+    <para>
+      PostgreSQL must be accessible on all nodes (using the <varname>conninfo</varname> string shown by
+      <link linkend="repmgr-cluster-show"><command>repmgr cluster show</command></link>)
+      from the node where <command>repmgr service pause</command> is executed.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
+    <para>
+      <command>repmgr service pause</command> can be executed on any active node in the
+      replication cluster. A valid <filename>repmgr.conf</filename> file is required.
+      It will have no effect on previously paused nodes.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
+    <para>
+    <programlisting>
+$ repmgr -f /etc/repmgr.conf service pause
+NOTICE: node 1 (node1) paused
+NOTICE: node 2 (node2) paused
+NOTICE: node 3 (node3) paused</programlisting>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check if nodes are reachable but don't pause &repmgrd;.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr service unpause</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            &repmgrd; could be paused on all nodes.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_REPMGRD_PAUSE (26)</option></term>
+        <listitem>
+          <para>
+           &repmgrd; could not be paused on one or mode nodes.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      <xref linkend="repmgr-service-unpause"/>,
+      <xref linkend="repmgr-service-status"/>,
+      <xref linkend="repmgrd-pausing"/>,
+      <xref linkend="repmgr-daemon-start"/>,
+      <xref linkend="repmgr-daemon-stop"/>
+    </para>
+  </refsect1>
+</refentry>
+
--- a/doc/repmgr-service-status.xml
+++ b/doc/repmgr-service-status.xml
@@ -0,0 +1,215 @@
+<refentry id="repmgr-service-status">
+  <indexterm>
+    <primary>repmgr service status</primary>
+  </indexterm>
+
+  <indexterm>
+    <primary>repmgrd</primary>
+    <secondary>displaying service status</secondary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr service status</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr service status</refname>
+    <refpurpose>display information about the status of &repmgrd; on each node in the cluster</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      This command provides an overview over all active nodes in the cluster and the state
+      of each node's &repmgrd; instance. It can be used to check
+      the result of <xref linkend="repmgr-service-pause"/> and <xref linkend="repmgr-service-unpause"/>
+      operations.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Prerequisites</title>
+    <para>
+      PostgreSQL should be accessible on all nodes (using the <varname>conninfo</varname> string shown by
+      <link linkend="repmgr-cluster-show"><command>repmgr cluster show</command></link>)
+      from the node where <command>repmgr service status</command> is executed.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
+    <para>
+      <command>repmgr service status</command> can be executed on any active node in the
+      replication cluster. A valid <filename>repmgr.conf</filename> file is required.
+    </para>
+    <para>
+      If a node is not accessible, or PostgreSQL itself is not running on the node,
+      &repmgr; will not be able to determine the status of that node's &repmgrd; instance,
+      and &quot;<literal>n/a</literal>&quot; will be displayed in the node's <literal>repmgrd</literal>
+      column.
+    </para>
+
+    <note>
+      <para>
+        After restarting PostgreSQL on any node, the &repmgrd; instance
+        will take a second or two before it is able to update its status. Until then,
+        &repmgrd; will be shown as not running.
+      </para>
+    </note>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+    <para>
+      &repmgrd; running normally on all nodes:
+    <programlisting>$ repmgr -f /etc/repmgr.conf service status
+ ID | Name  | Role    | Status    | Upstream | repmgrd | PID   | Paused? | Upstream last seen
+----+-------+---------+-----------+----------+---------+-------+---------+--------------------
+ 1  | node1 | primary | * running |          | running | 96563 | no      | n/a
+ 2  | node2 | standby |   running | node1    | running | 96572 | no      | 1 second(s) ago
+ 3  | node3 | standby |   running | node1    | running | 96584 | no      | 0 second(s) ago</programlisting>
+    </para>
+
+    <para>
+      &repmgrd; paused on all nodes (using <xref linkend="repmgr-service-pause"/>):
+    <programlisting>$ repmgr -f /etc/repmgr.conf service status
+ ID | Name  | Role    | Status    | Upstream | repmgrd | PID   | Paused? | Upstream last seen
+----+-------+---------+-----------+----------+---------+-------+---------+--------------------
+ 1  | node1 | primary | * running |          | running | 96563 | yes     | n/a
+ 2  | node2 | standby |   running | node1    | running | 96572 | yes     | 1 second(s) ago
+ 3  | node3 | standby |   running | node1    | running | 96584 | yes     | 0 second(s) ago</programlisting>
+    </para>
+
+    <para>
+      &repmgrd; not running on one node:
+    <programlisting>$ repmgr -f /etc/repmgr.conf service status
+ ID | Name  | Role    | Status    | Upstream | repmgrd     | PID   | Paused? | Upstream last seen
+----+-------+---------+-----------+----------+-------------+-------+---------+--------------------
+ 1  | node1 | primary | * running |          | running     | 96563 | yes     | n/a
+ 2  | node2 | standby |   running | node1    | not running | n/a   | n/a     | n/a
+ 3  | node3 | standby |   running | node1    | running     | 96584 | yes     | 0 second(s) ago</programlisting>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--csv</option></term>
+        <listitem>
+          <para>
+            <command>repmgr service status</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, e.g.:
+            <programlisting>
+    $ repmgr -f /etc/repmgr.conf service status --csv
+    1,node1,primary,1,1,5722,1,100,-1,default
+    2,node2,standby,1,0,-1,1,100,1,default
+    3,node3,standby,1,1,5779,1,100,1,default</programlisting>
+          </para>
+          <para>
+            The columns have following meanings:
+            <itemizedlist spacing="compact" mark="bullet">
+              <listitem>
+                <simpara>
+                  node ID
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  node name
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  node type (primary or standby)
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  PostgreSQL server running (1 = running, 0 = not running)
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  &repmgrd; running (1 = running, 0 = not running, -1 = unknown)
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  &repmgrd; PID (-1 if not running or status unknown)
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  &repmgrd; paused (1 = paused, 0 = not paused, -1 = unknown)
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  &repmgrd; node priority
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  interval in seconds since the node's upstream was last seen (this will be -1 if the value could not be retrieved, or the node is primary)
+                </simpara>
+              </listitem>
+
+			  <listitem>
+                <simpara>
+                  node location
+                </simpara>
+              </listitem>
+
+            </itemizedlist>
+          </para>
+        </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+        <term><option>--detail</option></term>
+        <listitem>
+          <para>
+            Display additional information (<literal>location</literal>, <literal>priority</literal>)
+	    about the &repmgr; configuration.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--verbose</option></term>
+        <listitem>
+          <para>
+            Display the full text of any database connection error messages.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      <xref linkend="repmgr-service-pause"/>,
+      <xref linkend="repmgr-service-unpause"/>,
+      <xref linkend="repmgr-cluster-show"/>,
+      <xref linkend="repmgrd-pausing"/>,
+      <xref linkend="repmgr-daemon-start"/>,
+      <xref linkend="repmgr-daemon-stop"/>
+    </para>
+  </refsect1>
+</refentry>
--- a/doc/repmgr-service-unpause.xml
+++ b/doc/repmgr-service-unpause.xml
@@ -0,0 +1,121 @@
+<refentry id="repmgr-service-unpause">
+  <indexterm>
+    <primary>repmgr service unpause</primary>
+  </indexterm>
+
+  <indexterm>
+    <primary>repmgrd</primary>
+    <secondary>unpausing</secondary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr service unpause</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr service unpause</refname>
+    <refpurpose>Instruct all &repmgrd; instances in the replication cluster to resume failover operations</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      This command can be run on any active node in the replication cluster to instruct all
+      running &repmgrd; instances to &quot;unpause&quot;
+      (following a previous execution of <xref linkend="repmgr-service-pause"/>)
+      and resume normal failover/monitoring operation.
+    </para>
+
+    <note>
+      <para>
+        It's important to wait a few seconds after restarting PostgreSQL on any node before running
+        <command>repmgr service pause</command>, as the &repmgrd; instance
+        on the restarted node will take a second or two before it has updated its status.
+      </para>
+    </note>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Prerequisites</title>
+    <para>
+      PostgreSQL must be accessible on all nodes (using the <varname>conninfo</varname> string shown by
+      <link linkend="repmgr-cluster-show"><command>repmgr cluster show</command></link>)
+      from the node where <command>repmgr service pause</command> is executed.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
+    <para>
+     <command>repmgr service unpause</command> can be executed on any active node in the
+      replication cluster. A valid <filename>repmgr.conf</filename> file is required.
+      It will have no effect on nodes which are not already paused.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
+    <para>
+    <programlisting>
+$ repmgr -f /etc/repmgr.conf service unpause
+NOTICE: node 1 (node1) unpaused
+NOTICE: node 2 (node2) unpaused
+NOTICE: node 3 (node3) unpaused</programlisting>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check if nodes are reachable but don't unpause &repmgrd;.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr service unpause</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            &repmgrd; could be unpaused on all nodes.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_REPMGRD_PAUSE (26)</option></term>
+        <listitem>
+          <para>
+           &repmgrd; could not be unpaused on one or mode nodes.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      <xref linkend="repmgr-service-pause"/>,
+      <xref linkend="repmgr-service-status"/>,
+      <xref linkend="repmgrd-pausing"/>,
+      <xref linkend="repmgr-daemon-start"/>,
+      <xref linkend="repmgr-daemon-stop"/>
+    </para>
+  </refsect1>
+</refentry>
+
--- a/doc/repmgr-standby-clone.sgml
+++ b/doc/repmgr-standby-clone.sgml
@@ -18,7 +18,7 @@
    <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
+      the cluster or from Barman. It creates the replication configuration required
      to attach the cloned node to the primary node (or another standby, if cascading replication
      is in use).
    </para>
@@ -49,7 +49,7 @@
    not be copied by default. &repmgr; can copy these files, either to the same
    location on the standby server (provided appropriate directory and file permissions
    are available), or into the standby's data directory. This requires passwordless
-    SSH access to the primary server. Add the option <literal>--copy-external-config-files</literal>
+    SSH access to the primary server. Add the option <option>--copy-external-config-files</option>
    to the <command>repmgr standby clone</command> command; by default files will be copied to
    the same path as on the upstream server. Note that the user executing <command>repmgr</command>
    must have write access to those directories.
@@ -59,23 +59,46 @@
    <literal>--copy-external-config-files=pgdata</literal>, but note that
    any include directives in the copied files may need to be updated.
   </para>
+
+   <note>
+	 <para>
+	   When executing <command>repmgr standby clone</command> with the
+	   <option>--copy-external-config-files</option> aand <option>--dry-run</option>
+	   options, &repmgr; will check the SSH connection to the source node, but
+	   will not verify whether the files can actually be copied.
+	 </para>
+	 <para>
+	   During the actual clone operation, a check will be made before the database itself
+	   is cloned to determine whether the files can actually be copied; if any problems are
+	   encountered, the clone operation will be aborted, enabling the user to fix
+	   any issues before retrying the clone operation.
+	 </para>
+   </note>
+
   <tip>
    <simpara>
     For reliable configuration file management we recommend using a
     configuration management tool such as Ansible, Chef, Puppet or Salt.
    </simpara>
   </tip>
+
  </refsect1>

  <refsect1 id="repmgr-standby-clone-recovery-conf">
-   <indexterm>
+    <title>Customising replication configuration</title>
+    <indexterm>
     <primary>recovery.conf</primary>
-     <secondary>customising with "repmgr standby clone"</secondary>
-   </indexterm>
+     <secondary>customising with &quot;repmgr standby clone&quot;</secondary>
+    </indexterm>
+
+	<indexterm>
+     <primary>replication configuration</primary>
+     <secondary>customising with &quot;repmgr standby clone&quot;</secondary>
+    </indexterm>
+

-   <title>Customising recovery.conf</title>
   <para>
-     By default, &repmgr; will create a minimal <filename>recovery.conf</filename>
+     By default, &repmgr; will create a minimal replication configuration
     containing following parameters:
   </para>

@@ -101,7 +124,7 @@

   <para>
     The following additional parameters can be specified in <filename>repmgr.conf</filename>
-     for inclusion in <filename>recovery.conf</filename>:
+     for inclusion in the replication configuration:
   </para>

   <itemizedlist spacing="compact" mark="bullet">
@@ -125,7 +148,7 @@
       We recommend using <ulink url="https://www.pgbarman.org/">Barman</ulink> to manage
       WAL file archiving. For more details on combining &repmgr; and <application>Barman</application>,
       in particular using <varname>restore_command</varname> to configure Barman as a backup source of
-       WAL files, see <xref linkend="cloning-from-barman">.
+       WAL files, see <xref linkend="cloning-from-barman"/>.
     </para>
   </note>

@@ -137,7 +160,7 @@
    When initially cloning a standby, you will need to ensure
    that all required WAL files remain available while the cloning is taking
    place. To ensure this happens when using the default <command>pg_basebackup</command> method,
-    &repmgr; will set <command>pg_basebackup</command>'s <literal>--xlog-method</literal>
+    &repmgr; will set <command>pg_basebackup</command>'s <literal>--wal-method</literal>
    parameter to <literal>stream</literal>,
    which will ensure all WAL files generated during the cloning process are
    streamed in parallel with the main backup. Note that this requires two
@@ -147,21 +170,20 @@
   </para>
   <para>
    To override this behaviour, in <filename>repmgr.conf</filename> set
-    <command>pg_basebackup</command>'s <literal>--xlog-method</literal>
+    <command>pg_basebackup</command>'s <literal>--wal-method</literal>
    parameter to <literal>fetch</literal>:
    <programlisting>
-      pg_basebackup_options='--xlog-method=fetch'</programlisting>
+      pg_basebackup_options='--wal-method=fetch'</programlisting>

    and ensure that <literal>wal_keep_segments</literal> is set to an appropriately high value.
-    See the <ulink url="https://www.postgresql.org/docs/current/static/app-pgbasebackup.html">
+    See the <ulink url="https://www.postgresql.org/docs/current/app-pgbasebackup.html">
    pg_basebackup</ulink> documentation for details.
   </para>

   <note>
    <simpara>
-      From PostgreSQL 10, <command>pg_basebackup</command>'s
-      <literal>--xlog-method</literal> parameter has been renamed to
-      <literal>--wal-method</literal>.
+      If using PostgreSQL 9.6 or earlier, replace <literal>--wal-method</literal>
+      with <literal>--xlog-method</literal>.
    </simpara>
   </note>
  </refsect1>
@@ -169,42 +191,57 @@

  <refsect1 id="repmgr-standby-create-recovery-conf">

+   <title>Using a standby cloned by another method</title>
+
   <indexterm>
     <primary>recovery.conf</primary>
     <secondary>generating for a standby cloned by another method</secondary>
   </indexterm>

-   <title>Using a standby cloned by another method</title>
+   <indexterm>
+     <primary>replication configuration</primary>
+     <secondary>generating for a standby cloned by another method</secondary>
+   </indexterm>
+
   <para>
     &repmgr; supports standbys cloned by another method (e.g. using <application>barman</application>'s
-     <command><ulink url="http://docs.pgbarman.org/release/2.4/#recover">barman recover</ulink></command> command).
+     <command><ulink url="https://docs.pgbarman.org/#recover">barman recover</ulink></command> command).
   </para>
   <para>
-     To integrate the standby as a &repmgr; node, ensure the <filename>repmgr.conf</filename>
+     To integrate the standby as a &repmgr; node, once the standby has been cloned,
+     ensure the <filename>repmgr.conf</filename>
     file is created for the node, and that it has been registered using
     <command><link linkend="repmgr-standby-register">repmgr standby register</link></command>.
+   </para>
+   <tip>
+     <para>
+       To register a standby which is not running, execute
+       <link linkend="repmgr-standby-register">repmgr standby register --force</link>
+       and provide the connection details for the primary.
+     </para>
+     <para>
+       See <xref linkend="repmgr-standby-register-inactive-node"/> for more details.
+     </para>
+   </tip>
+   <para>
     Then execute the command <command>repmgr standby clone --recovery-conf-only</command>.
     This will create the <filename>recovery.conf</filename> file needed to attach
-     the node to its upstream, and will also create a replication slot on the
+     the node to its upstream (in PostgreSQL 12 and later: append replication configuration
+     to <filename>postgresql.auto.conf</filename>), and will also create a replication slot on the
     upstream node if required.
   </para>
   <para>
-     Note that the upstream node must be running. An existing
+     Note that the upstream node must be running. In PostgreSQL 11 and earlier, an existing
     <filename>recovery.conf</filename> will not be overwritten unless the
     <option>-F/--force</option> option is provided.
   </para>
   <para>
     Execute <command>repmgr standby clone --recovery-conf-only --dry-run</command>
-     to check the prerequisites for creating the <filename>recovery.conf</filename> file,
-     and display the contents of the file without actually creating it.
+     to check the prerequisites for creating the recovery configuration,
+     and display the contents of the configuration which would be added without actually
+	 making any changes.
   </para>

-   <note>
-     <para>
-       <option>--recovery-conf-only</option> was introduced in &repmgr; <link linkend="release-4.0.4">4.0.4</link>.
-     </para>
-   </note>
-
  </refsect1>

  <refsect1>
@@ -230,8 +267,8 @@
          </para>
          <para>
            If <option>--recovery-conf-only</option> specified, the contents of
-            the generated <filename>recovery.conf</filename> file will be displayed
-            but the file itself not written.
+            the generated recovery configuration will be displayed
+            but not written.
          </para>
        </listitem>
      </varlistentry>
@@ -278,8 +315,16 @@
        <term><option> --recovery-conf-only</option></term>
        <listitem>
          <para>
-            Create <filename>recovery.conf</filename> file for a previously cloned instance. &repmgr 4.0.4 and later.
+            Create recovery configuration for a previously cloned instance.
          </para>
+		  <para>
+			In PostgreSQL 11 and earlier, the replication configuration will be
+			written to <filename>recovery.conf</filename>.
+		  </para>
+		  <para>
+			In PostgreSQL 12 and later, the replication configuration will be
+			written to <filename>postgresql.auto.conf</filename>.
+		  </para>
        </listitem>
      </varlistentry>

@@ -307,9 +352,13 @@
        <term><option>--upstream-conninfo</option></term>
        <listitem>
          <para>
-            <literal>primary_conninfo</literal> value to write in recovery.conf
+            <literal>primary_conninfo</literal> value to include in the recovery configuration
            when the intended upstream server does not yet exist.
          </para>
+          <para>
+            Note that &repmgr; may modify the provided value, in particular to set the
+            correct <literal>application_name</literal>.
+          </para>
        </listitem>
      </varlistentry>

@@ -333,7 +382,7 @@
    </variablelist>
  </refsect1>

-  <refsect1>
+  <refsect1 id="repmgr-standby-clone-events">
    <title>Event notifications</title>
    <para>
      A <literal>standby_clone</literal> <link linkend="event-notifications">event notification</link> will be generated.
@@ -343,7 +392,7 @@
  <refsect1>
    <title>See also</title>
    <para>
-      See <xref linkend="cloning-standbys"> for details about various aspects of cloning.
+      See <xref linkend="cloning-standbys"/> for details about various aspects of cloning.
    </para>
  </refsect1>
 </refentry>
--- a/doc/repmgr-standby-follow.sgml
+++ b/doc/repmgr-standby-follow.sgml
@@ -1,116 +0,0 @@
-<refentry id="repmgr-standby-follow">
-  <indexterm>
-    <primary>repmgr standby follow</primary>
-  </indexterm>
-
-  <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>
-	<tip>
-      <para>
-		To re-add an inactive node to the replication cluster, use
-		<xref linkend="repmgr-node-rejoin">.
-      </para>
-	</tip>
-
-	<para>
-	  <command>repmgr standby follow</command> will wait up to
-	  <varname>standby_follow_timeout</varname> seconds (default: <literal>30</literal>)
-	  to verify the standby has actually connected to the new primary.
-	</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"
-      waiting for server to shut down........ done
-      server stopped
-      waiting for server to start.... done
-      server started
-      NOTICE: STANDBY FOLLOW successful
-      DETAIL: node 3 is now attached to node 2</programlisting>
-    </para>
-  </refsect1>
-
-  <refsect1>
-    <title>Options</title>
-    <variablelist>
-
-      <varlistentry>
-        <term><option>--dry-run</option></term>
-        <listitem>
-          <para>
-            Check prerequisites but don't actually follow a new standby.
-          </para>
-          <important>
-            <para>
-              This does not guarantee the standby can follow the primary; in
-              particular, whether the primary and standby timelines have diverged,
-              can currently only be determined by actually attempting to
-              attach the standby to the primary.
-            </para>
-          </important>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>-w</option></term>
-        <term><option>--wait</option></term>
-        <listitem>
-          <para>
-            Wait for a primary to appear. &repmgr; will wait for up to
-            <varname>primary_follow_timeout</varname> seconds
-            (default: 60 seconds) to verify that the standby is following the new primary.
-            This value can be defined in <filename>repmgr.conf</filename>.
-          </para>
-        </listitem>
-      </varlistentry>
-
-    </variablelist>
-  </refsect1>
-
-  <refsect1>
-    <title>Event notifications</title>
-    <para>
-      A <literal>standby_follow</literal> <link linkend="event-notifications">event notification</link> will be generated.
-    </para>
-    <para>
-      If provided, &repmgr; will substitute the placeholders <literal>%p</literal> with the node ID of the primary
-      being followed, <literal>%c</literal> with its <literal>conninfo</literal> string, and
-      <literal>%a</literal> with its node name.
-    </para>
-  </refsect1>
-
-  <refsect1>
-    <title>See also</title>
-    <para>
-     <xref linkend="repmgr-node-rejoin">
-    </para>
-  </refsect1>
-</refentry>
-
--- a/doc/repmgr-standby-follow.xml
+++ b/doc/repmgr-standby-follow.xml
@@ -0,0 +1,263 @@
+<refentry id="repmgr-standby-follow">
+  <indexterm>
+    <primary>repmgr standby follow</primary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr standby follow</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr standby follow</refname>
+    <refpurpose>attach a running standby to a new upstream node</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      Attaches the standby (&quot;follow candidate&quot;) to a new upstream node
+      (&quot;follow target&quot;). Typically this will be the primary, but this
+      command can also be used to attach the standby to another standby.
+    </para>
+
+    <para>
+      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>The standby node (&quot;follow candidate&quot;) <emphasis>must</emphasis>
+      be running. If the new upstream (&quot;follow target&quot;) is not the primary,
+      the cluster primary <emphasis>must</emphasis> be running and accessible from the
+      standby node.
+    </para>
+
+    <tip>
+      <para>
+        To re-add an inactive node to the replication cluster, use
+        <xref linkend="repmgr-node-rejoin"/>.
+      </para>
+    </tip>
+
+    <para>
+      By default &repmgr; will attempt to attach the standby to the current primary.
+      If <option>--upstream-node-id</option> is provided, &repmgr; will attempt
+      to attach the standby to the specified node, which can be another standby.
+    </para>
+
+    <para>
+      This command will force a restart of PostgreSQL on the standby node.
+    </para>
+
+    <para>
+      <command>repmgr standby follow</command> will wait up to
+      <varname>standby_follow_timeout</varname> seconds (default: <literal>30</literal>)
+      to verify the standby has actually connected to the new upstream node.
+    </para>
+
+    <note>
+      <para>
+        If <option>recovery_min_apply_delay</option> is set for the standby, it
+        will not attach to the new upstream node until it has replayed available
+        WAL.
+      </para>
+      <para>
+        Conversely, if the standby is attached to an upstream standby
+        which has <option>recovery_min_apply_delay</option> set, the upstream
+        standby's replay state may actually be behind that of its new downstream node.
+      </para>
+    </note>
+
+  </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"
+      waiting for server to shut down........ done
+      server stopped
+      waiting for server to start.... done
+      server started
+      NOTICE: STANDBY FOLLOW successful
+      DETAIL: node 3 is now attached to node 2</programlisting>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check prerequisites but don't actually follow a new upstream node.
+          </para>
+          <para>
+            This will also verify whether the standby is capable of following the new upstream node.
+          </para>
+          <important>
+            <para>
+              If a standby was turned into a primary by removing <filename>recovery.conf</filename>
+              (<application>PostgreSQL 12</application> and later: <filename>standby.signal</filename>),
+              &repmgr; will <emphasis>not</emphasis> be able to determine whether that primary's timeline
+              has diverged from the timeline of the standby (&quot;follow candidate&quot;).
+            </para>
+            <para>
+              We recommend always to use <link linkend="repmgr-standby-promote"><command>repmgr standby promote</command></link>
+              to promote a standby to primary, as this will ensure that the new primary
+              will perform a timeline switch (making it practical to check for timeline divergence)
+              and also that &repmgr; metadata is updated correctly.
+            </para>
+          </important>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--upstream-node-id</option></term>
+        <listitem>
+          <para>
+            Node ID of the new upstream node (&quot;follow target&quot;).
+          </para>
+          <para>
+            If not provided, &repmgr; will attempt to follow the current primary node.
+          </para>
+          <para>
+            Note that when using &repmgrd;, <option>--upstream-node-id</option>
+            should always be configured;
+            see <link linkend="repmgrd-automatic-failover-configuration">Automatic failover configuration</link>
+            for details.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-w</option></term>
+        <term><option>--wait</option></term>
+        <listitem>
+          <para>
+            Wait for a primary to appear. &repmgr; will wait for up to
+            <varname>primary_follow_timeout</varname> seconds
+            (default: 60 seconds) to verify that the standby is following the new primary.
+            This value can be defined in <filename>repmgr.conf</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
+
+    <para>
+      Execute with the <literal>--dry-run</literal> option to test the follow operation as
+      far as possible, without actually changing the status of the node.
+    </para>
+
+    <para>
+      Note that &repmgr; will first attempt to determine whether the standby
+      (&quot;follow candidate&quot;) is capable of following the
+      new upstream node (&quot;follow target&quot;).
+    </para>
+    <para>
+      If, for example, the new upstream node has diverged from this node's timeline,
+      for example if the new upstream node was promoted to primary while this node
+      was still attached to the original primary, it will <emphasis>not</emphasis>
+      be possible to follow the new upstream node, and &repmgr; will emit an error
+      message like this:
+      <programlisting>
+ERROR: this node cannot attach to follow target node &quot;node3&quot; (ID 3)
+DETAIL: follow target server's timeline 2 forked off current database system timeline 1 before current recovery point 0/6108880</programlisting>
+    </para>
+    <para>
+      In this case, it may be possible to have this node follow the new upstream
+      using <command><link linkend="repmgr-node-rejoin">repmgr node rejoin</link></command>
+      with the <option>--force-rewind</option> to execute <command>pg_rewind</command>.
+      This does mean that transactions which exist on this node, but not the new upstream,
+      will be lost.
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr standby follow</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            The follow operation succeeded; or if <option>--dry-run</option> was provided,
+            no issues were detected which would prevent the follow operation.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_BAD_CONFIG (1)</option></term>
+        <listitem>
+          <para>
+            A configuration issue was detected which prevented &repmgr; from
+            continuing with the follow operation.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_NO_RESTART (4)</option></term>
+        <listitem>
+          <para>
+            The node could not be restarted.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_DB_CONN (6)</option></term>
+        <listitem>
+          <para>
+            &repmgr; was unable to establish a database connection to one of the nodes.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_FOLLOW_FAIL (23)</option></term>
+        <listitem>
+          <para>
+            &repmgr; was unable to complete the follow command.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1 id="repmgr-standby-follow-events">
+    <title>Event notifications</title>
+    <para>
+      A <literal>standby_follow</literal> <link linkend="event-notifications">event notification</link> will be generated.
+    </para>
+    <para>
+      If provided, &repmgr; will substitute the placeholders <literal>%p</literal> with the node ID of the node
+      being followed, <literal>%c</literal> with its <literal>conninfo</literal> string, and
+      <literal>%a</literal> with its node name.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+     <xref linkend="repmgr-node-rejoin"/>
+    </para>
+  </refsect1>
+</refentry>
--- a/doc/repmgr-standby-promote.sgml
+++ b/doc/repmgr-standby-promote.sgml
@@ -1,60 +0,0 @@
-<refentry id="repmgr-standby-promote">
-  <indexterm>
-    <primary>repmgr standby promote</primary>
-  </indexterm>
-
-  <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>
-    <para>
-      Note that &repmgr; will wait for up to <varname>promote_check_timeout</varname> seconds
-      (default: 60 seconds) to verify that the standby has been promoted, and will
-      check the promotion every <varname>promote_check_interval</varname> seconds (default: 1 second).
-      Both values can be defined in <filename>repmgr.conf</filename>.
-    </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>
-  </refsect1>
-
-
-  <refsect1>
-    <title>Event notifications</title>
-    <para>
-      A <literal>standby_promote</literal> <link linkend="event-notifications">event notification</link> will be generated.
-    </para>
-  </refsect1>
-
-</refentry>
--- a/doc/repmgr-standby-promote.xml
+++ b/doc/repmgr-standby-promote.xml
@@ -0,0 +1,255 @@
+<refentry id="repmgr-standby-promote">
+  <indexterm>
+    <primary>repmgr standby promote</primary>
+  </indexterm>
+
+  <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>
+    <important>
+      <para>
+        If &repmgrd; is active, you must execute
+        <command><link linkend="repmgr-service-pause">repmgr service pause</link></command>
+        (&repmgr; 4.2 - 4.4: <command><link linkend="repmgr-service-pause">repmgr service pause</link></command>)
+        to temporarily disable &repmgrd; while making any changes
+        to the replication cluster.
+      </para>
+    </important>
+
+    <para>
+      If the standby promotion succeeds, the server will not need to be
+      restarted. However any other standbys will need to follow the new primary,
+      and will need to be restarted to do this.
+    </para>
+    <para>
+      Beginning with <link linkend="release-4.4">repmgr 4.4</link>,
+      the option <option>--siblings-follow</option> can be used to have
+      all other standbys (and a witness server, if in use)
+	  follow the new primary.
+    </para>
+
+    <note>
+      <para>
+        If using &repmgrd;, when invoking
+        <command>repmgr standby promote</command> (either directly via
+        the <option>promote_command</option>, or in a script called
+        via <option>promote_command</option>), <option>--siblings-follow</option>
+        <emphasis>must not</emphasis> be included as a
+        command line option for <command>repmgr standby promote</command>.
+      </para>
+    </note>
+
+    <para>
+      In <link linkend="release-4.3">repmgr 4.3</link> and earlier,
+      <command><link linkend="repmgr-standby-follow">repmgr standby follow</link></command>
+      must be executed on each standby individually.
+    </para>
+
+    <para>
+      &repmgr; will wait for up to <varname>promote_check_timeout</varname> seconds
+      (default: <literal>60</literal>) to verify that the standby has been promoted, and will
+      check the promotion every <varname>promote_check_interval</varname> seconds (default: 1 second).
+      Both values can be defined in <filename>repmgr.conf</filename>.
+    </para>
+
+    <note>
+      <para>
+        If WAL replay is paused on the standby, and not all WAL files on the standby have been
+        replayed, &repmgr; will not attempt to promote it.
+      </para>
+      <para>
+        This is because if WAL replay is paused, PostgreSQL itself will not react to a promote command
+        until WAL replay is resumed and all pending WAL has been replayed. This means
+        attempting to promote PostgreSQL in this state will leave PostgreSQL in a condition where the
+        promotion may occur at a unpredictable point in the future.
+      </para>
+      <para>
+        Note that if the standby is in archive recovery, &repmgr; will not be able to determine
+        if more WAL is pending replay, and will abort the promotion attempt if WAL replay is paused.
+      </para>
+    </note>
+
+  </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>
+  </refsect1>
+
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+      <varlistentry>
+
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check if this node can be promoted, but don't carry out the promotion.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--siblings-follow</option></term>
+        <listitem>
+          <para>
+            Have all sibling nodes (nodes formerly attached to the same upstream
+            node as the promotion candidate) follow this node after it has been promoted.
+          </para>
+		  <para>
+			Note that a witness server, if in use, is also
+			counted as a &quot;sibling node&quot; as it needs to be instructed to
+			synchronise its metadata with the new primary.
+		  </para>
+          <important>
+            <para>
+              Do <emphasis>not</emphasis> provide this option when configuring
+              &repmgrd;'s <option>promote_command</option>.
+            </para>
+          </important>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration file settings</title>
+   <para>
+     The following parameters in <filename>repmgr.conf</filename> are relevant to the
+     promote operation:
+    </para>
+
+    <para>
+      <itemizedlist spacing="compact" mark="bullet">
+
+       <listitem>
+        <indexterm>
+          <primary>promote_check_interval</primary>
+          <secondary>with &quot;repmgr standby promote &quot;</secondary>
+        </indexterm>
+         <simpara>
+           <literal>promote_check_interval</literal>:
+           interval (in seconds, default: 1 second) to wait between each check
+           to determine whether the standby has been promoted.
+		 </simpara>
+	   </listitem>
+
+       <listitem>
+        <indexterm>
+          <primary>promote_check_timeout</primary>
+          <secondary>with &quot;repmgr standby promote &quot;</secondary>
+        </indexterm>
+         <simpara>
+           <literal>promote_check_timeout</literal>:
+           time (in seconds, default: 60 seconds) to wait to verify that the standby has been promoted
+           before exiting with <literal>ERR_PROMOTION_FAIL</literal>.
+		 </simpara>
+	   </listitem>
+
+	  </itemizedlist>
+	</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      Following exit codes can be emitted by <command>repmgr standby promote</command>:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            The standby was successfully promoted to primary.
+          </para>
+        </listitem>
+      </varlistentry>
+
+     <varlistentry>
+        <term><option>ERR_DB_CONN (6)</option></term>
+        <listitem>
+          <para>
+            &repmgr; was unable to connect to the local PostgreSQL node.
+          </para>
+          <para>
+            PostgreSQL must be running before the node can be promoted.
+          </para>
+        </listitem>
+      </varlistentry>
+
+     <varlistentry>
+       <term><option>ERR_PROMOTION_FAIL (8)</option></term>
+        <listitem>
+          <para>
+            The node could not be promoted to primary for one of the following
+            reasons:
+            <itemizedlist spacing="compact" mark="bullet">
+
+              <listitem>
+                <simpara>
+                  there is an existing primary node in the replication cluster
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  the node is not a standby
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  WAL replay is paused on the node
+                </simpara>
+              </listitem>
+
+              <listitem>
+                <simpara>
+                  execution of the PostgreSQL promote command failed
+                </simpara>
+              </listitem>
+
+            </itemizedlist>
+          </para>
+        </listitem>
+     </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+
+  <refsect1 id="repmgr-standby-promote-events">
+    <title>Event notifications</title>
+    <para>
+      A <literal>standby_promote</literal> <link linkend="event-notifications">event notification</link> will be generated.
+    </para>
+  </refsect1>
+
+</refentry>
--- a/doc/repmgr-standby-register.sgml
+++ b/doc/repmgr-standby-register.sgml
@@ -17,7 +17,7 @@
    <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.
+      promote/follow operations and to allow &repmgrd; 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.
@@ -28,7 +28,7 @@
        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
+        <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
@@ -59,7 +59,7 @@
   <para>
     Depending on your environment and workload, it may take some time for the standby's node record
     to propagate from the primary to the standby. Some actions (such as starting
-     <application>repmgrd</application>) require that the standby's node record
+     &repmgrd;) require that the standby's node record
     is present and up-to-date to function correctly.
   </para>
   <para>
@@ -75,10 +75,22 @@
   <para>
    Under some circumstances you may wish to register a standby which is not
    yet running; this can be the case when using provisioning tools to create
-    a complex replication cluster. In this case, by using the <option>-F/--force</option>
-    option and providing the connection parameters to the primary server,
-    the standby can be registered.
+    a complex replication cluster, or if the node was not cloned by &repmgr;.
   </para>
+   <para>
+    In this case, by using the <option>-F/--force</option>
+    option and providing the connection parameters to the primary server,
+    the standby can be registered even if it has not yet been started.
+   </para>
+   <tip>
+     <para>
+       Connection parameters can either be provided either as a <literal>conninfo</literal> string
+       (e.g. <option>-d 'host=node1 user=repmgr'</option> or as individual connection parameters
+        (<option>-h/--host</option>, <option>-d/--dbname</option>,
+       <option>-U/--user</option>, <option>-p/--port</option> etc.).
+     </para>
+   </tip>
+
   <para>
    Similarly, with cascading replication it may be necessary to register
    a standby whose upstream node has not yet been registered - in this case,
@@ -96,9 +108,11 @@
    <title>Registering a node not cloned by repmgr</title>
    <para>
      If you've cloned a standby using another method (e.g. <application>barman</application>'s
-     <command>barman recover</command> command), first execute
+     <command><ulink url="https://docs.pgbarman.org/#recover">barman recover</ulink></command>
+     command), register the node as detailed in section
+     <xref linkend="repmgr-standby-register-inactive-node"/> then execute
     <link linkend="repmgr-standby-create-recovery-conf">repmgr standby clone --recovery-conf-only</link>
-     to add the <filename>recovery.conf</filename> file, then register the standby as usual.
+     to generate the appropriate replication configuration.
    </para>
  </refsect1>

@@ -119,7 +133,7 @@


      <varlistentry>
-       <term><option>-F</option><option>--force</option></term>
+       <term><option>-F</option>/<option>--force</option></term>
        <listitem>
          <para>
            Overwrite an existing node record
@@ -159,7 +173,7 @@
    </variablelist>
  </refsect1>

-  <refsect1>
+  <refsect1 id="repmgr-standby-register-events">
    <title>Event notifications</title>
    <para>
      A <literal>standby_register</literal> <link linkend="event-notifications">event notification</link>
--- a/doc/repmgr-standby-switchover.sgml
+++ b/doc/repmgr-standby-switchover.sgml
@@ -1,259 +0,0 @@
-<refentry id="repmgr-standby-switchover">
-  <indexterm>
-    <primary>repmgr standby switchover</primary>
-  </indexterm>
-
-  <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. This requires a passwordless SSH connection between the promotion
-      candidate (new primary) and the standbys attached to the demotion candidate
-      (existing primary).
-    </para>
-    <note>
-      <para>
-        Performing a switchover is a non-trivial operation. In particular it
-        relies on the current primary being able to shut down cleanly and quickly.
-        &repmgr; will attempt to check for potential issues but cannot guarantee
-        a successful switchover.
-      </para>
-    </note>
-    <para>
-      For more details on performing a switchover, including preparation and configuration,
-      see section <xref linkend="performing-switchover">.
-    </para>
-
-    <note>
-      <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>
-        &repmgr; will not perform the switchover if an exclusive backup is running on the current primary.
-      </para>
-    </note>
-
-  </refsect1>
-
-  <refsect1>
-    <title>Options</title>
-    <variablelist>
-
-      <varlistentry>
-        <term><option>--always-promote</option></term>
-        <listitem>
-          <para>
-            Promote standby to primary, even if it is behind original primary
-            (original primary will be shut down in any case).
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--dry-run</option></term>
-        <listitem>
-          <para>
-            Check prerequisites but don't actually execute a switchover.
-          </para>
-          <important>
-            <para>
-              Success of <option>--dry-run</option> does not imply the switchover will
-              complete successfully, only that
-              the prerequisites for performing the operation are met.
-            </para>
-          </important>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>-F</option></term>
-        <term><option>--force</option></term>
-        <listitem>
-          <para>
-            Ignore warnings and continue anyway.
-          </para>
-          <para>
-            Specifically, if a problem is encountered when shutting down the current primary,
-            using <option>-F/--force</option> will cause &repmgr; to continue by promoting
-            the standby to be the new primary, and if <option>--siblings-follow</option> is
-            specified, attach any other standbys to the new primary.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--force-rewind[=/path/to/pg_rewind]</option></term>
-        <listitem>
-          <para>
-            Use <application>pg_rewind</application> to reintegrate the old primary if necessary
-            (and the prerequisites for using <application>pg_rewind</application> are met).
-            If using PostgreSQL 9.3 or 9.4, and the <application>pg_rewind</application>
-            binary is not installed in the PostgreSQL <filename>bin</filename> directory,
-            provide its full path. For more details see also <xref linkend="switchover-pg-rewind">.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>-R</option></term>
-        <term><option>--remote-user</option></term>
-        <listitem>
-          <para>
-            System username for remote SSH operations (defaults to local system user).
-          </para>
-        </listitem>
-      </varlistentry>
-
-     <varlistentry>
-        <term><option>--siblings-follow</option></term>
-        <listitem>
-          <para>
-            Have standbys attached to the old primary follow the new primary.
-          </para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
-
-  </refsect1>
-
-  <refsect1>
-    <title>Configuration file settings</title>
-
-    <para>
-     Note that following parameters in <filename>repmgr.conf</filename> are relevant to the
-     switchover operation:
-     <itemizedlist spacing="compact" mark="bullet">
-       <listitem>
-         <simpara>
-           <literal>reconnect_attempts</literal>: number of times to check the original primary
-           for a clean shutdown after executing the shutdown command, before aborting
-         </simpara>
-       </listitem>
-       <listitem>
-         <simpara>
-           <literal>reconnect_interval</literal>: interval (in seconds) to check the original
-           primary for a clean shutdown after executing the shutdown command (up to a maximum
-           of <literal>reconnect_attempts</literal> tries)
-         </simpara>
-       </listitem>
-       <listitem>
-         <simpara>
-           <literal>replication_lag_critical</literal>:
-           if replication lag (in seconds) on the standby exceeds this value, the
-           switchover will be aborted (unless the <literal>-F/--force</literal> option
-           is provided)
-         </simpara>
-       </listitem>
-
-       <listitem>
-         <simpara>
-           <literal>standby_reconnect_timeout</literal>:
-           number of seconds to attempt to wait for the demoted primary
-           to reconnect to the promoted primary (default: 60 seconds)
-         </simpara>
-       </listitem>
-
-     </itemizedlist>
-    </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>
-    <important>
-      <para>
-        <application>repmgrd</application> must be shut down on all nodes while a switchover is being
-        executed. This restriction will be removed in a future &repmgr; version.
-      </para>
-    </important>
-    <para>
-      External database connections, e.g. from an application, should not be permitted while
-      the switchover is taking place. In particular, active transactions on the primary
-      can potentially disrupt the shutdown process.
-    </para>
-  </refsect1>
-
-  <refsect1>
-    <title>Event notifications</title>
-    <para>
-      <literal>standby_switchover</literal> and <literal>standby_promote</literal>
-      <link linkend="event-notifications">event notifications</link> will be generated for the new primary,
-      and a <literal>node_rejoin</literal> event notification for the former primary (new standby).
-    </para>
-    <para>
-      If using an event notification script, <literal>standby_switchover</literal>
-      will populate the placeholder parameter <literal>%p</literal> with the node ID of
-      the former primary.
-    </para>
-  </refsect1>
-
-  <refsect1>
-    <title>Exit codes</title>
-    <para>
-      Following exit codes can be emitted by <command>repmgr standby switchover</command>:
-    </para>
-    <variablelist>
-
-      <varlistentry>
-        <term><option>SUCCESS (0)</option></term>
-        <listitem>
-          <para>
-            The switchover completed successfully.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>ERR_SWITCHOVER_FAIL (18)</option></term>
-        <listitem>
-          <para>
-            The switchover could not be executed.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>ERR_SWITCHOVER_INCOMPLETE (22)</option></term>
-        <listitem>
-          <para>
-            The switchover was executed but a problem was encountered.
-            Typically this means the former primary could not be reattached
-            as a standby. Check preceding log messages for more information.
-          </para>
-        </listitem>
-      </varlistentry>
-
-   </variablelist>
-  </refsect1>
-
-  <refsect1>
-    <title>See also</title>
-    <para>
-      For more details see the section <xref linkend="performing-switchover">.
-    </para>
-  </refsect1>
-
-</refentry>
--- a/doc/repmgr-standby-switchover.xml
+++ b/doc/repmgr-standby-switchover.xml
@@ -0,0 +1,395 @@
+<refentry id="repmgr-standby-switchover">
+  <indexterm>
+    <primary>repmgr standby switchover</primary>
+  </indexterm>
+
+  <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 nodes are connected to the demotion candidate, &repmgr; can instruct
+      these to follow the new primary if the option <literal>--siblings-follow</literal>
+      is specified. This requires a passwordless SSH connection between the promotion
+      candidate (new primary) and the nodes attached to the demotion candidate
+      (existing primary). Note that a witness server, if in use, is also
+	  counted as a &quot;sibling node&quot; as it needs to be instructed to
+	  synchronise its metadata with the new primary.
+    </para>
+    <note>
+      <para>
+        Performing a switchover is a non-trivial operation. In particular it
+        relies on the current primary being able to shut down cleanly and quickly.
+        &repmgr; will attempt to check for potential issues but cannot guarantee
+        a successful switchover.
+      </para>
+      <para>
+        &repmgr; will refuse to perform the switchover if an exclusive backup is running on
+        the current primary, or if WAL replay is paused on the standby.
+      </para>
+    </note>
+    <para>
+      For more details on performing a switchover, including preparation and configuration,
+      see section <xref linkend="performing-switchover"/>.
+    </para>
+
+    <note>
+      <para>
+        From <link linkend="release-4.2">repmgr 4.2</link>, &repmgr; will instruct any running
+        &repmgrd; instances to pause operations while the switchover
+        is being carried out, to prevent &repmgrd; from
+        unintentionally promoting a node. For more details, see <xref linkend="repmgrd-pausing"/>.
+      </para>
+      <para>
+        Users of &repmgr; versions prior to 4.2 should ensure that &repmgrd;
+        is not running on any nodes while a switchover is being executed.
+      </para>
+    </note>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--always-promote</option></term>
+        <listitem>
+          <para>
+            Promote standby to primary, even if it is behind or has diverged
+            from the original primary. The original primary will be shut down in any case,
+            and will need to be manually reintegrated into the replication cluster.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--dry-run</option></term>
+        <listitem>
+          <para>
+            Check prerequisites but don't actually execute a switchover.
+          </para>
+          <important>
+            <para>
+              Success of <option>--dry-run</option> does not imply the switchover will
+              complete successfully, only that
+              the prerequisites for performing the operation are met.
+            </para>
+          </important>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-F</option></term>
+        <term><option>--force</option></term>
+        <listitem>
+          <para>
+            Ignore warnings and continue anyway.
+          </para>
+          <para>
+            Specifically, if a problem is encountered when shutting down the current primary,
+            using <option>-F/--force</option> will cause &repmgr; to continue by promoting
+            the standby to be the new primary, and if <option>--siblings-follow</option> is
+            specified, attach any other standbys to the new primary.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--force-rewind[=/path/to/pg_rewind]</option></term>
+        <listitem>
+          <para>
+            Use <application>pg_rewind</application> to reintegrate the old primary if necessary
+            (and the prerequisites for using <application>pg_rewind</application> are met).
+            If using PostgreSQL 9.3 or 9.4, and the <application>pg_rewind</application>
+            binary is not installed in the PostgreSQL <filename>bin</filename> directory,
+            provide its full path. For more details see also <xref linkend="switchover-pg-rewind"/>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-R</option></term>
+        <term><option>--remote-user</option></term>
+        <listitem>
+          <para>
+            System username for remote SSH operations (defaults to local system user).
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--repmgrd-no-pause</option></term>
+        <listitem>
+          <para>
+            Don't pause &repmgrd; while executing a switchover.
+          </para>
+          <para>
+            This option should not be used unless you take steps by other means
+            to ensure &repmgrd; is paused or not
+            running on all nodes.
+          </para>
+		  <para>
+            This option cannot be used together with <option>--repmgrd-force-unpause</option>.
+          </para>
+
+        </listitem>
+      </varlistentry>
+
+	  <varlistentry>
+        <term><option>--repmgrd-force-unpause</option></term>
+        <listitem>
+          <para>
+            Always unpause all &repmgrd; instances after executing a switchover. This will ensure that
+			any &repmgrd; instances which were paused before the switchover will be
+			unpaused.
+          </para>
+          <para>
+            This option cannot be used together with <option>--repmgrd-no-pause</option>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+
+     <varlistentry>
+
+        <term><option>--siblings-follow</option></term>
+        <listitem>
+          <para>
+            Have nodes attached to the old primary follow the new primary.
+          </para>
+          <para>
+            This will also ensure that a witness node, if in use, is updated
+            with the new primary's data.
+          </para>
+          <note>
+            <para>
+              In a future &repmgr; release, <option>--siblings-follow</option> will be applied
+              by default.
+            </para>
+          </note>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration file settings</title>
+
+    <para>
+     The following parameters in <filename>repmgr.conf</filename> are relevant to the
+     switchover operation:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>replication_lag_critical</option></term>
+        <listitem>
+
+          <indexterm>
+            <primary>replication_lag_critical</primary>
+            <secondary>with &quot;repmgr standby switchover&quot;</secondary>
+          </indexterm>
+
+          <para>
+            If replication lag (in seconds) on the standby exceeds this value, the
+            switchover will be aborted (unless the <literal>-F/--force</literal> option
+            is provided)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
+        <term><option>shutdown_check_timeout</option></term>
+        <listitem>
+          <indexterm>
+            <primary>shutdown_check_timeout</primary>
+            <secondary>with &quot;repmgr standby switchover&quot;</secondary>
+          </indexterm>
+
+          <para>
+            The maximum number of seconds to wait for the
+            demotion candidate (current primary) to shut down, before aborting the switchover.
+          </para>
+          <para>
+            Note that this parameter is set on the node where <command>repmgr standby switchover</command>
+            is executed (promotion candidate); setting it on the demotion candidate (former primary) will
+            have no effect.
+          </para>
+         <note>
+           <para>
+             In versions prior to <link linkend="release-4.2">&repmgr; 4.2</link>, <command>repmgr standby switchover</command> would
+             use the values defined in <literal>reconnect_attempts</literal> and <literal>reconnect_interval</literal>
+             to determine the timeout for demotion candidate shutdown.
+           </para>
+         </note>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><option>wal_receive_check_timeout</option></term>
+        <listitem>
+          <indexterm>
+            <primary>wal_receive_check_timeout</primary>
+          <secondary>with &quot;repmgr standby switchover&quot;</secondary>
+          </indexterm>
+
+          <para>
+            After the primary has shut down, the maximum number of seconds to wait for the
+            walreceiver on the standby to flush WAL to disk before comparing WAL receive location
+            with the primary's shut down location.
+         </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+
+        <term><option>standby_reconnect_timeout</option></term>
+        <listitem>
+          <indexterm>
+            <primary>standby_reconnect_timeout</primary>
+            <secondary>with &quot;repmgr standby switchover&quot;</secondary>
+          </indexterm>
+
+          <para>
+            The maximum number of seconds to attempt to wait for the demotion candidate (former primary)
+            to reconnect to the promoted primary (default: 60 seconds)
+          </para>
+          <para>
+            Note that this parameter is set on the node where <command>repmgr standby switchover</command>
+            is executed (promotion candidate); setting it on the demotion candidate (former primary) will
+            have no effect.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
+        <term><option>node_rejoin_timeout</option></term>
+        <listitem>
+
+          <indexterm>
+            <primary>node_rejoin_timeout</primary>
+            <secondary>with &quot;repmgr standby switchover&quot;</secondary>
+          </indexterm>
+
+          <para>
+            maximum number of seconds to attempt to wait for the demotion candidate (former primary)
+            to reconnect to the promoted primary (default: 60 seconds)
+          </para>
+          <para>
+            Note that this parameter is set on the the demotion candidate (former primary);
+            setting it on the node where <command>repmgr standby switchover</command> is
+            executed will have no effect.
+          </para>
+          <para>
+            However, this value <emphasis>must</emphasis> be less than <option>standby_reconnect_timeout</option> on the
+            promotion candidate (the node where <command>repmgr standby switchover</command> is executed).
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </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>
+      External database connections, e.g. from an application, should not be permitted while
+      the switchover is taking place. In particular, active transactions on the primary
+      can potentially disrupt the shutdown process.
+    </para>
+  </refsect1>
+
+  <refsect1 id="repmgr-standby-switchover-events">
+    <title>Event notifications</title>
+    <para>
+      <literal>standby_switchover</literal> and <literal>standby_promote</literal>
+      <link linkend="event-notifications">event notifications</link> will be generated for the new primary,
+      and a <literal>node_rejoin</literal> event notification for the former primary (new standby).
+    </para>
+    <para>
+      If using an event notification script, <literal>standby_switchover</literal>
+      will populate the placeholder parameter <literal>%p</literal> with the node ID of
+      the former primary.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Exit codes</title>
+    <para>
+      One of the following exit codes will be emitted by <command>repmgr standby switchover</command>:
+    </para>
+    <variablelist>
+
+      <varlistentry>
+        <term><option>SUCCESS (0)</option></term>
+        <listitem>
+          <para>
+            The switchover completed successfully; or if <option>--dry-run</option> was provided,
+            no issues were detected which would prevent the switchover operation.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_SWITCHOVER_FAIL (18)</option></term>
+        <listitem>
+          <para>
+            The switchover could not be executed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ERR_SWITCHOVER_INCOMPLETE (22)</option></term>
+        <listitem>
+          <para>
+            The switchover was executed but a problem was encountered.
+            Typically this means the former primary could not be reattached
+            as a standby. Check preceding log messages for more information.
+          </para>
+        </listitem>
+      </varlistentry>
+
+   </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      <xref linkend="repmgr-standby-follow"/>, <xref linkend="repmgr-node-rejoin"/>
+    </para>
+    <para>
+      For more details on performing a switchover operation, see the section <xref linkend="performing-switchover"/>.
+    </para>
+  </refsect1>
+
+</refentry>
--- a/doc/repmgr-standby-unregister.sgml
+++ b/doc/repmgr-standby-unregister.sgml
@@ -59,7 +59,7 @@
    </variablelist>
  </refsect1>

-  <refsect1>
+  <refsect1 id="repmgr-standby-unregister-events">
    <title>Event notifications</title>
    <para>
      A <literal>standby_unregister</literal> <link linkend="event-notifications">event notification</link> will be generated.
--- a/doc/repmgr-witness-register.sgml
+++ b/doc/repmgr-witness-register.sgml
@@ -20,17 +20,30 @@
      record to the &repmgr; metadata, and if necessary initialises the witness
      node by installing the &repmgr; extension and copying the &repmgr; metadata
      to the witness server. This command needs to be executed to enable
-      use of the witness server with <application>repmgrd</application>.
+      use of the witness server with &repmgrd;.
    </para>
    <para>
-      When executing <command>repmgr witness register</command>, connection information
-      for the cluster primary server must also be provided. &repmgr; will automatically
-      use the <varname>user</varname> and <varname>dbname</varname> values defined
-      in the <varname>conninfo</varname> string defined in the  witness node's
-      <filename>repmgr.conf</filename>, if these are not explicitly provided.
+      When executing <command>repmgr witness register</command>, database connection
+      information for the cluster primary server must also be provided.
    </para>
    <para>
-      Execute with the <literal>--dry-run</literal> option to check what would happen
+      In most cases it's only necessary to provide the primary's hostname with
+      the <option>-h</option>/<option>--host</option> option; &repmgr; will
+      automatically use the <varname>user</varname> and <varname>dbname</varname>
+      values defined in the <varname>conninfo</varname> string defined in the
+      witness node's <filename>repmgr.conf</filename>, unless these are explicitly
+      provided as command line options.
+    </para>
+
+    <note>
+      <para>
+        The primary server must be registered with <command><link linkend="repmgr-primary-register">repmgr primary register</link></command> before the witness
+        server can be registered.
+      </para>
+    </note>
+
+    <para>
+      Execute with the <option>--dry-run</option> option to check what would happen
      without actually registering the witness server.
    </para>
  </refsect1>
@@ -50,7 +63,7 @@
  </refsect1>


-  <refsect1>
+  <refsect1 id="repmgr-witness-register-events">
    <title>Event notifications</title>
    <para>
      A <literal>witness_register</literal> <link linkend="event-notifications">event notification</link> will be generated.
--- a/doc/repmgr-witness-unregister.sgml
+++ b/doc/repmgr-witness-unregister.sgml
@@ -92,7 +92,7 @@
  </refsect1>


-  <refsect1>
+  <refsect1 id="repmgr-witness-unregister-events">
    <title>Event notifications</title>
    <para>
      A <literal>witness_unregister</literal> <link linkend="event-notifications">event notification</link> will be generated.
--- a/doc/repmgr.sgml
+++ b/doc/repmgr.sgml
@@ -1,14 +1,16 @@
-<!-- doc/src/sgml/postgres.sgml -->
+<!-- doc/repmgr.xml -->

-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
-
-          <!ENTITY % version SYSTEM "version.sgml">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[
+          <!ENTITY % version SYSTEM "version.xml">
          %version;

-          <!ENTITY % filelist SYSTEM "filelist.sgml">
+          <!ENTITY % filelist SYSTEM "filelist.xml">
          %filelist;

          <!ENTITY repmgr "<productname>repmgr</productname>">
+          <!ENTITY repmgrd "<productname>repmgrd</productname>">
          <!ENTITY postgres "<productname>PostgreSQL</productname>">
 ]>

@@ -24,26 +26,32 @@
  <abstract>
   <para>
   This is the official documentation of &repmgr; &repmgrversion; for
-   use with PostgreSQL 9.3 - PostgreSQL 10.
-   It describes the functionality supported by the current version of &repmgr;.
+   use with PostgreSQL 9.3 - PostgreSQL 12.
+   </para>
+   <para>
+     &repmgr; is being continually developed and we strongly recommend using the
+     latest version. Please check the
+     <ulink url="https://repmgr.org/">repmgr website</ulink> for details
+     about the current &repmgr; version as well as the
+     <ulink url="https://repmgr.org/docs/current/index.html">current repmgr documentation</ulink>.
   </para>

   <para>
-    &repmgr; was developed by
+    &repmgr; is developed by
    <ulink url="https://2ndquadrant.com">2ndQuadrant</ulink>
-    along with contributions from other individuals and companies.
+    along with contributions from other individuals and organisations.
    Contributions from the community are appreciated and welcome - get
-    in touch via <ulink url="https://github.com/2ndQuadrant/repmgr">github</>
-    or <ulink url="https://groups.google.com/group/repmgr">the mailing list/forum</>.
+    in touch via <ulink url="https://github.com/2ndQuadrant/repmgr">github</ulink>
+    or <ulink url="https://groups.google.com/group/repmgr">the mailing list/forum</ulink>.
    Multiple 2ndQuadrant customers contribute funding
    to make repmgr development possible.
   </para>

   <para>
-    2ndQuadrant, a Platinum sponsor of the PostgreSQL project,
-    continues to develop repmgr to meet internal needs and those of customers.
-     Other companies as well as individual developers
-    are welcome to participate in the efforts.
+     &repmgr; is fully supported by 2ndQuadrant's
+     <ulink url="https://www.2ndquadrant.com/en/support/support-postgresql/">24/7 Production Support</ulink>.
+     2ndQuadrant, a Major Sponsor of the PostgreSQL project, continues to develop and maintain &repmgr;.
+     Other organisations as well as individual developers are welcome to participate in the efforts.
   </para>
  </abstract>

@@ -73,21 +81,16 @@
  &promoting-standby;
  &follow-new-primary;
  &switchover;
-  &configuring-witness-server;
  &event-notifications;
  &upgrading-repmgr;
 </part>

 <part id="using-repmgrd">
  <title>Using repmgrd</title>
+  &repmgrd-overview;
  &repmgrd-automatic-failover;
  &repmgrd-configuration;
-  &repmgrd-demonstration;
-  &repmgrd-cascading-replication;
-  &repmgrd-network-split;
-  &repmgrd-witness-server;
-  &repmgrd-degraded-monitoring;
-  &repmgrd-monitoring;
+  &repmgrd-operation;
  &repmgrd-bdr;
 </part>

@@ -107,19 +110,25 @@
  &repmgr-node-status;
  &repmgr-node-check;
  &repmgr-node-rejoin;
+  &repmgr-node-service;
  &repmgr-cluster-show;
  &repmgr-cluster-matrix;
  &repmgr-cluster-crosscheck;
  &repmgr-cluster-event;
  &repmgr-cluster-cleanup;
+  &repmgr-service-status;
+  &repmgr-service-pause;
+  &repmgr-service-unpause;
+  &repmgr-daemon-start;
+  &repmgr-daemon-stop;
 </part>

 &appendix-release-notes;
 &appendix-signatures;
 &appendix-faq;
 &appendix-packages;
+ &appendix-support;

- <![%include-index;[&bookindex;]]>
- <![%include-xslt-index;[<index id="bookindex"></index>]]>
+ <index id="bookindex"></index>

 </book>
--- a/doc/repmgrd-automatic-failover.sgml
+++ b/doc/repmgrd-automatic-failover.sgml
@@ -1,17 +0,0 @@
-<chapter id="repmgrd-automatic-failover" xreflabel="Automatic failover with repmgrd">
- <indexterm>
-   <primary>repmgrd</primary>
-   <secondary>automatic failover</secondary>
- </indexterm>
-
- <title>Automatic failover with repmgrd</title>
-
- <para>
-  <application>repmgrd</application> is a management and monitoring daemon which runs
-  on each node in a replication cluster. It can automate actions such as
-  failover and updating standbys to follow the new primary, as well as
-  providing monitoring information about the state of each standby.
- </para>
-
-
-</chapter>
--- a/doc/repmgrd-automatic-failover.xml
+++ b/doc/repmgrd-automatic-failover.xml
@@ -0,0 +1,933 @@
+<chapter id="repmgrd-automatic-failover" xreflabel="Automatic failover with repmgrd">
+
+ <title>Automatic failover with repmgrd</title>
+
+ <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>automatic failover</secondary>
+ </indexterm>
+
+ <para>
+  &repmgrd; is a management and monitoring daemon which runs
+  on each node in a replication cluster. It can automate actions such as
+  failover and updating standbys to follow the new primary, as well as
+  providing monitoring information about the state of each standby.
+ </para>
+
+ <sect1 id="repmgrd-witness-server" xreflabel="Using a witness server with repmgrd">
+   <title>Using a witness server</title>
+
+ <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>witness server</secondary>
+ </indexterm>
+
+ <indexterm>
+   <primary>witness server</primary>
+   <secondary>repmgrd</secondary>
+ </indexterm>
+
+ <para>
+   A <xref linkend="witness-server"/> is a normal PostgreSQL instance which
+   is not part of the streaming replication cluster; its purpose is, if a
+   failover situation occurs, to provide proof that it is the primary server
+   itself which is unavailable, rather than e.g. a network split between
+   different physical locations.
+ </para>
+
+ <para>
+   A typical use case for a witness server is a two-node streaming replication
+   setup, where the primary and standby are in different locations (data centres).
+   By creating a witness server in the same location (data centre) as the primary,
+   if the primary becomes unavailable it's possible for the standby to decide whether
+   it can promote itself without risking a "split brain" scenario: if it can't see either the
+   witness or the primary server, it's likely there's a network-level interruption
+   and it should not promote itself. If it can see the witness but not the primary,
+   this proves there is no network interruption and the primary itself is unavailable,
+   and it can therefore promote itself (and ideally take action to fence the
+   former primary).
+ </para>
+ <note>
+   <para>
+     <emphasis>Never</emphasis> install a witness server on the same physical host
+     as another node in the replication cluster managed by &repmgr; - it's essential
+     the witness is not affected in any way by failure of another node.
+   </para>
+ </note>
+ <para>
+   For more complex replication scenarios, e.g. with multiple datacentres, it may
+   be preferable to use location-based failover, which ensures that only nodes
+   in the same location as the primary will ever be promotion candidates;
+   see <xref linkend="repmgrd-network-split"/> for more details.
+ </para>
+
+ <note>
+   <simpara>
+     A witness server will only be useful if &repmgrd;
+     is in use.
+   </simpara>
+ </note>
+
+ <sect2 id="creating-witness-server">
+   <title>Creating a witness server</title>
+ <para>
+   To create a witness server, set up a normal PostgreSQL instance on a server
+   in the same physical location as the cluster's primary server.
+ </para>
+ <para>
+   This instance should <emphasis>not</emphasis> be on the same physical host as the primary server,
+   as otherwise if the primary server fails due to hardware issues, the witness
+   server will be lost too.
+ </para>
+ <note>
+   <simpara>
+     &repmgr; 3.3 and earlier provided a <command>repmgr create witness</command>
+     command, which would automatically create a PostgreSQL instance. However
+     this often resulted in an unsatisfactory, hard-to-customise instance.
+   </simpara>
+ </note>
+ <para>
+   The witness server should be configured in the same way as a normal
+   &repmgr; node; see section <xref linkend="configuration"/>.
+ </para>
+ <para>
+   Register the witness server with <xref linkend="repmgr-witness-register"/>.
+   This will create the &repmgr; extension on the witness server, and make
+   a copy of the &repmgr; metadata.
+ </para>
+ <note>
+   <simpara>
+    As the witness server is not part of the replication cluster, further
+    changes to the &repmgr; metadata will be synchronised by
+    &repmgrd;.
+   </simpara>
+ </note>
+ <para>
+   Once the witness server has been configured, &repmgrd;
+   should be started.
+ </para>
+
+ <para>
+  To unregister a witness server, use <xref linkend="repmgr-witness-unregister"/>.
+ </para>
+
+ </sect2>
+
+</sect1>
+
+
+<sect1 id="repmgrd-network-split" xreflabel="Handling network splits with repmgrd">
+ <title>Handling network splits with repmgrd</title>
+ <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>network splits</secondary>
+ </indexterm>
+
+ <indexterm>
+   <primary>network splits</primary>
+ </indexterm>
+
+ <para>
+  A common pattern for replication cluster setups is to spread servers over
+  more than one datacentre. This can provide benefits such as geographically-
+  distributed read replicas and DR (disaster recovery capability). However
+  this also means there is a risk of disconnection at network level between
+  datacentre locations, which would result in a split-brain scenario if
+  servers in a secondary data centre were no longer able to see the primary
+  in the main data centre and promoted a standby among themselves.
+ </para>
+ <para>
+  &repmgr; enables provision of &quot;<xref linkend="witness-server"/>&quot; to
+  artificially create a quorum of servers in a particular location, ensuring
+  that nodes in another location will not elect a new primary if they
+  are unable to see the majority of nodes. However this approach does not
+  scale well, particularly with more complex replication setups, e.g.
+  where the majority of nodes are located outside of the primary datacentre.
+  It also means the <literal>witness</literal> node needs to be managed as an
+  extra PostgreSQL instance outside of the main replication cluster, which
+  adds administrative and programming complexity.
+ </para>
+ <para>
+  <literal>repmgr4</literal> introduces the concept of <literal>location</literal>:
+  each node is associated with an arbitrary location string (default is
+  <literal>default</literal>); this is set in <filename>repmgr.conf</filename>, e.g.:
+  <programlisting>
+    node_id=1
+    node_name=node1
+    conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'
+    data_directory='/var/lib/postgresql/data'
+    location='dc1'</programlisting>
+ </para>
+ <para>
+  In a failover situation, &repmgrd; will check if any servers in the
+  same location as the current primary node are visible.  If not, &repmgrd;
+  will assume a network interruption and not promote any node in any
+  other location (it will however enter <link linkend="repmgrd-degraded-monitoring">degraded monitoring</link>
+  mode until a primary becomes visible).
+ </para>
+
+</sect1>
+
+
+<sect1 id="repmgrd-primary-visibility-consensus" xreflabel="Primary visibility consensus">
+  <title>Primary visibility consensus</title>
+
+  <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>primary visibility consensus</secondary>
+  </indexterm>
+
+  <indexterm>
+   <primary>primary_visibility_consensus</primary>
+  </indexterm>
+
+  <para>
+    In more complex replication setups, particularly where replication occurs between
+    multiple datacentres, it's possible that some but not all standbys get cut off from the
+    primary (but not from the other standbys).
+  </para>
+  <para>
+    In this situation, normally it's not desirable for any of the standbys which have been
+    cut off to initiate a failover, as the primary is still functioning and standbys are
+    connected. Beginning with <link linkend="release-4.4">&repmgr; 4.4</link>
+    it is now possible for the affected standbys to build a consensus about whether
+    the primary is still available to some standbys (&quot;primary visibility consensus&quot;).
+    This is done by polling each standby for the time it last saw the primary;
+    if any have seen the primary very recently, it's reasonable
+    to infer that the primary is still available and a failover should not be started.
+  </para>
+
+  <para>
+    The time the primary was last seen by each node can be checked by executing
+    <link linkend="repmgr-service-status"><command>repmgr service status</command></link>
+    (&repmgr; 4.2 - 4.4: <link linkend="repmgr-service-status"><command>repmgr daemon status</command></link>)
+    which includes this in its output, e.g.:
+    <programlisting>$ repmgr -f /etc/repmgr.conf service status
+ ID | Name  | Role    | Status    | Upstream | repmgrd | PID   | Paused? | Upstream last seen
+----+-------+---------+-----------+----------+---------+-------+---------+--------------------
+ 1  | node1 | primary | * running |          | running | 96563 | no      | n/a
+ 2  | node2 | standby |   running | node1    | running | 96572 | no      | 1 second(s) ago
+ 3  | node3 | standby |   running | node1    | running | 96584 | no      | 0 second(s) ago</programlisting>
+
+  </para>
+
+  <para>
+    To enable this functionality, in <filename>repmgr.conf</filename> set:
+    <programlisting>
+      primary_visibility_consensus=true</programlisting>
+  </para>
+  <note>
+    <para>
+      <option>primary_visibility_consensus</option> <emphasis>must</emphasis> be set to
+      <literal>true</literal> on all nodes for it to be effective.
+    </para>
+  </note>
+
+  <para>
+    The following sample &repmgrd; log output demonstrates the behaviour in a situation
+    where one of three standbys is no longer able to connect to the primary, but <emphasis>can</emphasis>
+    connect to the two other standbys (&quot;sibling nodes&quot;):
+    <programlisting>
+    [2019-05-17 05:36:12] [WARNING] unable to reconnect to node 1 after 3 attempts
+    [2019-05-17 05:36:12] [INFO] 2 active sibling nodes registered
+    [2019-05-17 05:36:12] [INFO] local node's last receive lsn: 0/7006E58
+    [2019-05-17 05:36:12] [INFO] checking state of sibling node "node3" (ID: 3)
+    [2019-05-17 05:36:12] [INFO] node "node3" (ID: 3) reports its upstream is node 1, last seen 1 second(s) ago
+    [2019-05-17 05:36:12] [NOTICE] node 3 last saw primary node 1 second(s) ago, considering primary still visible
+    [2019-05-17 05:36:12] [INFO] last receive LSN for sibling node "node3" (ID: 3) is: 0/7006E58
+    [2019-05-17 05:36:12] [INFO] node "node3" (ID: 3) has same LSN as current candidate "node2" (ID: 2)
+    [2019-05-17 05:36:12] [INFO] checking state of sibling node "node4" (ID: 4)
+    [2019-05-17 05:36:12] [INFO] node "node4" (ID: 4) reports its upstream is node 1, last seen 0 second(s) ago
+    [2019-05-17 05:36:12] [NOTICE] node 4 last saw primary node 0 second(s) ago, considering primary still visible
+    [2019-05-17 05:36:12] [INFO] last receive LSN for sibling node "node4" (ID: 4) is: 0/7006E58
+    [2019-05-17 05:36:12] [INFO] node "node4" (ID: 4) has same LSN as current candidate "node2" (ID: 2)
+    [2019-05-17 05:36:12] [INFO] 2 nodes can see the primary
+    [2019-05-17 05:36:12] [DETAIL] following nodes can see the primary:
+     - node "node3" (ID: 3): 1 second(s) ago
+     - node "node4" (ID: 4): 0 second(s) ago
+    [2019-05-17 05:36:12] [NOTICE] cancelling failover as some nodes can still see the primary
+    [2019-05-17 05:36:12] [NOTICE] election cancelled
+    [2019-05-17 05:36:14] [INFO] node "node2" (ID: 2) monitoring upstream node "node1" (ID: 1) in degraded state</programlisting>
+    In this situation it will cancel the failover and enter degraded monitoring node,
+    waiting for the primary to reappear.
+  </para>
+</sect1>
+
+<sect1 id="repmgrd-standby-disconnection-on-failover" xreflabel="Standby disconnection on failover">
+  <title>Standby disconnection on failover</title>
+
+  <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>standby disconnection on failover</secondary>
+ </indexterm>
+
+  <indexterm>
+    <primary>standby disconnection on failover</primary>
+  </indexterm>
+
+  <para>
+    If <option>standby_disconnect_on_failover</option> is set to <literal>true</literal> in
+    <filename>repmgr.conf</filename>, in a failover situation &repmgrd; will forcibly disconnect
+    the local node's WAL receiver, and wait for the WAL receiver on all sibling nodes to be
+	disconnected, before making a failover decision.
+  </para>
+  <note>
+    <para>
+      <option>standby_disconnect_on_failover</option> is available with PostgreSQL 9.5 and later.
+      Additionally this requires that the <literal>repmgr</literal> database user is a superuser.
+    </para>
+  </note>
+  <para>
+    By doing this, it's possible to ensure that, at the point the failover decision is made, no nodes
+    are receiving data from the primary and their LSN location will be static.
+  </para>
+  <important>
+    <para>
+      <option>standby_disconnect_on_failover</option> <emphasis>must</emphasis> be set to the same value on
+      all nodes.
+    </para>
+  </important>
+  <para>
+    Note that when using <option>standby_disconnect_on_failover</option> there will be a delay of 5 seconds
+    plus however many seconds it takes to confirm the WAL receiver is disconnected before
+    &repmgrd; proceeds with the failover decision.
+  </para>
+  <para>
+	&repmgrd; will wait up to <option>sibling_nodes_disconnect_timeout</option> seconds (default:
+	<literal>30</literal>) to confirm that the WAL receiver on all sibling nodes hase been
+	disconnected before proceding with the failover operation. If the timeout is reached, the
+	failover operation will go ahead anyway.
+  </para>
+  <para>
+    Following the failover operation, no matter what the outcome, each node will reconnect its WAL receiver.
+  </para>
+  <para>
+    If using <option>standby_disconnect_on_failover</option>, we recommend that the
+    <option>primary_visibility_consensus</option> option is also used.
+  </para>
+
+</sect1>
+
+<sect1 id="repmgrd-failover-validation" xreflabel="Failover validation">
+  <title>Failover validation</title>
+
+  <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>failover validation</secondary>
+ </indexterm>
+
+  <indexterm>
+    <primary>failover validation</primary>
+  </indexterm>
+
+  <para>
+    From <link linkend="release-4.3">repmgr 4.3</link>, &repmgr; makes it possible to provide a script
+    to &repmgrd; which, in a failover situation,
+    will be executed by the promotion candidate (the node which has been selected
+    to be the new primary) to confirm whether the node should actually be promoted.
+  </para>
+  <para>
+    To use this, <option>failover_validation_command</option> in <filename>repmgr.conf</filename>
+    to a script executable by the <literal>postgres</literal> system user, e.g.:
+    <programlisting>
+      failover_validation_command=/path/to/script.sh %n %a</programlisting>
+  </para>
+  <para>
+    The <literal>%n</literal> parameter will be replaced with the node ID, and the
+    <literal>%a</literal> parameter will be replaced by the node name when the script is executed.
+  </para>
+  <para>
+    This script must return an exit code of <literal>0</literal> to indicate the node should promote itself.
+    Any other value will result in the promotion being aborted and the election rerun.
+    There is a pause of <option>election_rerun_interval</option> seconds before the election is rerun.
+  </para>
+  <para>
+    Sample &repmgrd; log file output during which the failover validation
+    script rejects the proposed promotion candidate:
+    <programlisting>
+[2019-03-13 21:01:30] [INFO] visible nodes: 2; total nodes: 2; no nodes have seen the primary within the last 4 seconds
+[2019-03-13 21:01:30] [NOTICE] promotion candidate is "node2" (ID: 2)
+[2019-03-13 21:01:30] [NOTICE] executing "failover_validation_command"
+[2019-03-13 21:01:30] [DETAIL] /usr/local/bin/failover-validation.sh 2
+[2019-03-13 21:01:30] [INFO] output returned by failover validation command:
+Node ID: 2
+
+[2019-03-13 21:01:30] [NOTICE] failover validation command returned a non-zero value: "1"
+[2019-03-13 21:01:30] [NOTICE] promotion candidate election will be rerun
+[2019-03-13 21:01:30] [INFO] 1 followers to notify
+[2019-03-13 21:01:30] [NOTICE] notifying node "node3" (ID: 3) to rerun promotion candidate selection
+INFO:  node 3 received notification to rerun promotion candidate election
+[2019-03-13 21:01:30] [NOTICE] rerunning election after 15 seconds ("election_rerun_interval")</programlisting>
+  </para>
+
+
+</sect1>
+
+ <sect1 id="cascading-replication" xreflabel="Cascading replication">
+  <title>repmgrd and cascading replication</title>
+
+  <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>cascading replication</secondary>
+  </indexterm>
+
+ <indexterm>
+   <primary>cascading replication</primary>
+   <secondary>repmgrd</secondary>
+ </indexterm>
+
+ <para>
+  Cascading replication - where a standby can connect to an upstream node and not
+  the primary server itself - was introduced in PostgreSQL 9.2. &repmgr; and
+  &repmgrd; support cascading replication by keeping track of the relationship
+  between standby servers - each node record is stored with the node id of its
+  upstream ("parent") server (except of course the primary server).
+ </para>
+ <para>
+  In a failover situation where the primary node fails and a top-level standby
+  is promoted, a standby connected to another standby will not be affected
+  and continue working as normal (even if the upstream standby it's connected
+  to becomes the primary node). If however the node's direct upstream fails,
+  the &quot;cascaded standby&quot; will attempt to reconnect to that node's parent
+  (unless <varname>failover</varname> is set to <literal>manual</literal> in
+  <filename>repmgr.conf</filename>).
+ </para>
+
+  </sect1>
+
+<sect1 id="repmgrd-primary-child-disconnection" xreflabel="Monitoring standby disconnections on the primary">
+  <title>Monitoring standby disconnections on the primary node</title>
+
+  <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>standby disconnection</secondary>
+  </indexterm>
+
+  <indexterm>
+   <primary>repmgrd</primary>
+   <secondary>child node disconnection</secondary>
+  </indexterm>
+
+  <note>
+    <para>
+      This functionality is available in <link linkend="release-4.4">&repmgr; 4.4</link> and later.
+    </para>
+  </note>
+  <para>
+    When running on the primary node, &repmgrd; can
+    monitor connections and in particular disconnections by its attached
+    child nodes (standbys, and if in use, the witness server), and optionally
+    execute a custom command if certain criteria are met (such as the number of
+    attached nodes falling to zero following a failover to a new primary); this
+    command can be used for example to &quot;fence&quot; the node and ensure it
+    is isolated from any applications attempting to access the replication cluster.
+  </para>
+
+  <note>
+	<para>
+	  Currently &repmgrd; can only detect disconnections
+	  of streaming replication standbys and cannot determine whether a standby
+	  has disconnected and fallen back to archive recovery.
+	</para>
+	<para>
+	  See section <link linkend="repmgrd-primary-child-disconnection-caveats">caveats</link> below.
+	</para>
+  </note>
+
+  <sect2 id="repmgrd-primary-child-disconnection-monitoring-process">
+	<title>Standby disconnections monitoring process and criteria</title>
+	<para>
+	  &repmgrd; monitors attached child nodes and decides
+	  whether to invoke the user-defined command based on the following process
+	  and criteria:
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Every few seconds (defined by the configuration parameter <varname>child_nodes_check_interval</varname>;
+          default: <literal>5</literal> seconds, a value of <literal>0</literal> disables this altogether), &repmgrd; queries
+          the <literal>pg_stat_replication</literal> system view and compares
+          the nodes present there against the list of nodes registered with &repmgr; which
+          should be attached to the primary.
+        </para>
+        <para>
+          If a witness server is in use, &repmgrd; connects to it and checks which upstream node
+          it is following.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If a child node (standby) is no longer present in <literal>pg_stat_replication</literal>,
+          &repmgrd; notes the time it detected the node's absence, and additionally generates a
+          <literal>child_node_disconnect</literal> event.
+        </para>
+        <para>
+          If a witness server is in use, and it is no longer following the primary, or not
+          reachable at all, &repmgrd; notes the time it detected the node's absence, and additionally generates a
+          <literal>child_node_disconnect</literal> event.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If a child node (standby) which was absent from <literal>pg_stat_replication</literal> reappears,
+          &repmgrd; clears the time it detected the node's absence, and additionally generates a
+          <literal>child_node_reconnect</literal> event.
+        </para>
+        <para>
+          If a witness server is in use, which was previously not reachable or not following the
+          primary node, has become reachable and is following the primary node,  &repmgrd; clears the
+          time it detected the node's absence, and additionally generates a
+          <literal>child_node_reconnect</literal> event.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If an entirely new child node (standby or witness) is detected, &repmgrd; adds it to its internal list
+          and additionally generates a <literal>child_node_new_connect</literal> event.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If the <varname>child_nodes_disconnect_command</varname> parameter is set in
+          <filename>repmgr.conf</filename>, &repmgrd; will then loop through all child nodes.
+          If it determines that insufficient child nodes are connected, and a
+          minimum of <varname>child_nodes_disconnect_timeout</varname> seconds (default: <literal>30</literal>)
+          has elapsed since  the last node became disconnected, &repmgrd; will then execute the
+          <varname>child_nodes_disconnect_command</varname> script.
+        </para>
+        <para>
+          By default, the <varname>child_nodes_disconnect_command</varname> will only be executed
+          if all child nodes are disconnected. If <varname>child_nodes_connected_min_count</varname>
+          is set, the <varname>child_nodes_disconnect_command</varname> script will be triggered
+          if the number of connected child nodes falls below the specified value (e.g.
+          if set to <literal>2</literal>, the script will be triggered if only one child node
+          is connected). Alternatively, if <varname>child_nodes_disconnect_min_count</varname>
+          and more than that number of child nodes disconnects, the script will be triggered.
+        </para>
+        <note>
+          <para>
+            By default, a witness node, if in use, will <emphasis>not</emphasis> be counted as a
+            child node for the purposes of determining whether to execute
+            <varname>child_nodes_disconnect_command</varname>.
+          </para>
+          <para>
+            To enable the witness node to be counted as a child node, set
+            <varname>child_nodes_connected_include_witness</varname> in <filename>repmgr.conf</filename>
+            to <literal>true</literal>
+            (and <link linkend="repmgrd-reloading-configuration">reload the configuration</link> if &repmgrd;
+            is running).
+          </para>
+        </note>
+      </listitem>
+
+      <listitem>
+        <para>
+          Note that child nodes which are not attached when &repmgrd;
+          starts will <emphasis>not</emphasis> be considered as missing, as &repmgrd;
+          cannot know why they are not attached.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+	</para>
+  </sect2>
+
+  <sect2 id="repmgrd-primary-child-disconnection-example">
+	<title>Standby disconnections monitoring process example</title>
+	<para>
+	  This example shows typical &repmgrd; log output from a three-node cluster
+	  (primary and two child nodes), with <varname>child_nodes_connected_min_count</varname>
+	  set to <literal>2</literal>.
+	</para>
+	<para>
+	  &repmgrd; on the primary has started up, while two child
+	  nodes are being provisioned:
+	  <programlisting>
+[2019-04-24 15:25:33] [INFO] monitoring primary node "node1" (ID: 1) in normal state
+[2019-04-24 15:25:35] [NOTICE] new node "node2" (ID: 2) has connected
+[2019-04-24 15:25:35] [NOTICE] 1 (of 1) child nodes are connected, but at least 2 child nodes required
+[2019-04-24 15:25:35] [INFO] no child nodes have detached since repmgrd startup
+(...)
+[2019-04-24 15:25:44] [NOTICE] new node "node3" (ID: 3) has connected
+[2019-04-24 15:25:46] [INFO] monitoring primary node "node1" (ID: 1) in normal state
+(...)</programlisting>
+	</para>
+	<para>
+	  One of the child nodes has disconnected; &repmgrd;
+	  is now waiting <varname>child_nodes_disconnect_timeout</varname> seconds
+	  before executing <varname>child_nodes_disconnect_command</varname>:
+	  <programlisting>
+[2019-04-24 15:28:11] [INFO] monitoring primary node "node1" (ID: 1) in normal state
+[2019-04-24 15:28:17] [INFO] monitoring primary node "node1" (ID: 1) in normal state
+[2019-04-24 15:28:19] [NOTICE] node "node3" (ID: 3) has disconnected
+[2019-04-24 15:28:19] [NOTICE] 1 (of 2) child nodes are connected, but at least 2 child nodes required
+[2019-04-24 15:28:19] [INFO] most recently detached child node was 3 (ca. 0 seconds ago), not triggering "child_nodes_disconnect_command"
+[2019-04-24 15:28:19] [DETAIL] "child_nodes_disconnect_timeout" set To 30 seconds
+(...)</programlisting>
+	</para>
+	<para>
+	  <varname>child_nodes_disconnect_command</varname> is executed once:
+	  <programlisting>
+[2019-04-24 15:28:49] [INFO] most recently detached child node was 3 (ca. 30 seconds ago), triggering "child_nodes_disconnect_command"
+[2019-04-24 15:28:49] [INFO] "child_nodes_disconnect_command" is:
+	"/usr/bin/fence-all-the-things.sh"
+[2019-04-24 15:28:51] [NOTICE] 1 (of 2) child nodes are connected, but at least 2 child nodes required
+[2019-04-24 15:28:51] [INFO] "child_nodes_disconnect_command" was previously executed, taking no action</programlisting>
+	</para>
+
+  </sect2>
+
+  <sect2 id="repmgrd-primary-child-disconnection-caveats">
+	<title>Standby disconnections monitoring caveats</title>
+	<para>
+	  The follwing caveats should be considered if you are intending to use this functionality.
+	</para>
+	<para>
+	  <itemizedlist mark="bullet">
+		<listitem>
+          <para>
+			If a child node is configured to use archive recovery, it's possible that
+			the child node will disconnect from the primary node and fall back to
+			archive recovery. In this case &repmgrd;
+			will nevertheless register a node disconnection.
+		  </para>
+		</listitem>
+
+        <listitem>
+          <para>
+			&repmgr; relies on <varname>application_name</varname> in the child node's
+			<varname>primary_conninfo</varname> string to be the same as the node name
+			defined in the node's <filename>repmgr.conf</filename> file. Furthermore,
+			this <varname>application_name</varname> must be unique across the replication
+			cluster.
+          </para>
+		  <para>
+			If a custom <varname>application_name</varname> is used, or the
+			<varname>application_name</varname> is not unique across the replication
+			cluster, &repmgr; will not be able to reliably monitor child node connections.
+		  </para>
+        </listitem>
+
+	  </itemizedlist>
+	</para>
+  </sect2>
+
+
+  <sect2 id="repmgrd-primary-child-disconnection-configuration">
+	<title>Standby disconnections monitoring process configuration</title>
+	<para>
+	  The following parameters, set in <filename>repmgr.conf</filename>,
+	  control how child node disconnection monitoring operates.
+	</para>
+	<variablelist>
+
+      <varlistentry>
+        <term><varname>child_nodes_check_interval</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_nodes_check_interval</primary>
+		    <secondary>child node disconnection monitoring</secondary>
+		  </indexterm>
+
+		  <para>
+			Interval (in seconds) after which &repmgrd; queries the
+			<literal>pg_stat_replication</literal> system view and compares the nodes present
+			there against the list of nodes registered with repmgr which should be attached to the primary.
+		  </para>
+		  <para>
+			Default is <literal>5</literal> seconds, a value of <literal>0</literal> disables this check
+			altogether.
+		  </para>
+		</listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+        <term><varname>child_nodes_disconnect_command</varname></term>
+
+        <listitem>
+          <indexterm>
+		    <primary>child_nodes_disconnect_command</primary>
+		    <secondary>child node disconnection monitoring</secondary>
+		  </indexterm>
+
+		  <para>
+			User-definable script to be executed when &repmgrd;
+			determines that an insufficient number of child nodes are connected. By default
+			the script is executed when no child nodes are executed, but the execution
+			threshold can be modified by setting one of <varname>child_nodes_connected_min_count</varname>
+			or<varname>child_nodes_disconnect_min_count</varname> (see below).
+		  </para>
+		  <para>
+			The <varname>child_nodes_disconnect_command</varname> script can be
+			any user-defined script or program. It <emphasis>must</emphasis> be able
+			to be executed by the system user under which the PostgreSQL server itself
+			runs (usually <literal>postgres</literal>).
+		  </para>
+		  <note>
+			<para>
+			  If <varname>child_nodes_disconnect_command</varname> is not set, no action
+			  will be taken.
+			</para>
+		  </note>
+		  <para>
+			If specified, the following format placeholder will be substituted when
+			executing <varname>child_nodes_disconnect_command</varname>:
+		  </para>
+
+		   <variablelist>
+			 <varlistentry>
+			   <term><option>%p</option></term>
+			   <listitem>
+				 <para>
+				   ID of the node executing the <varname>child_nodes_disconnect_command</varname> script.
+				 </para>
+			   </listitem>
+			 </varlistentry>
+		   </variablelist>
+
+		  <para>
+			The <varname>child_nodes_disconnect_command</varname> script will only be executed once
+			while the criteria for its execution are met. If the criteria for its execution are no longer
+			met (i.e. some child nodes have reconnected), it will be executed again if
+			the criteria for its execution are met again.
+          </para>
+          <para>
+			The <varname>child_nodes_disconnect_command</varname> script will not be executed if
+			&repmgrd; is <link linkend="repmgrd-pausing">paused</link>.
+          </para>
+
+		</listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+        <term><varname>child_nodes_disconnect_timeout</varname></term>
+
+        <listitem>
+          <indexterm>
+		    <primary>child_nodes_disconnect_timeout</primary>
+		    <secondary>child node disconnection monitoring</secondary>
+		  </indexterm>
+
+		  <para>
+			If &repmgrd; determines that an insufficient number of
+			child nodes are connected, it will wait for the specified number of seconds
+			to execute the <varname>child_nodes_disconnect_command</varname>.
+		  </para>
+		  <para>
+			Default: <literal>30</literal> seconds.
+		  </para>
+		</listitem>
+	  </varlistentry>
+
+      <varlistentry>
+        <term><varname>child_nodes_connected_min_count</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_nodes_connected_min_count</primary>
+		    <secondary>child node disconnection monitoring</secondary>
+		  </indexterm>
+
+		  <para>
+			If the number of child nodes connected falls below the number specified in
+			this parameter, the <varname>child_nodes_disconnect_command</varname> script
+			will be executed.
+		  </para>
+		  <para>
+			For example, if <varname>child_nodes_connected_min_count</varname> is set
+			to <literal>2</literal>, the <varname>child_nodes_disconnect_command</varname>
+			script will be executed if one or no child nodes are connected.
+		  </para>
+		  <para>
+			Note that <varname>child_nodes_connected_min_count</varname> overrides any value
+			set in <varname>child_nodes_disconnect_min_count</varname>.
+		  </para>
+		  <para>
+			If neither of <varname>child_nodes_connected_min_count</varname> or
+			<varname>child_nodes_disconnect_min_count</varname> are set,
+			the <varname>child_nodes_disconnect_command</varname> script
+			will be executed when no child nodes are connected.
+		  </para>
+          <para>
+            A witness node, if in use, will not be counted as a child node unless
+            <varname>child_nodes_connected_include_witness</varname> is set to <literal>true</literal>.
+          </para>
+		</listitem>
+	  </varlistentry>
+
+
+	  <varlistentry>
+        <term><varname>child_nodes_disconnect_min_count</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_nodes_disconnect_min_count</primary>
+		    <secondary>child node disconnection monitoring</secondary>
+		  </indexterm>
+
+		  <para>
+			If the number of disconnected child nodes exceeds the number specified in
+			this parameter, the <varname>child_nodes_disconnect_command</varname> script
+			will be executed.
+		  </para>
+
+		  <para>
+			For example, if <varname>child_nodes_disconnect_min_count</varname> is set
+			to <literal>2</literal>, the <varname>child_nodes_disconnect_command</varname>
+			script will be executed if more than two child nodes are disconnected.
+		  </para>
+
+		  <para>
+			Note that any value set in <varname>child_nodes_disconnect_min_count</varname>
+			will be overriden by <varname>child_nodes_connected_min_count</varname>.
+		  </para>
+		  <para>
+			If neither of <varname>child_nodes_connected_min_count</varname> or
+			<varname>child_nodes_disconnect_min_count</varname> are set,
+			the <varname>child_nodes_disconnect_command</varname> script
+			will be executed when no child nodes are connected.
+		  </para>
+
+          <para>
+            A witness node, if in use, will not be counted as a child node unless
+            <varname>child_nodes_connected_include_witness</varname> is set to <literal>true</literal>.
+          </para>
+
+		</listitem>
+	  </varlistentry>
+
+
+	  <varlistentry>
+        <term><varname>child_nodes_connected_include_witness</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_nodes_connected_include_witness</primary>
+		    <secondary>child node disconnection monitoring</secondary>
+		  </indexterm>
+
+		  <para>
+            Whether to count the witness node (if in use) as a child node when
+            determining whether to execute <varname>child_nodes_disconnect_command</varname>.
+          </para>
+          <para>
+            Default to <literal>false</literal>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+	</variablelist>
+
+  </sect2>
+
+  <sect2 id="repmgrd-primary-child-disconnection-events">
+	<title>Standby disconnections monitoring process event notifications</title>
+	<para>
+	  The following <link linkend="event-notifications">event notifications</link> may be generated:
+	</para>
+	<variablelist>
+
+      <varlistentry>
+        <term><varname>child_node_disconnect</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_node_disconnect</primary>
+		    <secondary>event notification</secondary>
+		  </indexterm>
+
+          <para>
+			This event is generated after &repmgrd;
+			detects that a child node is no longer streaming from the primary node.
+          </para>
+		  <para>
+			Example:
+			<programlisting>
+$ repmgr cluster event --event=child_node_disconnect
+ Node ID | Name  | Event                 | OK | Timestamp           | Details
+---------+-------+-----------------------+----+---------------------+--------------------------------------------
+ 1       | node1 | child_node_disconnect | t  | 2019-04-24 12:41:36 | node "node3" (ID: 3) has disconnected</programlisting>
+		  </para>
+        </listitem>
+      </varlistentry>
+
+	  <varlistentry>
+        <term><varname>child_node_reconnect</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_node_reconnect</primary>
+		    <secondary>event notification</secondary>
+		  </indexterm>
+
+          <para>
+			This event is generated after &repmgrd;
+			detects that a child node has resumed streaming from the primary node.
+          </para>
+		  <para>
+			Example:
+			<programlisting>
+$ repmgr cluster event --event=child_node_reconnect
+ Node ID | Name  | Event                | OK | Timestamp           | Details
+---------+-------+----------------------+----+---------------------+------------------------------------------------------------
+ 1       | node1 | child_node_reconnect | t  | 2019-04-24 12:42:19 | node "node3" (ID: 3) has reconnected after 42 seconds</programlisting>
+		  </para>
+        </listitem>
+      </varlistentry>
+
+	  <varlistentry>
+        <term><varname>child_node_new_connect</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_node_new_connect</primary>
+		    <secondary>event notification</secondary>
+		  </indexterm>
+
+          <para>
+			This event is generated after &repmgrd;
+			detects that a new child node has been registered with &repmgr; and has
+			connected to the primary.
+          </para>
+		  <para>
+			Example:
+			<programlisting>
+$ repmgr cluster event --event=child_node_new_connect
+ Node ID | Name  | Event                  | OK | Timestamp           | Details
+---------+-------+------------------------+----+---------------------+---------------------------------------------
+ 1       | node1 | child_node_new_connect | t  | 2019-04-24 12:41:30 | new node "node3" (ID: 3) has connected</programlisting>
+		  </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>child_nodes_disconnect_command</varname></term>
+        <listitem>
+          <indexterm>
+		    <primary>child_nodes_disconnect_command</primary>
+		    <secondary>event notification</secondary>
+		  </indexterm>
+
+          <para>
+			This event is generated after &repmgrd; detects
+			that sufficient child nodes have been disconnected for a sufficient amount
+			of time to trigger execution of the <varname>child_nodes_disconnect_command</varname>.
+          </para>
+		  <para>
+			Example:
+			<programlisting>
+$ repmgr cluster event --event=child_nodes_disconnect_command
+ Node ID | Name  | Event                          | OK | Timestamp           | Details
+---------+-------+--------------------------------+----+---------------------+--------------------------------------------------------
+ 1       | node1 | child_nodes_disconnect_command | t  | 2019-04-24 13:08:17 | "child_nodes_disconnect_command" successfully executed</programlisting>
+		  </para>
+        </listitem>
+      </varlistentry>
+
+	</variablelist>
+
+  </sect2>
+
+
+</sect1>
+
+
+</chapter>
--- a/doc/repmgrd-bdr.sgml
+++ b/doc/repmgrd-bdr.sgml
@@ -1,4 +1,6 @@
 <chapter id="repmgrd-bdr">
+  <title>BDR failover with repmgrd</title>
+
  <indexterm>
    <primary>repmgrd</primary>
    <secondary>BDR</secondary>
@@ -8,14 +10,13 @@
    <primary>BDR</primary>
  </indexterm>

-  <title>BDR failover with repmgrd</title>
  <para>
-    &repmgr; 4.x provides support for monitoring BDR nodes and taking action in
+    &repmgr; 4.x provides support for monitoring a pair of BDR 2.x nodes and taking action in
    case one of the nodes fails.
  </para>
  <note>
    <simpara>
-      Due to the nature of BDR, it's only safe to use this solution for
+      Due to the nature of BDR 1.x/2.x, it's only safe to use this solution for
      a two-node scenario. Introducing additional nodes will create an inherent
      risk of node desynchronisation if a node goes down without being cleanly
      removed from the cluster.
@@ -24,15 +25,28 @@
  <para>
    In contrast to streaming replication, there's no concept of "promoting" a new
    primary node with BDR. Instead, "failover" involves monitoring both nodes
-    with <application>repmgrd</application> and redirecting queries from the failed node to the remaining
+    with &repmgrd; and redirecting queries from the failed node to the remaining
    active node. This can be done by using an
    <link linkend="event-notifications">event notification</link> script
-    which is called by <application>repmgrd</application> to dynamically
+    which is called by &repmgrd; to dynamically
    reconfigure a proxy server/connection pooler such as <application>PgBouncer</application>.
  </para>

+  <note>
+    <simpara>
+      This &repmgr; functionality is for BDR 2.x only running on PostgreSQL 9.4/9.6.
+      It is <emphasis>not</emphasis> required for later BDR versions.
+    </simpara>
+  </note>
+
  <sect1 id="bdr-prerequisites" xreflabel="BDR prequisites">
    <title>Prerequisites</title>
+    <important>
+      <para>
+        This &repmgr; functionality is for BDR 2.x only running on PostgreSQL 9.4/9.6.
+        It is <emphasis>not</emphasis> required for later BDR versions.
+      </para>
+    </important>
    <para>
      &repmgr; 4 requires PostgreSQL 9.4 or 9.6 with the BDR 2 extension
      enabled and configured for a two-node BDR network. &repmgr; 4 packages
@@ -47,7 +61,7 @@
    <para>
      Application database connections *must* be passed through a proxy server/
      connection pooler such as <application>PgBouncer</application>, and it must be possible to dynamically
-      reconfigure that from <application>repmgrd</application>. The example demonstrated in this document
+      reconfigure that from &repmgrd;. The example demonstrated in this document
      will use <application>PgBouncer</application>
    </para>
    <para>
@@ -81,7 +95,7 @@

        # Event notification configuration
        event_notifications=bdr_failover
-        event_notification_command='/path/to/bdr-pgbouncer.sh %n %e %s "%c" "%a" >> /tmp/bdr-failover.log 2>&1'
+        event_notification_command='/path/to/bdr-pgbouncer.sh %n %e %s "%c" "%a" >> /tmp/bdr-failover.log 2>&amp;1'

        # repmgrd options
        monitor_interval_secs=5
@@ -107,7 +121,7 @@
      <simpara>
        <varname>event_notification_command</varname> is the script which does the actual "heavy lifting"
        of reconfiguring the proxy server/ connection pooler. It is fully
-        user-definable; see section <xref linkend="bdr-event-notification-command"> for a reference
+        user-definable; see section <xref linkend="bdr-event-notification-command"/> for a reference
        implementation.
      </simpara>
    </note>
@@ -145,7 +159,7 @@
    </important>
    <para>
      At this point the meta data for both nodes has been created; executing
-      <xref linkend="repmgr-cluster-show"> (on either node) should produce output like this:
+      <xref linkend="repmgr-cluster-show"/> (on either node) should produce output like this:
      <programlisting>
        $ repmgr -f /etc/repmgr.conf cluster show
        ID | Name  | Role | Status    | Upstream | Location | Connection string
@@ -155,7 +169,7 @@
    </para>
    <para>
      Additionally it's possible to display log of significant events;  executing
-      <xref linkend="repmgr-cluster-event"> (on either node) should produce output like this:
+      <xref linkend="repmgr-cluster-event"/> (on either node) should produce output like this:
      <programlisting>
        $ repmgr -f /etc/repmgr.conf cluster event
        Node ID | Event        | OK | Timestamp           | Details
@@ -283,7 +297,7 @@
        </listitem>
        <listitem>
          <simpara>recreates the <application>PgBouncer</application> configuration file on each
-            node using the information provided by <application>repmgrd</application>
+            node using the information provided by &repmgrd;
            (primarily the <varname>conninfo</varname> string) to configure
            <application>PgBouncer</application></simpara>
        </listitem>
@@ -305,21 +319,21 @@
    <title>Node monitoring and failover</title>
    <para>
      At the intervals specified by <varname>monitor_interval_secs</varname>
-      in <filename>repmgr.conf</filename>, <application>repmgrd</application>
+      in <filename>repmgr.conf</filename>, &repmgrd;
      will ping each node to check if it's available. If a node isn't available,
-      <application>repmgrd</application> will enter failover mode and check <varname>reconnect_attempts</varname>
+      &repmgrd; will enter failover mode and check <varname>reconnect_attempts</varname>
      times at intervals of <varname>reconnect_interval</varname> to confirm the node is definitely unreachable.
      This buffer period is necessary to avoid false positives caused by transient
      network outages.
    </para>
    <para>
-      If the node is still unavailable, <application>repmgrd</application> will enter failover mode and execute
+      If the node is still unavailable, &repmgrd; will enter failover mode and execute
      the script defined in <varname>event_notification_command</varname>; an entry will be logged
-      in the <literal>repmgr.events</literal> table and <application>repmgrd</application> will
+      in the <literal>repmgr.events</literal> table and &repmgrd; will
      (unless otherwise configured) resume monitoring of the node in "degraded" mode until it reappears.
    </para>
    <para>
-      <application>repmgrd</application> logfile output during a failover event will look something like this
+      &repmgrd; logfile output during a failover event will look something like this
      on one node (usually the node which has failed, here <literal>node2</literal>):
      <programlisting>
            ...
@@ -375,8 +389,8 @@
    </para>
    <para>
      This assumes only the PostgreSQL instance on <literal>node2</literal> has failed. In this case the
-      <application>repmgrd</application> instance running on <literal>node2</literal> has performed the failover. However if
-      the entire server becomes unavailable, <application>repmgrd</application> on <literal>node1</literal> will perform
+      &repmgrd; instance running on <literal>node2</literal> has performed the failover. However if
+      the entire server becomes unavailable, &repmgrd; on <literal>node1</literal> will perform
      the failover.
    </para>
  </sect1>
@@ -391,7 +405,7 @@
    </para>
    <para>
      If the failed node comes back up and connects correctly, output similar to this
-      will be visible in the <application>repmgrd</application> log:
+      will be visible in the &repmgrd; log:
      <programlisting>
        [2017-07-27 21:25:30] [DETAIL] monitoring node "node2" (ID: 2) in degraded mode
        [2017-07-27 21:25:46] [INFO] monitoring BDR replication status on node "node2" (ID: 2)
@@ -404,10 +418,10 @@
  <sect1 id="bdr-complete-shutdown" xreflabel="Shutdown of both nodes">
    <title>Shutdown of both nodes</title>
    <para>
-      If both PostgreSQL instances are shut down, <application>repmgrd</application> will try and handle the
+      If both PostgreSQL instances are shut down, &repmgrd; will try and handle the
      situation as gracefully as possible, though with no failover candidates available
      there's not much it can do. Should this case ever occur, we recommend shutting
-      down <application>repmgrd</application> on both nodes and restarting it once the PostgreSQL instances
+      down &repmgrd; on both nodes and restarting it once the PostgreSQL instances
      are running properly.
    </para>
  </sect1>
--- a/doc/repmgrd-cascading-replication.sgml
+++ b/doc/repmgrd-cascading-replication.sgml
@@ -1,22 +0,0 @@
-<chapter id="repmgrd-cascading-replication">
- <indexterm>
-   <primary>repmgrd</primary>
-   <secondary>cascading replication</secondary>
- </indexterm>
-
- <title>repmgrd and cascading replication</title>
- <para>
-  Cascading replication - where a standby can connect to an upstream node and not
-  the primary server itself - was introduced in PostgreSQL 9.2. &repmgr; and
-  <application>repmgrd</application> support cascading replication by keeping track of the relationship
-  between standby servers - each node record is stored with the node id of its
-  upstream ("parent") server (except of course the primary server).
- </para>
- <para>
-  In a failover situation where the primary node fails and a top-level standby
-  is promoted, a standby connected to another standby will not be affected
-  and continue working as normal (even if the upstream standby it's connected
-  to becomes the primary node). If however the node's direct upstream fails,
-  the "cascaded standby" will attempt to reconnect to that node's parent.
- </para>
-</chapter>
--- a/doc/repmgrd-configuration.sgml
+++ b/doc/repmgrd-configuration.sgml
@@ -1,347 +0,0 @@
-<chapter id="repmgrd-configuration">
-
-  <indexterm>
-    <primary>repmgrd</primary>
-    <secondary>configuration</secondary>
-  </indexterm>
-
-  <title>repmgrd configuration</title>
-
-  <para>
-    <application>repmgrd</application> is a daemon which runs on each PostgreSQL node,
-    monitoring the local node, and (unless it's the primary node) the upstream server
-    (the primary server or with cascading replication, another standby) which it's
-    connected to.
-  </para>
-  <para>
-    <application>repmgrd</application> can be configured to provide failover
-    capability in case the primary upstream node becomes unreachable, and/or
-    provide monitoring data to the &repmgr; metadatabase.
-  </para>
-
-  <sect1 id="repmgrd-basic-configuration">
-    <title>repmgrd basic configuration</title>
-
-    <para>
-      To use <application>repmgrd</application>, its associated function library <emphasis>must</emphasis> be
-      included via <filename>postgresql.conf</filename> with:
-
-      <programlisting>
-        shared_preload_libraries = 'repmgr'</programlisting>
-    </para>
-    <para>
-      Changing this setting requires a restart of PostgreSQL; for more details see
-      the <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">PostgreSQL documentation</ulink>.
-    </para>
-
-    <para>
-      To apply configuration file changes to a running <application>repmgrd</application>
-      daemon, execute the operating system's r<application>repmgrd</application> service reload command
-      (see <xref linkend="appendix-packages"> for examples),
-      or for instances  which were manually started, execute <command>kill -HUP</command>, e.g.
-      <command>kill -HUP `cat /tmp/repmgrd.pid`</command>.
-    </para>
-    <note>
-      <para>
-        Check the <application>repmgrd</application> log to see what changes were
-        applied, or if any issues were encountered when reloading the configuration.
-      </para>
-    </note>
-    <para>
-      Note that only a subset of configuration file parameters can be changed on a
-      running <application>repmgrd</application> daemon.
-    </para>
-
-
-    <sect2 id="repmgrd-automatic-failover-configuration">
-      <title>automatic failover configuration</title>
-      <para>
-        If using automatic failover, the following <application>repmgrd</application> options *must* be set in
-        <filename>repmgr.conf</filename> :
-        <programlisting>
-          failover=automatic
-          promote_command='/usr/bin/repmgr standby promote -f /etc/repmgr.conf --log-to-file'
-          follow_command='/usr/bin/repmgr standby follow -f /etc/repmgr.conf --log-to-file --upstream-node-id=%n'</programlisting>
-      </para>
-      <para>
-        Adjust file paths as appropriate; we recomment specifying the full path to the &repmgr; binary.
-      </para>
-      <para>
-        Note that the <literal>--log-to-file</literal> option will cause
-        output generated by the &repmgr; command, when executed by <application>repmgrd</application>,
-        to be logged to the same destination configured to receive log output for <application>repmgrd</application>.
-        See <filename><ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</ulink></filename>
-        for further <application>repmgrd</application>-specific settings.
-      </para>
-      <para>
-        When <varname>failover</varname> is set to <literal>automatic</literal>, upon detecting failure
-        of the current  primary, <application>repmgrd</application> will execute one of:
-      </para>
-      <itemizedlist spacing="compact" mark="bullet">
-        <listitem>
-          <simpara>
-            <varname>promote_command</varname> (if the current server is to become the new primary)
-          </simpara>
-        </listitem>
-        <listitem>
-          <simpara>
-            <varname>follow_command</varname> (if the current server needs to follow another server which has
-            become the new primary)
-          </simpara>
-        </listitem>
-      </itemizedlist>
-      <note>
-        <para>
-          These commands can be any valid shell script which results in one of these
-          two actions happening, but if &repmgr;'s <command>standby follow</command> or
-          <command>standby promote</command>
-          commands are not executed (either directly as shown here, or from a script which
-          performs other actions), the &repmgr; metadata will not be updated and
-          &repmgr; will no longer function reliably.
-        </para>
-      </note>
-
-      <para>
-        The <varname>follow_command</varname> should provide the <literal>--upstream-node-id=%n</literal>
-        option to <command>repmgr standby follow</command>; the <literal>%n</literal> will be replaced by
-        <application>repmgrd</application> with the ID of the new primary node. If this is not provided, &repmgr;
-        will attempt to determine the new primary by itself, but if the
-        original primary comes back online after the new primary is promoted, there is a risk that
-        <command>repmgr standby follow</command> will result in the node continuing to follow
-        the original primary.
-      </para>
-    </sect2>
-
-    <sect2 id="repmgrd-service-configuration">
-      <indexterm>
-        <primary>repmgrd</primary>
-        <secondary>PostgreSQL service configuration</secondary>
-      </indexterm>
-      <title>PostgreSQL service configuration</title>
-      <para>
-        If using automatic failover, currently <application>repmgrd</application> will need to execute
-        <link linkend="repmgr-standby-follow"><command>repmgr standby follow</command></link>
-        to restart PostgreSQL on standbys to have them follow a new primary.
-      </para>
-      <para>
-        To ensure this happens smoothly, it's essential to provide the appropriate system/service restart
-        command appropriate to your operating system via <varname>service_restart_command</varname>
-        in <filename>repmgr.conf</filename>. If you don't do this, <application>repmgrd</application>
-        will default to using <command>pg_ctl</command>, which can result in unexpected problems,
-        particularly on <application>systemd</application>-based systems.
-      </para>
-      <para>
-        For more details, see <xref linkend="configuration-file-service-commands">.
-      </para>
-    </sect2>
-
-    <sect2 id="repmgrd-monitoring-configuration">
-      <indexterm>
-        <primary>repmgrd</primary>
-        <secondary>monitoring configuration</secondary>
-      </indexterm>
-      <title>Monitoring configuration</title>
-      <para>
-        To enable monitoring, set:
-        <programlisting>
-          monitoring_history=yes</programlisting>
-        in <filename>repmgr.conf</filename>.
-      </para>
-      <para>
-        The default monitoring interval is 2 seconds; this value can be explicitly set using:
-        <programlisting>
-          monitor_interval_secs=&lt;seconds&gt;</programlisting>
-        in <filename>repmgr.conf</filename>.
-      </para>
-      <para>
-        For more details on monitoring, see <xref linkend="repmgrd-monitoring">.
-      </para>
-    </sect2>
-
-  </sect1>
-
-  <sect1 id="repmgrd-daemon">
-    <indexterm>
-      <primary>repmgrd</primary>
-      <secondary>starting and stopping</secondary>
-    </indexterm>
-    <title>repmgrd daemon</title>
-    <para>
-      If installed from a package, the <application>repmgrd</application> can be started
-      via the operating system's service command, e.g. in <application>systemd</application>
-      using <command>systemctl</command>.
-    </para>
-    <para>
-      See appendix <xref linkend="appendix-packages"> for details of service commands
-      for different distributions.
-    </para>
-    <para>
-      <application>repmgrd</application> can be started manually like this:
-      <programlisting>
-        repmgrd -f /etc/repmgr.conf --pid-file /tmp/repmgrd.pid</programlisting>
-      and stopped with <command>kill `cat /tmp/repmgrd.pid`</command>. Adjust paths as appropriate.
-    </para>
-
-    <sect2 id="repmgrd-pid-file" xreflabel="repmgrd's PID file">
-      <indexterm>
-        <primary>repmgrd</primary>
-        <secondary>PID file</secondary>
-      </indexterm>
-      <indexterm>
-        <primary>PID file</primary>
-        <secondary>repmgrd</secondary>
-      </indexterm>
-      <title>repmgrd's PID file</title>
-      <para>
-        <application>repmgrd</application> will generate a PID file by default.
-      </para>
-      <note>
-        <simpara>
-          This is a behaviour change from previous versions (earlier than 4.1), where
-          the PID file had to be explicitly specified with the command line
-          parameter <option> --pid-file</option>.
-        </simpara>
-      </note>
-      <para>
-        The PID file can be specified in <filename>repmgr.conf</filename> with the configuration
-        parameter <varname>repmgrd_pid_file</varname>.
-      </para>
-      <para>
-        It can also be specified on the command line (as in previous versions) with
-        the command line parameter <option>--pid-file</option>. Note this will override
-        any value set in <filename>repmgr.conf</filename> with <varname>repmgrd_pid_file</varname>.
-        <option>--pid-file</option> may be deprecated in future releases.
-      </para>
-      <para>
-        If a PID file location was specified by the package maintainer, <application>repmgrd</application>
-        will use that. This only applies if &repmgr; was installed from a package and the package
-        maintainer has specified the PID file location.
-      </para>
-      <para>
-        If none of the above apply, <application>repmgrd</application> will create a PID file
-        in the operating system's temporary directory (das etermined by the environment variable
-        <varname>TMPDIR</varname>, or if that is not set, will use <filename>/tmp</filename>).
-      </para>
-      <para>
-        To prevent a PID file being generated at all, provide the command line option
-        <option>--no-pid-file</option>.
-      </para>
-      <para>
-        To see which PID file <application>repmgrd</application> would use, execute <application>repmgrd</application>
-        with the option <option>--show-pid-file</option>. <application>repmgrd</application>
-        will not start if this option is provided. Note that the value shown is the
-        file  <application>repmgrd</application> would use next time it starts, and is
-        not necessarily the PID file currently in use.
-      </para>
-    </sect2>
-
-    <sect2 id="repmgrd-configuration-debian-ubuntu">
-      <indexterm>
-        <primary>repmgrd</primary>
-        <secondary>Debian/Ubuntu and daemon configuration</secondary>
-      </indexterm>
-      <indexterm>
-        <primary>Debian/Ubuntu</primary>
-        <secondary>repmgrd daemon configuration</secondary>
-      </indexterm>
-
-      <title>repmgrd daemon configuration on Debian/Ubuntu</title>
-
-      <para>
-        If &repmgr; was installed from Debian/Ubuntu packages, additional configuration
-        is required before <application>repmgrd</application> is started as a daemon.
-      </para>
-      <para>
-        This is done via the file <filename>/etc/default/repmgrd</filename>, which by default
-        looks like this:
-        <programlisting>
-# default settings for repmgrd. This file is source by /bin/sh from
-# /etc/init.d/repmgrd
-
-# disable repmgrd by default so it won't get started upon installation
-# valid values: yes/no
-REPMGRD_ENABLED=no
-
-# configuration file (required)
-#REPMGRD_CONF="/path/to/repmgr.conf"
-
-# additional options
-#REPMGRD_OPTS=""
-
-# user to run repmgrd as
-#REPMGRD_USER=postgres
-
-# repmgrd binary
-#REPMGRD_BIN=/usr/bin/repmgrd
-
-# pid file
-#REPMGRD_PIDFILE=/var/run/repmgrd.pid</programlisting>
-      </para>
-      <para>
-        Set <varname>REPMGRD_ENABLED</varname> to <literal>yes</literal>, and <varname>REPMGRD_CONF</varname>
-        to the <filename>repmgr.conf</filename> file you are using.
-      </para>
-      <para>
-        If using <application>systemd</application>, you may need to execute <command>systemctl daemon-reload</command>.
-        Also, if you attempted to start <application>repmgrd</application> using <command>systemctl start repmgrd</command>,
-        you'll need to execute <command>systemctl stop repmgrd</command>. Because that's how <application>systemd</application>
-        rolls.
-      </para>
-
-    </sect2>
-  </sect1>
-
-  <sect1 id="repmgrd-connection-settings">
-    <title>repmgrd connection settings</title>
- <para>
-  In addition to the &repmgr; configuration settings, parameters in the
-  <varname>conninfo</varname> string influence how &repmgr; makes a network connection to
-  PostgreSQL. In particular, if another server in the replication cluster
-  is unreachable at network level, system network settings will influence
-  the length of time it takes to determine that the connection is not possible.
- </para>
- <para>
-  In particular explicitly setting a parameter for <literal>connect_timeout</literal>
-  should be considered; the effective minimum value of <literal>2</literal>
-  (seconds) will ensure that a connection failure at network level is reported
-  as soon as possible, otherwise depending on the system settings (e.g.
-  <varname>tcp_syn_retries</varname> in Linux) a delay of a minute or more
-  is possible.
- </para>
- <para>
-  For further details on <varname>conninfo</varname> network connection
-  parameters, see the
-  <ulink url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PARAMKEYWORDS">PostgreSQL documentation</ulink>.
- </para>
- </sect1>
-
-
-
- <sect1 id="repmgrd-log-rotation">
-   <indexterm>
-     <primary>log rotation</primary>
-     <secondary>repmgrd</secondary>
-   </indexterm>
-
-  <title>repmgrd log rotation</title>
-  <para>
-   To ensure the current <application>repmgrd</application> logfile
-   (specified in <filename>repmgr.conf</filename> with the parameter
-   <option>log_file</option> does not grow indefinitely, configure your
-   system's <command>logrotate</command> to regularly rotate it.
-  </para>
-  <para>
-   Sample configuration to rotate logfiles weekly with retention for
-   up to 52 weeks and rotation forced if a file grows beyond 100Mb:
-   <programlisting>
-    /var/log/postgresql/repmgr-9.6.log {
-        missingok
-        compress
-        rotate 52
-        maxsize 100M
-        weekly
-        create 0600 postgres postgres
-    }</programlisting>
-  </para>
- </sect1>
-</chapter>
--- a/doc/repmgrd-configuration.xml
+++ b/doc/repmgrd-configuration.xml
--- a/doc/repmgrd-degraded-monitoring.sgml
+++ b/doc/repmgrd-degraded-monitoring.sgml
@@ -1,83 +0,0 @@
-<chapter id="repmgrd-degraded-monitoring">
- <indexterm>
-   <primary>repmgrd</primary>
-   <secondary>degraded monitoring</secondary>
- </indexterm>
-
- <title>"degraded monitoring" mode</title>
- <para>
-  In certain circumstances, <application>repmgrd</application> is not able to fulfill its primary mission
-  of monitoring the nodes' upstream server. In these cases it enters "degraded
-  monitoring" mode, where <application>repmgrd</application> remains active but is waiting for the situation
-  to be resolved.
- </para>
- <para>
-  Situations where this happens are:
-  <itemizedlist spacing="compact" mark="bullet">
-
-   <listitem>
-    <simpara>a failover situation has occurred, no nodes in the primary node's location are visible</simpara>
-   </listitem>
-
-   <listitem>
-    <simpara>a failover situation has occurred, but no promotion candidate is available</simpara>
-   </listitem>
-
-   <listitem>
-    <simpara>a failover situation has occurred, but the promotion candidate could not be promoted</simpara>
-   </listitem>
-
-   <listitem>
-    <simpara>a failover situation has occurred, but the node was unable to follow the new primary</simpara>
-   </listitem>
-
-   <listitem>
-    <simpara>a failover situation has occurred, but no primary has become available</simpara>
-   </listitem>
-
-   <listitem>
-    <simpara>a failover situation has occurred, but automatic failover is not enabled for the node</simpara>
-   </listitem>
-
-   <listitem>
-    <simpara>repmgrd is monitoring the primary node, but it is not available (and no other node has been promoted as primary)</simpara>
-   </listitem>
-  </itemizedlist>
- </para>
-
- <para>
-  Example output in a situation where there is only one standby with <literal>failover=manual</literal>,
-  and the primary node is unavailable (but is later restarted):
-  <programlisting>
-    [2017-08-29 10:59:19] [INFO] node "node2" (node ID: 2) monitoring upstream node "node1" (node ID: 1) in normal state (automatic failover disabled)
-    [2017-08-29 10:59:33] [WARNING] unable to connect to upstream node "node1" (node ID: 1)
-    [2017-08-29 10:59:33] [INFO] checking state of node 1, 1 of 5 attempts
-    [2017-08-29 10:59:33] [INFO] sleeping 1 seconds until next reconnection attempt
-    (...)
-    [2017-08-29 10:59:37] [INFO] checking state of node 1, 5 of 5 attempts
-    [2017-08-29 10:59:37] [WARNING] unable to reconnect to node 1 after 5 attempts
-    [2017-08-29 10:59:37] [NOTICE] this node is not configured for automatic failover so will not be considered as promotion candidate
-    [2017-08-29 10:59:37] [NOTICE] no other nodes are available as promotion candidate
-    [2017-08-29 10:59:37] [HINT] use "repmgr standby promote" to manually promote this node
-    [2017-08-29 10:59:37] [INFO] node "node2" (node ID: 2) monitoring upstream node "node1" (node ID: 1) in degraded state (automatic failover disabled)
-    [2017-08-29 10:59:53] [INFO] node "node2" (node ID: 2) monitoring upstream node "node1" (node ID: 1) in degraded state (automatic failover disabled)
-    [2017-08-29 11:00:45] [NOTICE] reconnected to upstream node 1 after 68 seconds, resuming monitoring
-    [2017-08-29 11:00:57] [INFO] node "node2" (node ID: 2) monitoring upstream node "node1" (node ID: 1) in normal state (automatic failover disabled)</programlisting>
-
- </para>
- <para>
-  By default, <literal>repmgrd</literal> will continue in degraded monitoring mode indefinitely.
-  However a timeout (in seconds) can be set with <varname>degraded_monitoring_timeout</varname>,
-  after which <application>repmgrd</application> will terminate.
- </para>
-
- <note>
-   <para>
-     If <application>repmgrd</application> is monitoring a primary mode which has been stopped
-     and manually restarted as a standby attached to a new primary, it will automatically detect
-     the status change and update the node record to reflect the node's new status
-     as an active standby. It will then resume monitoring the node as a standby.
-   </para>
- </note>
-
-</chapter>
--- a/doc/repmgrd-demonstration.sgml
+++ b/doc/repmgrd-demonstration.sgml
@@ -1,96 +0,0 @@
-<chapter id="repmgrd-demonstration">
- <title>repmgrd demonstration</title>
- <para>
-  To demonstrate automatic failover, set up a 3-node replication cluster (one primary
-  and two standbys streaming directly from the primary) so that the cluster looks
-  something like this:
-  <programlisting>
-    $ repmgr -f /etc/repmgr.conf cluster show
-     ID | Name  | Role    | Status    | Upstream | Location | Connection string
-    ----+-------+---------+-----------+----------+----------+--------------------------------------
-     1  | node1 | primary | * running |          | default  | host=node1 dbname=repmgr user=repmgr
-     2  | node2 | standby |   running | node1    | default  | host=node2 dbname=repmgr user=repmgr
-     3  | node3 | standby |   running | node1    | default  | host=node3 dbname=repmgr user=repmgr</programlisting>
- </para>
- <para>
-  Start <application>repmgrd</application> on each standby and verify that it's running by examining the
-  log output, which at log level <literal>INFO</literal> will look like this:
-  <programlisting>
-    [2017-08-24 17:31:00] [NOTICE] using configuration file "/etc/repmgr.conf"
-    [2017-08-24 17:31:00] [INFO] connecting to database "host=node2 dbname=repmgr user=repmgr"
-    [2017-08-24 17:31:00] [NOTICE] starting monitoring of node <literal>node2</literal> (ID: 2)
-    [2017-08-24 17:31:00] [INFO] monitoring connection to upstream node "node1" (node ID: 1)</programlisting>
- </para>
- <para>
-  Each <application>repmgrd</application> should also have recorded its successful startup as an event:
-  <programlisting>
-    $ repmgr -f /etc/repmgr.conf cluster event --event=repmgrd_start
-     Node ID | Name  | Event         | OK | Timestamp           | Details
-    ---------+-------+---------------+----+---------------------+-------------------------------------------------------------
-     3       | node3 | repmgrd_start | t  | 2017-08-24 17:35:54 | monitoring connection to upstream node "node1" (node ID: 1)
-     2       | node2 | repmgrd_start | t  | 2017-08-24 17:35:50 | monitoring connection to upstream node "node1" (node ID: 1)
-     1       | node1 | repmgrd_start | t  | 2017-08-24 17:35:46 | monitoring cluster primary "node1" (node ID: 1)  </programlisting>
- </para>
- <para>
-  Now stop the current primary server with e.g.:
-  <programlisting>
-    pg_ctl -D /var/lib/postgresql/data -m immediate stop</programlisting>
- </para>
- <para>
-  This will force the primary to shut down straight away, aborting all processes
-  and transactions.  This will cause a flurry of activity in the <application>repmgrd</application> log
-  files as each <application>repmgrd</application> detects the failure of the primary and a failover
-  decision is made. This is an extract from the log of a standby server (<literal>node2</literal>)
-  which has promoted to new primary after failure of the original primary (<literal>node1</literal>).
-  <programlisting>
-    [2017-08-24 23:32:01] [INFO] node "node2" (node ID: 2) monitoring upstream node "node1" (node ID: 1) in normal state
-    [2017-08-24 23:32:08] [WARNING] unable to connect to upstream node "node1" (node ID: 1)
-    [2017-08-24 23:32:08] [INFO] checking state of node 1, 1 of 5 attempts
-    [2017-08-24 23:32:08] [INFO] sleeping 1 seconds until next reconnection attempt
-    [2017-08-24 23:32:09] [INFO] checking state of node 1, 2 of 5 attempts
-    [2017-08-24 23:32:09] [INFO] sleeping 1 seconds until next reconnection attempt
-    [2017-08-24 23:32:10] [INFO] checking state of node 1, 3 of 5 attempts
-    [2017-08-24 23:32:10] [INFO] sleeping 1 seconds until next reconnection attempt
-    [2017-08-24 23:32:11] [INFO] checking state of node 1, 4 of 5 attempts
-    [2017-08-24 23:32:11] [INFO] sleeping 1 seconds until next reconnection attempt
-    [2017-08-24 23:32:12] [INFO] checking state of node 1, 5 of 5 attempts
-    [2017-08-24 23:32:12] [WARNING] unable to reconnect to node 1 after 5 attempts
-    INFO:  setting voting term to 1
-    INFO:  node 2 is candidate
-    INFO:  node 3 has received request from node 2 for electoral term 1 (our term: 0)
-    [2017-08-24 23:32:12] [NOTICE] this node is the winner, will now promote self and inform other nodes
-    INFO: connecting to standby database
-    NOTICE: promoting standby
-    DETAIL: promoting server using 'pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/pgsql/data' promote'
-    INFO: reconnecting to promoted server
-    NOTICE: STANDBY PROMOTE successful
-    DETAIL: node 2 was successfully promoted to primary
-    INFO:  node 3 received notification to follow node 2
-    [2017-08-24 23:32:13] [INFO] switching to primary monitoring mode</programlisting>
- </para>
- <para>
-  The cluster status will now look like this, with the original primary (<literal>node1</literal>)
-  marked as inactive, and standby <literal>node3</literal> now following the new primary
-  (<literal>node2</literal>):
-  <programlisting>
-    $ repmgr -f /etc/repmgr.conf cluster show
-     ID | Name  | Role    | Status    | Upstream | Location | Connection string
-    ----+-------+---------+-----------+----------+----------+----------------------------------------------------
-     1  | node1 | primary | - failed  |          | default  | host=node1 dbname=repmgr user=repmgr
-     2  | node2 | primary | * running |          | default  | host=node2 dbname=repmgr user=repmgr
-     3  | node3 | standby |   running | node2    | default  | host=node3 dbname=repmgr user=repmgr</programlisting>
-
- </para>
- <para>
-  <command>repmgr cluster event</command> will display a summary of what happened to each server
-  during the failover:
-  <programlisting>
-    $ repmgr -f /etc/repmgr.conf cluster event
-     Node ID | Name  | Event                    | OK | Timestamp           | Details
-    ---------+-------+--------------------------+----+---------------------+-----------------------------------------------------------------------------------
-     3       | node3 | repmgrd_failover_follow  | t  | 2017-08-24 23:32:16 | node 3 now following new upstream node 2
-     3       | node3 | standby_follow           | t  | 2017-08-24 23:32:16 | node 3 is now attached to node 2
-     2       | node2 | repmgrd_failover_promote | t  | 2017-08-24 23:32:13 | node 2 promoted to primary; old primary 1 marked as failed
-     2       | node2 | standby_promote          | t  | 2017-08-24 23:32:13 | node 2 was successfully promoted to primary</programlisting>
- </para>
-</chapter>
--- a/doc/repmgrd-monitoring.sgml
+++ b/doc/repmgrd-monitoring.sgml
@@ -1,80 +0,0 @@
-<chapter id="repmgrd-monitoring">
- <indexterm>
-   <primary>repmgrd</primary>
-   <secondary>monitoring</secondary>
- </indexterm>
- <indexterm>
-   <primary>monitoring</primary>
-   <secondary>with repmgrd</secondary>
- </indexterm>
-
- <title>Monitoring with repmgrd</title>
- <para>
-   When <application>repmgrd</application> is running with the option <literal>monitoring_history=true</literal>,
-  it will constantly write standby node status information to the
-  <varname>monitoring_history</varname> table, providing a near-real time
-  overview of replication status on all nodes
-  in the cluster.
- </para>
- <para>
-   The view <literal>replication_status</literal> shows the most recent state
-   for each node, e.g.:
-  <programlisting>
-    repmgr=# select * from repmgr.replication_status;
-    -[ RECORD 1 ]-------------+------------------------------
-    primary_node_id           | 1
-    standby_node_id           | 2
-    standby_name              | node2
-    node_type                 | standby
-    active                    | t
-    last_monitor_time         | 2017-08-24 16:28:41.260478+09
-    last_wal_primary_location | 0/6D57A00
-    last_wal_standby_location | 0/5000000
-    replication_lag           | 29 MB
-    replication_time_lag      | 00:00:11.736163
-    apply_lag                 | 15 MB
-    communication_time_lag    | 00:00:01.365643</programlisting>
- </para>
- <para>
-  The interval in which monitoring history is written is controlled by the
-  configuration parameter <varname>monitor_interval_secs</varname>;
-  default is 2.
- </para>
- <para>
-  As this can generate a large amount of monitoring data in the table
-  <literal>repmgr.monitoring_history</literal>. it's advisable to regularly
-  purge historical data using the <xref linkend="repmgr-cluster-cleanup">
-  command; use the <literal>-k/--keep-history</literal> option to
-  specify how many day's worth of data should be retained.
- </para>
- <para>
-  It's possible to use <application>repmgrd</application> to run in monitoring
-  mode only (without automatic failover capability) for some or all
-  nodes by setting <literal>failover=manual</literal> in the node's
-  <filename>repmgr.conf</filename> file. In the event of the node's upstream failing,
-  no failover action will be taken and the node will require manual intervention to
-  be reattached to replication. If this occurs, an
-  <link linkend="event-notifications">event notification</link>
-  <varname>standby_disconnect_manual</varname> will be created.
- </para>
- <para>
-  Note that when a standby node is not streaming directly from its upstream
-  node, e.g. recovering WAL from an archive, <varname>apply_lag</varname> will always appear as
-  <literal>0 bytes</literal>.
- </para>
- <tip>
-  <para>
-   If monitoring history is enabled, the contents of the <literal>repmgr.monitoring_history</literal>
-   table will be replicated to attached standbys. This means there will be a small but
-   constant stream of replication activity which may not be desirable. To prevent
-   this, convert the table to an <literal>UNLOGGED</literal> one with:
-   <programlisting>
-     ALTER TABLE repmgr.monitoring_history SET UNLOGGED;</programlisting>
-  </para>
-  <para>
-   This will however mean that monitoring history will not be available on
-   another node following a failover, and the view <literal>repmgr.replication_status</literal>
-   will not work on standbys.
-  </para>
- </tip>
-</chapter>
--- a/doc/repmgrd-network-split.sgml
+++ b/doc/repmgrd-network-split.sgml
@@ -1,48 +0,0 @@
-<chapter id="repmgrd-network-split" xreflabel="Handling network splits with repmgrd">
- <indexterm>
-   <primary>repmgrd</primary>
-   <secondary>network splits</secondary>
- </indexterm>
-
- <title>Handling network splits with repmgrd</title>
- <para>
-  A common pattern for replication cluster setups is to spread servers over
-  more than one datacentre. This can provide benefits such as geographically-
-  distributed read replicas and DR (disaster recovery capability). However
-  this also means there is a risk of disconnection at network level between
-  datacentre locations, which would result in a split-brain scenario if
-  servers in a secondary data centre were no longer able to see the primary
-  in the main data centre and promoted a standby among themselves.
- </para>
- <para>
-  &repmgr; enables provision of &quot;<xref linkend="witness-server">&quot; to
-  artificially create a quorum of servers in a particular location, ensuring
-  that nodes in another location will not elect a new primary if they
-  are unable to see the majority of nodes. However this approach does not
-  scale well, particularly with more complex replication setups, e.g.
-  where the majority of nodes are located outside of the primary datacentre.
-  It also means the <literal>witness</literal> node needs to be managed as an
-  extra PostgreSQL instance outside of the main replication cluster, which
-  adds administrative and programming complexity.
- </para>
- <para>
-  <literal>repmgr4</literal> introduces the concept of <literal>location</literal>:
-  each node is associated with an arbitrary location string (default is
-  <literal>default</literal>); this is set in <filename>repmgr.conf</filename>, e.g.:
-  <programlisting>
-    node_id=1
-    node_name=node1
-    conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'
-    data_directory='/var/lib/postgresql/data'
-    location='dc1'</programlisting>
- </para>
- <para>
-  In a failover situation, <application>repmgrd</application> will check if any servers in the
-  same location as the current primary node are visible.  If not, <application>repmgrd</application>
-  will assume a network interruption and not promote any node in any
-  other location (it will however enter <xref linkend="repmgrd-degraded-monitoring"> mode until
-  a primary becomes visible).
- </para>
-
-</chapter>
-
--- a/Show More
+++ b/Show More