Start quickstart guide

doc/configuration-file-settings.sgml

@@ -1,7 +1,7 @@
 <sect1 id="configuration-file-settings" xreflabel="configuration file settings">
  <title>Configuration file settings</title>
  <para>
-  Each repmgr.conf file must contain the following parameters:
+   Each <filename>repmgr.conf</filename> file must contain the following parameters:
  </para>
  <para>
   <variablelist>
@@ -51,8 +51,8 @@
      </para>
      <para>
        For details on conninfo strings, see section <ulink
-       url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING">
+       url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING">Connection Strings</>
-       Connection Strings</> in the PosgreSQL documentation.
+        in the PosgreSQL documentation.
      </para>
      <para>
         If repmgrd is in use, consider explicitly setting
@@ -66,7 +66,7 @@
    </varlistentry>
 
    <varlistentry id="repmgr-conf-data-directory" xreflabel="data_directory">
-    <term><varname>data_directory</varname> (<type>data_directory</type>)
+    <term><varname>data_directory</varname> (<type>string</type>)
      <indexterm>
       <primary><varname>data_directory</varname> configuration file parameter</primary>
      </indexterm>
@@ -93,13 +93,19 @@
   <note>
     <para>
     The following parameters in the configuration file can be overridden with
-command line options:
+    command line options:
     <itemizedlist>
      <listitem>
-       <simpara>`-L/--log-level` overrides `log_level` in repmgr.conf </simpara>
+       <simpara>
+         <literal>-L/--log-level</literal> overrides <literal>log_level</literal> in
+         <filename>repmgr.conf</filename>
+       </simpara>
      </listitem>
      <listitem>
-       <simpara>`-b/--pg_bindir` overrides `pg_bindir` in repmgr.conf</simpara>
+       <simpara>
+         <literal>-b/--pg_bindir</literal> overrides <literal>pg_bindir</literal> in
+         <filename>repmgr.conf</filename>
+       </simpara>
      </listitem>
     </itemizedlist>
     </para>

doc/configuration-file.sgml

@@ -1,9 +1,10 @@
 <sect1 id="configuration-file" xreflabel="configuration file location">
   <title>Configuration file location</title>
   <para>
-    `repmgr` and `repmgrd` use a common configuration file, by default called
+    <application>repmgr</application> and <application>repmgrd</application>
-    `repmgr.conf` (although any name can be used if explicitly specified).
+    use a common configuration file, by default called
-    `repmgr.conf` must contain a number of required parameters, including
+    <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 `configuration file parameters`
@@ -17,26 +18,29 @@
      <para>a configuration file specified by the `-f/--config-file` command line option</para>
     </listitem>
     <listitem>
-     <para>a location specified by the package maintainer (if `repmgr` was installed
+     <para>
-  from a package and the package maintainer has specified the configuration
+      a location specified by the package maintainer (if <application>repmgr</application>
-  file location)</para>
+      as installed from a package and the package maintainer has specified the configuration
+      file location)
+     </para>
     </listitem>
     <listitem>
-     <para>`repmgr.conf` in the local directory</para>
+     <para><filename>repmgr.conf</filename> in the local directory</para>
     </listitem>
     <listitem>
-     <para>`/etc/repmgr.conf`</para>
+      <para><filename>/etc/repmgr.conf</filename></para>
     </listitem>
     <listitem>
-     <para>the directory reported by `pg_config --sysconfdir`</para>
+     <para>the directory reported by <application>pg_config --sysconfdir</application></para>
     </listitem>
    </itemizedlist>
   </para>
 
   <para>
-    Note that if a file is explicitly specified with `-f/--config-file`, an error will
+   Note that if a file is explicitly specified with <application>-f/--config-file</application>,
-    be raised if it is not found or not readable and no attempt will be made to check
+   an error will be raised if it is not found or not readable and no attempt will be made to
-    default locations; this is to prevent `repmgr` unexpectedly reading the wrong file.
+   check default locations; this is to prevent <application>repmgr</application> unexpectedly
+   reading the wrong file.
   </para>
 
 </sect1>

doc/filelist.sgml

@@ -35,6 +35,7 @@
 <!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-settings      SYSTEM "configuration-file-settings.sgml">

