diff --git a/doc/configuration.sgml b/doc/configuration.sgml index b9cbb68b..95585032 100644 --- a/doc/configuration.sgml +++ b/doc/configuration.sgml @@ -12,13 +12,13 @@ repmgr user permissions - &repmgr; will create an extension in the BDR database containing objects + &repmgr; will create an extension database containing objects for administering &repmgr; metadata. The user defined in the conninfo 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 --superuser when registering a BDR node. + superuser specified with --superuser when registering a &repmgr; node. diff --git a/doc/configuring-witness-server.sgml b/doc/configuring-witness-server.sgml new file mode 100644 index 00000000..b0b18eb3 --- /dev/null +++ b/doc/configuring-witness-server.sgml @@ -0,0 +1,86 @@ + + + witness server + Using a witness server with repmgrd + + + + Using a witness server + + A 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. + + + + 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). + + + 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 for more details. + + + + + A witness server will only be useful if repmgrd + is in use. + + + + + Creating a witness server + + 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. + + + 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. + + + + &repmgr; 3.3 and earlier provided a repmgr create witness + command, which would automatically create a PostgreSQL instance. However + this often resulted in an unsatisfactory, hard-to-customise instance. + + + + The witness server should be configured in the same way as a normal + &repmgr; node; see section . + + + Register the witness server with . + This will create the &repmgr; extension on the witness server, and make + a copy of the &repmgr; metadata. + + + + As the witness server is not part of the replication cluster, further + changes to the &repmgr; metadata will be synchronised by + repmgrd. + + + + Once the witness server has been configured, repmgrd + should be started; for more details see . + + + + To unregister a witness server, use . + + + + diff --git a/doc/filelist.sgml b/doc/filelist.sgml index 9ec8c197..44526e31 100644 --- a/doc/filelist.sgml +++ b/doc/filelist.sgml @@ -43,6 +43,8 @@ + + diff --git a/doc/follow-new-primary.sgml b/doc/follow-new-primary.sgml index 75af0955..0ac1fc67 100644 --- a/doc/follow-new-primary.sgml +++ b/doc/follow-new-primary.sgml @@ -1,4 +1,4 @@ - + Following a new primary repmgr standby follow diff --git a/doc/overview.sgml b/doc/overview.sgml index be91122a..b4e63fa1 100644 --- a/doc/overview.sgml +++ b/doc/overview.sgml @@ -87,6 +87,30 @@ + + witness server + + + &repmgr; provides functionality to set up a so-called "witness server" to + assist in determining a new primary server in a failover situation with more + than one standby. The witness server itself is not part of the replication + cluster, although it does contain a copy of the repmgr metadata schema. + + + The purpose of a witness server is to provide a "casting vote" where servers + in the replication cluster are split over more than one location. In the event + of a loss of connectivity between locations, the presence or absence of + the witness server will decide whether a server at that location is promoted + to primary; this is to prevent a "split-brain" situation where an isolated + location interprets a network outage as a failure of the (remote) primary and + promotes a (local) standby. + + + A witness server only needs to be created if repmgrd + is in use. + + + @@ -145,31 +169,6 @@ - - witness server - - - &repmgr; provides functionality to set up a so-called "witness server" to - assist in determining a new primary server in a failover situation with more - than one standby. The witness server itself is not part of the replication - cluster, although it does contain a copy of the repmgr metadata schema - (see below). - - - The purpose of a witness server is to provide a "casting vote" where servers - in the replication cluster are split over more than one location. In the event - of a loss of connectivity between locations, the presence or absence of - the witness server will decide whether a server at that location is promoted - to primary; this is to prevent a "split-brain" situation where an isolated - location interprets a network outage as a failure of the (remote) primary and - promotes a (local) standby. - - - A witness server only needs to be created if repmgrd - is in use. - - - diff --git a/doc/repmgr-witness-register.sgml b/doc/repmgr-witness-register.sgml index efe2526e..a82d4376 100644 --- a/doc/repmgr-witness-register.sgml +++ b/doc/repmgr-witness-register.sgml @@ -1,6 +1,7 @@ - + repmgr witness register + witness server diff --git a/doc/repmgr.sgml b/doc/repmgr.sgml index f4c2401e..d3e136cd 100644 --- a/doc/repmgr.sgml +++ b/doc/repmgr.sgml @@ -73,6 +73,7 @@ &promoting-standby; &follow-new-primary; &switchover; + &configuring-witness-server; &event-notifications; &upgrading-repmgr; diff --git a/doc/repmgrd-network-split.sgml b/doc/repmgrd-network-split.sgml index 3b18d0a5..1f305361 100644 --- a/doc/repmgrd-network-split.sgml +++ b/doc/repmgrd-network-split.sgml @@ -1,4 +1,4 @@ - + repmgrd network splits diff --git a/doc/repmgrd-witness-server.sgml b/doc/repmgrd-witness-server.sgml index bce6770b..3bebca43 100644 --- a/doc/repmgrd-witness-server.sgml +++ b/doc/repmgrd-witness-server.sgml @@ -1,4 +1,4 @@ - + repmgrd witness server @@ -23,9 +23,9 @@ This is not a fully-fledged standby node and is not integrated into replication, but it effectively represents the "casting vote" when deciding which network segment has a majority. A witness server can - be set up using `repmgr witness create` (see below for details) and - can run on a dedicated server or an existing node. Note that it only + be set up using . Note that it only makes sense to create a witness server in conjunction with running - `repmgrd`; the witness server will require its own `repmgrd` instance. + repmgrd; the witness server will require its own + repmgrd instance.