diff --git a/doc/configuring-witness-server.sgml b/doc/configuring-witness-server.sgml deleted file mode 100644 index 54b0aee9..00000000 --- a/doc/configuring-witness-server.sgml +++ /dev/null @@ -1,93 +0,0 @@ - - - witness server - - - - 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 it is the primary server - itself which is unavailable, rather than e.g. a network split between - different physical locations. - - - - 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). - - - - Never 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. - - - - 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 90fc8810..792ef61f 100644 --- a/doc/filelist.sgml +++ b/doc/filelist.sgml @@ -45,7 +45,6 @@ - diff --git a/doc/repmgr.sgml b/doc/repmgr.sgml index d93e1a0a..0e358ae8 100644 --- a/doc/repmgr.sgml +++ b/doc/repmgr.sgml @@ -82,7 +82,6 @@ &repmgrd-overview; &repmgrd-automatic-failover; &repmgrd-configuration; - &configuring-witness-server; &repmgrd-operation; &repmgrd-bdr; diff --git a/doc/repmgrd-automatic-failover.sgml b/doc/repmgrd-automatic-failover.sgml index c591971a..ba162744 100644 --- a/doc/repmgrd-automatic-failover.sgml +++ b/doc/repmgrd-automatic-failover.sgml @@ -23,37 +23,92 @@ witness server 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 it is the primary server + itself which is unavailable, rather than e.g. a network split between + different physical locations. + - Using a witness server with repmgrd - In a situation caused e.g. by a network interruption between two - data centres, it's important to avoid a "split-brain" situation where - both sides of the network assume they are the active segment and the - side without an active primary unilaterally promotes one of its standbys. - - - To prevent this situation happening, it's essential to ensure that one - network segment has a "voting majority", so other segments will know - they're in the minority and not attempt to promote a new primary. Where - an odd number of servers exists, this is not an issue. However, if each - network has an even number of nodes, it's necessary to provide some way - of ensuring a majority, which is where the witness server becomes useful. - - - 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 register; - see also section Using a witness server. + 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). - It only - makes sense to create a witness server in conjunction with running - repmgrd; the witness server will require its own - repmgrd instance. + Never 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. + + 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. + + + + To unregister a witness server, use . + + + diff --git a/doc/repmgrd-overview.sgml b/doc/repmgrd-overview.sgml index 7f67e7a8..2698424f 100644 --- a/doc/repmgrd-overview.sgml +++ b/doc/repmgrd-overview.sgml @@ -44,7 +44,7 @@ - optional witness server + optional witness server