doc/quickstart.sgml

@@ -0,0 +1,223 @@
+<chapter id="quickstart" xreflabel="Quick-start guide">
+ <title>Quick-start guide</title>
+
+ <para>
+  This section gives a quick introduction to &repmgr;, including setting up a
+  sample &repmgr; installation and a basic replication cluster.
+ </para>
+
+ <para>
+  These instructions are not suitable for a production install, as they may not
+  take into account security considerations, proper system administration
+  procedures etc..
+ </para>
+
+ <sect1 id="quickstart-prerequisites">
+   <title>Prerequisites for setting up a basic replication cluster with &repmgr;</title>
+    <para>
+     The following section will describe how to set up a basic replication cluster
+     with a primary and a standby server using the <application>repmgr</application>
+     command line tool.
+    </para>
+    <para>
+      We'll assume the primary is called <literal>node1</literal> with IP address
+      <literal>192.168.1.11</literal>, and the standby is called <literal>node2</literal>
+      with IP address <literal>192.168.1.12</literal>
+    </para>
+    <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> (matching the installed
+        <application>PostgreSQL</application> major version)
+       </simpara>
+      </listitem>
+     </itemizedlist>
+    </para>
+
+    <para>
+      At network level, connections between the PostgreSQL port (default: <literal>5432</literal>)
+      must be possible in both directions.
+    </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>
+      functionality, you will also need passwordless SSH connections between both servers, and
+      <application>rsync</application> should be installed.
+    </para>
+    <tip>
+     <simpara>
+      For testing <application>repmgr</application>, it's possible to use multiple PostgreSQL
+      instances running on different ports on the same computer, with
+      passwordless SSH access to <filename>localhost</filename> enabled.
+     </simpara>
+    </tip>
+ </sect1>
+
+ <sect1 id="quickstart-postgresql-configuration">
+   <title>PostgreSQL configuration</title>
+   <para>
+    On the primary server, a PostgreSQL instance must be initialised and running.
+    The following replication settings may need to be adjusted:
+   </para>
+   <programlisting>
+
+    # Enable replication connections; set this figure 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)
+
+    max_wal_senders = 10
+
+    # Ensure WAL files contain enough information to enable read-only queries
+    # on the standby.
+    #
+    #  PostgreSQL 9.5 and earlier: one of 'hot_standby' or 'logical'
+    #  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
+
+    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)
+
+    hot_standby = on
+
+    # Enable WAL file archiving
+    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.
+    #
+    # wal_keep_segments = 5000
+   </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
+      include it from the end of the main configuration file with:
+     <command>include 'postgresql.replication.conf</command>.
+    </simpara>
+   </tip>
+ </sect1>
+
+ <sect1 id="quickstart-repmgr-user-database">
+  <title>repmgr user and database</title>
+  <para>
+   Create a dedicated PostgreSQL superuser account and a database for
+   the `repmgr` metadata, e.g.
+  </para>
+  <programlisting>
+   createuser -s repmgr
+   createdb repmgr -O repmgr
+  </programlisting>
+
+  <para>
+   For the examples in this document, the name <literal>repmgr</literal> will be
+   used for both user and database, but any names can be used.
+  </para>
+  <note>
+   <para>
+    For the sake of simplicity, the <literal>repmgr</literal> user is created
+    as a superuser. If desired, it's possible to create the <literal>repmgr</literal>
+    user as a normal user. However for certain operations superuser permissions
+    are requiredl; in this case the command line option <command>--superuser</command>
+    can be provided to specify a superuser.
+   </para>
+   <para>
+    It's also assumed that the <literal>repmgr</literal> user will be used to make the
+    replication connection from the standby to the primary; again this can be
+    overridden by specifying a separate replication user when registering each node.
+   </para>
+  </note>
+ </sect1>
+
+ <sect1 id="quickstart-authentication">
+  <title>Configuring authentication in pg_hba.conf</title>
+  <para>
+   Ensure the `repmgr` user has appropriate permissions in <filename>pg_hba.conf</filename> and
+   can connect in replication mode; <filename>pg_hba.conf</filename> should contain entries
+   similar to the following:
+  </para>
+  <programlisting>
+    local   replication   repmgr                              trust
+    host    replication   repmgr      127.0.0.1/32            trust
+    host    replication   repmgr      192.168.1.0/24          trust
+
+    local   repmgr        repmgr                              trust
+    host    repmgr        repmgr      127.0.0.1/32            trust
+    host    repmgr        repmgr      192.168.1.0/24          trust
+  </programlisting>
+  <para>
+   Adjust according to your network environment and authentication requirements.
+  </para>
+ </sect1>
+
+ <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
+   data directory (and any other directories which you want PostgreSQL to use)
+   exist and are owned by the <literal>postgres</literal> system user. Permissions
+   should be set to <literal>0700</literal> (<literal>drwx------</literal>).
+  </para>
+  <para>
+   Check the primary database is reachable from the standby using <application>psql</application>:
+  </para>
+  <programlisting>
+    psql 'host=node1 user=repmgr dbname=repmgr connect_timeout=2'</programlisting>
+
+  <note>
+   <para>
+    &repmgr; stores connection information as <ulink
+    url="https://www.postgresql.org/docs/current/static/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.
+   </para>
+  </note>
+ </sect1>
+
+ <sect1 id="quickstart-repmgr-conf">
+  <title>repmgr configuration file</title>
+  <para>
+   Create a <filename>repmgr.conf</filename> file on the primary server. The file must
+   contain at least the following parameters:
+  </para>
+  <programlisting>
+    node_id=1
+    node_name=node1
+    conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'
+    data_directory='/var/lib/postgresql/data'
+  </programlisting>
+
+  <para>
+
+  </para>
+
+  <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 on <xref linkend="configuration-file"> and <xref linkend="configuration-file-settings">
+   for further details about <filename>repmgr.conf</filename>.
+  </para>
+ </sect1>
+
+</chapter>

