diff --git a/doc/configuration-file-settings.sgml b/doc/configuration-file-settings.sgml index 36665e25..7d868dde 100644 --- a/doc/configuration-file-settings.sgml +++ b/doc/configuration-file-settings.sgml @@ -1,7 +1,7 @@ Configuration file settings - Each repmgr.conf file must contain the following parameters: + Each repmgr.conf file must contain the following parameters: @@ -51,8 +51,8 @@ For details on conninfo strings, see section - Connection Strings in the PosgreSQL documentation. + url="https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING">Connection Strings + in the PosgreSQL documentation. If repmgrd is in use, consider explicitly setting @@ -66,7 +66,7 @@ - data_directory (data_directory) + data_directory (string) data_directory configuration file parameter @@ -93,13 +93,19 @@ The following parameters in the configuration file can be overridden with -command line options: + command line options: - `-L/--log-level` overrides `log_level` in repmgr.conf + + -L/--log-level overrides log_level in + repmgr.conf + - `-b/--pg_bindir` overrides `pg_bindir` in repmgr.conf + + -b/--pg_bindir overrides pg_bindir in + repmgr.conf + diff --git a/doc/configuration-file.sgml b/doc/configuration-file.sgml index cc0dc2d9..5b87dbcc 100644 --- a/doc/configuration-file.sgml +++ b/doc/configuration-file.sgml @@ -1,9 +1,10 @@ Configuration file location - `repmgr` and `repmgrd` use a common configuration file, by default called - `repmgr.conf` (although any name can be used if explicitly specified). - `repmgr.conf` must contain a number of required parameters, including + repmgr and repmgrd + use a common configuration file, by default called + repmgr.conf (although any name can be used if explicitly specified). + repmgr.conf must contain a number of required parameters, including the database connection string for the local node and the location of its data directory; other values will be inferred from defaults if not explicitly supplied. See section `configuration file parameters` @@ -17,26 +18,29 @@ a configuration file specified by the `-f/--config-file` command line option - a location specified by the package maintainer (if `repmgr` was installed - from a package and the package maintainer has specified the configuration - file location) + + a location specified by the package maintainer (if repmgr + as installed from a package and the package maintainer has specified the configuration + file location) + - `repmgr.conf` in the local directory + repmgr.conf in the local directory - `/etc/repmgr.conf` + /etc/repmgr.conf - the directory reported by `pg_config --sysconfdir` + the directory reported by pg_config --sysconfdir - Note that if a file is explicitly specified with `-f/--config-file`, an error will - be raised if it is not found or not readable and no attempt will be made to check - default locations; this is to prevent `repmgr` unexpectedly reading the wrong file. + Note that if a file is explicitly specified with -f/--config-file, + an error will be raised if it is not found or not readable and no attempt will be made to + check default locations; this is to prevent repmgr unexpectedly + reading the wrong file. diff --git a/doc/filelist.sgml b/doc/filelist.sgml index 542643b1..c11f0179 100644 --- a/doc/filelist.sgml +++ b/doc/filelist.sgml @@ -35,6 +35,7 @@ + diff --git a/doc/quickstart.sgml b/doc/quickstart.sgml new file mode 100644 index 00000000..3bc51d99 --- /dev/null +++ b/doc/quickstart.sgml @@ -0,0 +1,223 @@ + + Quick-start guide + + + This section gives a quick introduction to &repmgr;, including setting up a + sample &repmgr; installation and a basic replication cluster. + + + + These instructions are not suitable for a production install, as they may not + take into account security considerations, proper system administration + procedures etc.. + + + + Prerequisites for setting up a basic replication cluster with &repmgr; + + The following section will describe how to set up a basic replication cluster + with a primary and a standby server using the repmgr + command line tool. + + + We'll assume the primary is called node1 with IP address + 192.168.1.11, and the standby is called node2 + with IP address 192.168.1.12 + + + Following software must be installed on both servers: + + + PostgreSQL + + + + repmgr (matching the installed + PostgreSQL major version) + + + + + + + At network level, connections between the PostgreSQL port (default: 5432) + must be possible in both directions. + + + If you want repmgr to copy configuration files which are + located outside the PostgreSQL data directory, and/or to test switchover + functionality, you will also need passwordless SSH connections between both servers, and + rsync should be installed. + + + + For testing repmgr, it's possible to use multiple PostgreSQL + instances running on different ports on the same computer, with + passwordless SSH access to localhost enabled. + + + + + + PostgreSQL configuration + + On the primary server, a PostgreSQL instance must be initialised and running. + The following replication settings may need to be adjusted: + + + + # 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 + + + + Rather than editing these settings in the default postgresql.conf + file, create a separate file such as postgresql.replication.conf and + include it from the end of the main configuration file with: + include 'postgresql.replication.conf. + + + + + + repmgr user and database + + Create a dedicated PostgreSQL superuser account and a database for + the `repmgr` metadata, e.g. + + + createuser -s repmgr + createdb repmgr -O repmgr + + + + For the examples in this document, the name repmgr will be + used for both user and database, but any names can be used. + + + + For the sake of simplicity, the repmgr user is created + as a superuser. If desired, it's possible to create the repmgr + user as a normal user. However for certain operations superuser permissions + are requiredl; in this case the command line option --superuser + can be provided to specify a superuser. + + + It's also assumed that the repmgr 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. + + + + + + Configuring authentication in pg_hba.conf + + Ensure the `repmgr` user has appropriate permissions in pg_hba.conf and + can connect in replication mode; pg_hba.conf should contain entries + similar to the following: + + + 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 + + + Adjust according to your network environment and authentication requirements. + + + + + Preparing the standby + + 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 postgres system user. Permissions + should be set to 0700 (drwx------). + + + Check the primary database is reachable from the standby using psql: + + + psql 'host=node1 user=repmgr dbname=repmgr connect_timeout=2' + + + + &repmgr; stores connection information as libpq + connection strings throughout. This documentation refers to them as conninfo + strings; an alternative name is DSN (data source name). + We'll use these in place of the -h hostname -d databasename -U username syntax. + + + + + + repmgr configuration file + + Create a repmgr.conf file on the primary server. The file must + contain at least the following parameters: + + + node_id=1 + node_name=node1 + conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2' + data_directory='/var/lib/postgresql/data' + + + + + + + + repmgr.conf 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 and + for further details about repmgr.conf. + + + + diff --git a/doc/repmgr.sgml b/doc/repmgr.sgml index 83553a18..e84c2067 100644 --- a/doc/repmgr.sgml +++ b/doc/repmgr.sgml @@ -62,6 +62,7 @@ Getting started &overview; &install; + &quickstart; diff --git a/doc/website-docs.css b/doc/website-docs.css index e69de29b..8a707c2d 100644 --- a/doc/website-docs.css +++ b/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; +}