doc/repmgr.sgml

@@ -62,6 +62,7 @@
   <title>Getting started</title>
   &overview;
   &install;
+  &quickstart;
  </part>
 
  <part id="repmgr-administration-manual">

doc/website-docs.css

@@ -0,0 +1,469 @@
+/* PostgreSQL.org Documentation Style */
+
+/* requires global.css, table.css and text.css to be loaded before this file! */
+body {
+  font-family: verdana, sans-serif;
+  font-size: 76%;
+  background: url("/resources/background.png") repeat-x scroll left top transparent;
+  padding: 15px 4%;
+  margin: 0;
+}
+
+/* monospace font size fix */
+pre, code, kbd, samp, tt {
+  font-family: monospace,monospace;
+  font-size: 1em;
+}
+
+div.NAVHEADER table {
+  margin-left: 0;
+}
+
+/* Container Definitions */
+
+#docContainerWrap {
+  text-align: center; /* Win IE5 */
+}
+
+#docContainer {
+  margin: 0 auto;
+  width: 90%;
+  padding-bottom: 2em;
+  display: block;
+  text-align: left; /* Win IE5 */
+}
+
+#docHeader {
+  background-image: url("/media/img/docs/bg_hdr.png");
+  height: 83px;
+  margin: 0px;
+  padding: 0px;
+  display: block;
+}
+
+#docHeaderLogo {
+  position: relative;
+  width: 206px;
+  height: 83px;
+  border: 0px;
+  padding: 0px;
+  margin: 0 0 0 20px;
+}
+
+#docHeaderLogo img {
+  border: 0px;
+}
+
+#docNavSearchContainer {
+  padding-bottom: 2px;
+}
+
+#docNav, #docVersions {
+  position: relative;
+  text-align: left;
+  margin-left: 10px;
+  margin-top: 5px;
+  color: #666;
+  font-size: 0.95em;
+}
+
+#docSearch {
+  position: relative;
+  text-align: right;
+  padding: 0;
+  margin: 0;
+  color: #666;
+}
+
+#docTextSize {
+  text-align: right;
+  white-space: nowrap;
+  margin-top: 7px;
+  font-size: 0.95em;
+}
+
+#docSearch form {
+  position: relative;
+  top: 5px;
+  right: 0;
+  margin: 0; /* need for IE 5.5 OSX */
+  text-align: right; /* need for IE 5.5 OSX */
+  white-space: nowrap; /* for Opera */
+}
+
+#docSearch form label {
+  color: #666;
+  font-size: 0.95em;
+}
+
+#docSearch form input {
+  font-size: 0.95em;
+}
+  
+#docSearch form #submit {
+  font-size: 0.95em;
+  background: #7A7A7A;
+  color: #fff;
+  border: 1px solid #7A7A7A;
+  padding: 1px 4px;
+}
+  
+#docSearch form #q {
+  width: 170px;
+  font-size: 0.95em;
+  border:  1px solid #7A7A7A;
+  background: #E1E1E1;
+  color: #000000;
+  padding: 2px;
+}
+
+.frmDocSearch {
+  padding: 0;
+  margin: 0;
+  display: inline;
+}
+
+.inpDocSearch {
+  padding: 0;
+  margin: 0;
+  color: #000;
+}
+
+#docContent {
+  position: relative;
+  margin-left: 10px;
+  margin-right: 10px;
+  margin-top: 40px;
+}
+
+#docFooter {
+  position: relative;
+  font-size: 0.9em; 
+  color: #666; 
+  line-height: 1.3em; 
+  margin-left: 10px;
+  margin-right: 10px;
+}
+
+#docComments {
+  margin-top: 10px;
+}
+
+#docClear {
+  clear: both;
+  margin: 0;
+  padding: 0;
+}
+
+/* Heading Definitions */
+
+h1, h2, h3 {
+  font-weight: bold;
+  margin-top: 2ex;
+  color: #444;
+}
+
+h1 {
+  font-size: 1.4em;
+}
+
+h2 {
+  font-size: 1.2em !important;
+}
+
+h3 {
+  font-size: 1.1em;
+}
+
+h1 a:hover,
+h2 a:hover,
+h3 a:hover,
+h4 a:hover {
+  color: #444;
+  text-decoration: none;
+}
+
+/* Text Styles */
+
+div.SECT2 {
+  margin-top: 4ex;
+}
+
+div.SECT3 {
+  margin-top: 3ex;
+  margin-left: 3ex;
+}
+
+.txtCurrentLocation {
+  font-weight: bold;
+}
+
+p, ol, ul, li {
+  line-height: 1.5em;
+}
+
+.txtCommentsWrap {
+  border: 2px solid #F5F5F5; 
+  width: 100%;
+}
+
+.txtCommentsContent {
+  background: #F5F5F5;
+  padding: 3px;
+}
+
+.txtCommentsPoster {
+  float: left;
+}
+
+.txtCommentsDate {
+  float: right;
+}
+
+.txtCommentsComment {
+  padding: 3px;
+}
+
+#docContainer pre code,
+#docContainer pre tt,
+#docContainer pre pre,
+#docContainer tt tt,
+#docContainer tt code,
+#docContainer tt pre {
+  font-size: 1em;
+}
+
+pre.LITERALLAYOUT,
+.SCREEN,
+.SYNOPSIS,
+.PROGRAMLISTING,
+.REFSYNOPSISDIV p,
+table.CAUTION,
+table.WARNING,
+blockquote.NOTE,
+blockquote.TIP,
+table.CALSTABLE {
+  -moz-box-shadow: 3px 3px 5px #DFDFDF;
+  -webkit-box-shadow: 3px 3px 5px #DFDFDF;
+  -khtml-box-shadow: 3px 3px 5px #DFDFDF;
+  -o-box-shadow: 3px 3px 5px #DFDFDF;
+  box-shadow: 3px 3px 5px #DFDFDF;
+}
+
+pre.LITERALLAYOUT,
+.SCREEN,
+.SYNOPSIS,
+.PROGRAMLISTING,
+.REFSYNOPSISDIV p,
+table.CAUTION,
+table.WARNING,
+blockquote.NOTE,
+blockquote.TIP {
+  color: black;
+  border-width: 1px;
+  border-style: solid;
+  padding: 2ex;
+  margin: 2ex 0 2ex 2ex;
+  overflow: auto;
+  -moz-border-radius: 8px;
+  -webkit-border-radius: 8px;
+  -khtml-border-radius: 8px;
+  border-radius: 8px;
+}
+
+pre.LITERALLAYOUT,
+pre.SYNOPSIS,
+pre.PROGRAMLISTING,
+.REFSYNOPSISDIV p,
+.SCREEN {
+  border-color: #CFCFCF;
+  background-color: #F7F7F7;
+}
+
+blockquote.NOTE,
+blockquote.TIP {
+  border-color: #DBDBCC;
+  background-color: #EEEEDD;
+  padding: 14px;
+  width: 572px;
+}
+
+blockquote.NOTE,
+blockquote.TIP,
+table.CAUTION,
+table.WARNING {
+  margin: 4ex auto;
+}
+
+blockquote.NOTE p,
+blockquote.TIP p {
+  margin: 0;
+}
+
+blockquote.NOTE pre,
+blockquote.NOTE code,
+blockquote.TIP pre,
+blockquote.TIP code {
+  margin-left: 0;
+  margin-right: 0;
+  -moz-box-shadow: none;
+  -webkit-box-shadow: none;
+  -khtml-box-shadow: none;
+  -o-box-shadow: none;
+  box-shadow: none;
+}
+
+.emphasis,
+.c2 {
+  font-weight: bold;
+}
+
+.REPLACEABLE {
+  font-style: italic;
+}
+
+/* Table Styles */
+
+table {
+  margin-left: 2ex;
+}
+
+table.CALSTABLE td,
+table.CALSTABLE th,
+table.CAUTION td,
+table.CAUTION th,
+table.WARNING td,
+table.WARNING th {
+  border-style: solid;
+}
+
+table.CALSTABLE,
+table.CAUTION,
+table.WARNING {
+  border-spacing: 0;
+  border-collapse: collapse;
+}
+
+table.CALSTABLE
+{
+  margin: 2ex 0 2ex 2ex;
+  background-color: #E0ECEF;
+  border: 2px solid #A7C6DF;
+}
+
+table.CALSTABLE tr:hover td
+{
+  background-color: #EFEFEF;
+}
+
+table.CALSTABLE td {
+  background-color: #FFF;
+}
+
+table.CALSTABLE td,
+table.CALSTABLE th {
+  border: 1px solid #A7C6DF;
+  padding: 0.5ex 0.5ex;
+}
+
+table.CAUTION,
+table.WARNING {
+  border-collapse: separate;
+  display: block;
+  padding: 0;
+  max-width: 600px;
+}
+
+table.CAUTION {
+  background-color: #F5F5DC;
+  border-color: #DEDFA7;
+}
+
+table.WARNING {
+  background-color: #FFD7D7;
+  border-color: #DF421E;
+}
+
+table.CAUTION td,
+table.CAUTION th,
+table.WARNING td,
+table.WARNING th {
+  border-width: 0;
+  padding-left: 2ex;
+  padding-right: 2ex;
+}
+
+table.CAUTION td,
+table.CAUTION th {
+  border-color: #F3E4D5
+}
+
+table.WARNING td,
+table.WARNING th {
+  border-color: #FFD7D7;
+}
+
+td.c1,
+td.c2,
+td.c3,
+td.c4,
+td.c5,
+td.c6 {
+  font-size: 1.1em;
+  font-weight: bold;
+  border-bottom: 0px solid #FFEFEF;
+  padding: 1ex 2ex 0;
+}
+
+/* Link Styles */
+
+#docNav a {
+  font-weight: bold;
+}
+
+a:link,
+a:visited,
+a:active,
+a:hover {
+  text-decoration: underline;
+}
+
+a:link,
+a:active {
+  color:#0066A2;
+}
+
+a:visited {
+  color:#004E66;
+}
+
+a:hover {
+  color:#000000;
+}
+
+#docFooter a:link,
+#docFooter a:visited,
+#docFooter a:active {
+  color:#666;
+}
+
+#docContainer code.FUNCTION tt {
+  font-size: 1em;
+}
+
+div.header {
+    color: #444;
+    margin-top: 5px;
+}
+
+div.footer {
+    text-align: center;
+    background-image: url("/resources/footerl.png"), url("/resources/footerr.png"), url("/resources/footerc.png");
+    background-position: left top, right top, center top;
+    background-repeat: no-repeat, no-repeat, repeat-x;
+    padding-top: 45px;
+}
+
+img {
+    border-style: none;
+}