diff --git a/modules/ROOT/images/server-lifecycle.svg b/modules/ROOT/images/server-lifecycle.svg
new file mode 100644
index 000000000..96cf296a2
--- /dev/null
+++ b/modules/ROOT/images/server-lifecycle.svg
@@ -0,0 +1,33 @@
+
diff --git a/modules/ROOT/images/server-states.png b/modules/ROOT/images/server-states.png
deleted file mode 100644
index 19596196f..000000000
Binary files a/modules/ROOT/images/server-states.png and /dev/null differ
diff --git a/modules/ROOT/images/server-states2.png b/modules/ROOT/images/server-states2.png
deleted file mode 100644
index 9a23a1d33..000000000
Binary files a/modules/ROOT/images/server-states2.png and /dev/null differ
diff --git a/modules/ROOT/images/server-states3.png b/modules/ROOT/images/server-states3.png
deleted file mode 100644
index 4a3984c1a..000000000
Binary files a/modules/ROOT/images/server-states3.png and /dev/null differ
diff --git a/modules/ROOT/images/server-states4.png b/modules/ROOT/images/server-states4.png
deleted file mode 100644
index 508de1bdd..000000000
Binary files a/modules/ROOT/images/server-states4.png and /dev/null differ
diff --git a/modules/ROOT/pages/clustering/databases.adoc b/modules/ROOT/pages/clustering/databases.adoc
index e5f64535c..c9d120f83 100644
--- a/modules/ROOT/pages/clustering/databases.adoc
+++ b/modules/ROOT/pages/clustering/databases.adoc
@@ -16,10 +16,12 @@ The `system` database contains metadata on the DBMS and security configuration.
When connected to this database you can only perform a specific set of administrative tasks, such as managing databases, servers, and access control.
In the clustered environment, the `system` database can be in a primary or secondary mode.
-To configure its mode, use the xref:configuration/configuration-settings.adoc#config_server.cluster.system_database_mode[`server.cluster.system_database_mode`] setting.
+To configure its mode, use the xref:configuration/configuration-settings.adoc#config_server.cluster.system_database_mode[`server.cluster.system_database_mode`] setting in the _neo4j.conf_ file.
+This has to be done before starting the Neo4j process.
Deploying a cluster for the first time, consider configuring the xref:configuration/configuration-settings.adoc#config_dbms.cluster.minimum_initial_system_primaries_count[`dbms.cluster.minimum_initial_system_primaries_count`].
This setting defaults to `3`.
+In a cluster, the `system` database forms its own Raft group.
See xref:clustering/setup/deploy.adoc[] for details.
For information on how to recover the `system` database, refer to the xref:clustering/multi-region-deployment/disaster-recovery.adoc[Disaster recovery guide].
diff --git a/modules/ROOT/pages/clustering/index.adoc b/modules/ROOT/pages/clustering/index.adoc
index e0ee411d2..318b18382 100644
--- a/modules/ROOT/pages/clustering/index.adoc
+++ b/modules/ROOT/pages/clustering/index.adoc
@@ -17,6 +17,7 @@ This chapter describes the following:
* xref:clustering/servers.adoc[Managing servers in a cluster] -- How to manage the servers in a cluster.
* xref:clustering/unbind.adoc[Unbind a server] -- How to remove and archive the cluster state of a cluster server so that it can rebind to a cluster.
* xref:clustering/databases.adoc[Managing databases in a cluster] -- How to manage the databases in a cluster.
+* xref:clustering/unbind-system-database.adoc[Unbind the `system` database] -- How to remove and archive the cluster state for the `system` database.
* Monitoring -- Monitoring of a cluster.
** xref:clustering/monitoring/show-servers-monitoring.adoc[Monitor servers] -- The tools available for monitoring the servers in a cluster.
** xref:clustering/monitoring/show-databases-monitoring.adoc[Monitor databases] -- The tools available for monitoring the databases in a cluster.
diff --git a/modules/ROOT/pages/clustering/server-syntax.adoc b/modules/ROOT/pages/clustering/server-syntax.adoc
index 983a95d01..5b6322f4c 100644
--- a/modules/ROOT/pages/clustering/server-syntax.adoc
+++ b/modules/ROOT/pages/clustering/server-syntax.adoc
@@ -1,11 +1,11 @@
:description: This section provides a summary of server management Cypher syntax.
[role=enterprise-edition]
[[server-commands-reference]]
-= Server commands reference
+= Server management command syntax
-Servers can be added and managed using a set of Cypher administration commands executed against the `system` database.
+Servers can be added and managed using a set of Cypher administrative commands executed against the `system` database.
-When connected to the DBMS over `bolt`, administration commands are automatically routed to the `system` database.
+When connected to the DBMS over `bolt`, administrative commands are automatically routed to the `system` database.
[[server-management-syntax]]
@@ -13,9 +13,11 @@ When connected to the DBMS over `bolt`, administration commands are automaticall
[NOTE]
====
-More details about the syntax descriptions can be found xref:database-administration/syntax.adoc[here].
+More details about the syntax descriptions can be found on the page xref:database-administration/syntax.adoc#administration-syntax-reading[Database management command syntax -> Reading the administrative commands syntax].
====
+=== Enable a server
+
[cols="<15s,<85"]
|===
| Command
@@ -38,43 +40,52 @@ a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===
+
+=== List servers
+
[cols="<15s,<85"]
|===
| Command
-m| ALTER SERVER
+m| SHOW SERVERS
| Syntax
a|
[source, syntax, role=noheader]
----
-ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}"
+SHOW SERVER[S]
+ [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
+ [WHERE expression]
+ [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
----
| Description
-a| Changes the constraints for a server.
-For more information see xref:clustering/servers.adoc#alter-server-options[Altering server options].
+a| Lists all servers visible to the cluster.
+For more information see xref:clustering/servers.adoc#_listing_servers[Listing servers].
| Required privilege
-a| `GRANT SERVER MANAGEMENT`
+a| `GRANT SHOW SERVERS`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===
+
+=== Alter server's options
+
[cols="<15s,<85"]
|===
| Command
-m| RENAME SERVER
+m| ALTER SERVER
| Syntax
a|
[source, syntax, role=noheader]
----
-RENAME SERVER 'name' TO 'newName'
+ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}"
----
| Description
-a| Changes the name of a server.
-For more information see xref:clustering/servers.adoc#_renaming_a_server[Renaming a server].
+a| Changes the constraints for a server.
+For more information see xref:clustering/servers.adoc#alter-server-options[Altering server options].
| Required privilege
a| `GRANT SERVER MANAGEMENT`
@@ -82,22 +93,23 @@ a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===
+=== Rename a server
[cols="<15s,<85"]
|===
| Command
-m| DEALLOCATE DATABASES
+m| RENAME SERVER
| Syntax
a|
[source, syntax, role=noheader]
----
-[DRYRUN] DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]
+RENAME SERVER 'name' TO 'newName'
----
| Description
-a| Removes all databases from the given servers.
-For more information see xref:clustering/servers.adoc#_deallocating_databases_from_a_server[Deallocating databases from server].
+a| Changes the name of a server.
+For more information see xref:clustering/servers.adoc#_renaming_a_server[Renaming a server].
| Required privilege
a| `GRANT SERVER MANAGEMENT`
@@ -105,6 +117,9 @@ a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===
+
+=== Remove a server
+
[cols="<15s,<85"]
|===
| Command
@@ -127,51 +142,55 @@ a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===
+
+=== Reallocate databases in a cluster
+
[cols="<15s,<85"]
|===
| Command
-m| SHOW SERVERS
+m| REALLOCATE DATABASES
| Syntax
a|
[source, syntax, role=noheader]
----
-SHOW SERVER[S]
- [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
- [WHERE expression]
- [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
+[DRYRUN] REALLOCATE DATABASE[S]
----
| Description
-a| Lists all servers visible to the cluster.
-For more information see xref:clustering/servers.adoc#_listing_servers[Listing servers].
+a| Re-balances databases among the servers in the cluster.
+For more information see xref:clustering/servers.adoc#_hosting_databases_on_added_servers[Hosting databases on added servers].
+
+Note that is a cluster-level command, not a server-level command.
| Required privilege
-a| `GRANT SHOW SERVERS`
+a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===
+
+=== Deallocate databases from a server
+
[cols="<15s,<85"]
|===
| Command
-m| REALLOCATE DATABASES
+m| DEALLOCATE DATABASES
| Syntax
a|
[source, syntax, role=noheader]
----
-[DRYRUN] REALLOCATE DATABASE[S]
+[DRYRUN] DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]
----
| Description
-a| Re-balances databases among the servers in the cluster.
-For more information see xref:clustering/servers.adoc#_hosting_databases_on_added_servers[Hosting databases on added servers].
-
-Note that is a cluster-level command, not a server-level command.
+a| Removes all databases from the given servers.
+For more information see xref:clustering/servers.adoc#_deallocating_databases_from_a_server[Deallocating databases from server].
| Required privilege
a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===
+
diff --git a/modules/ROOT/pages/clustering/servers.adoc b/modules/ROOT/pages/clustering/servers.adoc
index f1e9e7eb1..346eb6294 100644
--- a/modules/ROOT/pages/clustering/servers.adoc
+++ b/modules/ROOT/pages/clustering/servers.adoc
@@ -1,31 +1,32 @@
-:description: This section describes how to manage servers in a cluster.
+:description: This section describes how to manage servers in a Neo4j cluster.
:page-role: enterprise-edition
[[manage-servers]]
= Managing servers in a cluster
-As described previously, server-management is completely separate from database-management in a clustered environment.
+In a clustered environment, server management is completely separate from database management.
This section describes how to work with servers in a cluster: adding and removing them, as well as altering their metadata.
-[[server-states]]
-== Server states
+For details on server management command syntax, see xref:clustering/server-syntax.adoc[].
-A server can exist in five different states within the DBMS:
+[[server-states]]
+== Server lifecycle
+A server can exist in six different states within the DBMS:
* Free
* Enabled
+* Cordoned
* Deallocating
* Deallocated
-* Cordoned
* Dropped
+image::server-lifecycle.svg[width="800", title="Server's lifecycle"]
-image::server-states4.png[width=800]
=== Free state
-When a server is discovered by the discovery service (see xref:clustering/setup/discovery.adoc[Cluster server discovery] for more information), it is created in the _Free_ state.
+When a server is discovered by the discovery service (see xref:clustering/setup/discovery.adoc[Setting up a cluster -> Cluster server discovery] for more information), it is created in the _free_ state.
Servers in this state have a unique automatically generated ID, but are otherwise unconfigured.
These free servers are not yet part of the cluster and cannot be allocated to host any databases.
@@ -40,11 +41,12 @@ When first discovered, a server's name defaults to the value of its generated se
When you deploy a cluster for the first time, at least the minimum number of servers included in the initial deployment are automatically enabled.
For details, refer to the example on how to xref:clustering/setup/deploy.adoc#cluster-example-configure-a-three-primary-cluster[Configure a cluster with three servers].
-If you add a new server after the cluster is already running, the server is added in the `FREE` state.
-A server in the `FREE` state needs to be explicitly enabled in order to be considered an active member of the cluster.
+If you add a new server after the cluster is already running, the server is added in the `Free` state.
+A server in the `Free` state needs to be explicitly enabled in order to be considered an active member of the cluster.
-To transition a server into the _Enabled_ state, use the command `ENABLE SERVER`:
+To transition a server into the _enabled_ state, use the command `ENABLE SERVER`:
+.Syntax
[source, syntax, role=noheader]
----
ENABLE SERVER 'serverId' [OPTIONS "{" option: value[,...] "}"]
@@ -55,7 +57,7 @@ If the server is already enabled and the command is executed with the same optio
The possible options when enabling a server are:
-[options="header", width="100%", cols="2a,2,^.^"]
+[options="header", width="100%", cols="1a,2,3"]
|===
| Option
| Allowed values
@@ -108,58 +110,84 @@ Once enabled, the server may be allocated databases to host.
If you need to change some of the server's values, use the <> command.
+=== Cordoned state
+
+A server in a _cordoned_ state cannot be assigned to host any newly created databases; however, the server retains the databases it already hosts.
+
+This state is primarily used for <>.
+
+To transition a server from the _enabled_ to the _cordoned_ state, run the xref:procedures.adoc#procedure_dbms_cluster_cordonServer[`dbms.cluster.cordonServer()`] procedure.
+Keep in mind that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first.
+
+A server in the _cordoned_ state can be transitioned to _deallocating_ state or back to _enabled_.
+To re-enable a server, run the `ENABLE SERVER` command.
+In Cypher 5, you can also use the xref:procedures.adoc#procedure_dbms_cluster_uncordonServer[`dbms.cluster.uncordonServer()`] procedure.
+
+
[[deallocating-state]]
=== Deallocating state
-A server in a deallocating state means that it can no longer host databases.
+A _deallocating_ state means a server can no longer host databases.
It may be that the server is no longer needed and you want to remove it from the cluster.
-The command `DEALLOCATE DATABASE[S] FROM SERVER[S] _server_[,...]` is used to transition servers to the _Deallocating_ state, reallocating all their hosted databases to other servers in the cluster.
-[NOTE]
-====
+
+To transition servers to the _deallocating_ state, run the following command:
+
+[source, cypher, role="noplay"]
+----
+DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]
+----
+
+The command reallocates all their hosted databases to other servers in the cluster.
This state is *irreversible*.
-Once a server is in a deallocating state, it subsequently cannot have databases allocated to it.
+Once a server is in a deallocating state, it subsequently cannot have any further databases allocated to it.
-If you want to deallocate databases from a server in a *reversible manner*, see xref:clustering/databases.adoc#deallocate-databases[Deallocate databases] for more information.
-====
+However, you can deallocate databases from a server in a *reversible manner* by running one of the following procedures:
+
+* xref:procedures.adoc#procedure_dbms_cluster_deallocateDatabaseFromServer[`dbms.cluster.deallocateDatabaseFromServer("server-name", "database-name")`]
+* xref:procedures.adoc#procedure_dbms_cluster_deallocateDatabaseFromServers[`dbms.cluster.deallocateDatabaseFromServers(["server-name1", "server-name2"\], "database-name")`]
+* xref:procedures.adoc#procedure_dbms_cluster_deallocateNumberOfDatabases[`dbms.cluster.deallocateNumberOfDatabases("server-name", number)`]
+For details, see xref:clustering/databases.adoc#deallocate-databases[Managing databases in a cluster -> Deallocate databases].
+
+
+[[deallocated-state]]
=== Deallocated state
-When a server is in the deallocated state, it no longer hosts any databases besides `system` and can be removed from the cluster.
+The _deallocated_ state means that a server no longer hosts any databases besides the `system` database and can be removed from the cluster.
Additionally, deallocated servers cannot have any further databases allocated to them.
-Note that there is a known situation in which a previously deallocated offline server can transiently show as deallocating when restarting, it will, however, eventually return to the deallocated state without intervention.
-=== Cordoned state
+Note that there is a known situation in which a previously deallocated offline server can transiently show as deallocating when restarting, it will, however, eventually return to the deallocated state without intervention.
-The _Cordoned_ state is similar to _Deallocating_ in that servers in this state will not be allocated to host additional databases.
-Unlike _Deallocating_ however, cordoned servers do not lose the databases they already host.
-It is worth noting that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first.
-A server is transitioned from the _Enabled_ state to the _Cordoned_ state by executing the procedure `dbms.cluster.cordonServer`.
-A server in the _Cordoned_ state may be transitioned to _Deallocating_, or back to _Enabled_.
+=== Dropped state
-This state is primarily used for xref:clustering/servers.adoc#server-error-handling[error handling].
+The _dropped_ state means a server has been removed from the cluster but remains visible to the other cluster members.
-=== Dropped state
+Once a server is in the _deallocated_ state and is only hosting the `system` database, it is safe to remove it.
+Use the command `DROP SERVER 'server name'` to remove the server from the cluster.
-Once a server is in state _Deallocating_ and is only hosting the system database, it is safe to drop it.
-The command `DROP SERVER _server name_` logically removes the server from the cluster.
-However, as long as the server's Neo4j process is running, it is still visible to the other cluster members in the _Dropped_ state.
-Once the Neo4j process is stopped, the server finally disappears.
+However, as long as the server's Neo4j process is running, it is still visible to the other cluster members in the _dropped_ state.
+When the Neo4j process is stopped, the server finally disappears.
Once dropped, a server cannot rejoin a cluster.
[NOTE]
====
-The same physical hardware can rejoin the cluster, provided the Neo4j installation has been "reset" (either re-installing, or running `neo4j-admin server unbind`), causing it to receive a new generated server ID on next startup.
+To allow the same physical hardware to rejoin the cluster, reset the Neo4j installation by either:
+
+* Reinstalling Neo4j.
+* Running the xref:clustering/unbind.adoc[`neo4j-admin server unbind`] command.
+
+This process ensures a new server ID is generated when the server starts again.
====
== Listing servers
-The Cypher command `SHOW SERVERS` displays all current servers running in the cluster, including both servers yet to be enabled (i.e. servers in the _Free_ state) in the DBMS as well as dropped servers.
+The Cypher command `SHOW SERVERS` displays all current servers running in the cluster, including servers yet to be enabled (i.e. servers in the _free_ state) in the DBMS as well as dropped servers.
[source,cypher,role=noplay]
----
-neo4j@neo4j> SHOW SERVERS;
+neo4j@system> SHOW SERVERS;
+------------------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+------------------------------------------------------------------------------------------------------------------+
@@ -175,7 +203,7 @@ To display all available information about the servers in the cluster, use `SHOW
[source,cypher, role=noplay]
----
-neo4j@neo4j> SHOW SERVERS YIELD *;
+neo4j@system> SHOW SERVERS YIELD *;
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| serverId | name | address | httpAddress | httpsAddress | state | health | hosting | requestedHosting | tags | allowedDatabases | deniedDatabases | modeConstraint | version |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -188,8 +216,9 @@ neo4j@neo4j> SHOW SERVERS YIELD *;
----
-The table of results shows information about the servers:
+The table of results shows information about the servers.
+.The `SHOW SERVERS` output modes
[options="header", width="100%", cols="2a,4,2m,1,1"]
|===
| Column
@@ -205,7 +234,7 @@ The table of results shows information about the servers:
| {check-mark}
| serverId
-| Id of the server.
+| ID of the server.
| STRING
|
| {check-mark}
@@ -217,25 +246,25 @@ The table of results shows information about the servers:
| {check-mark}
| httpAddress
-| Http address of the server (if enabled).
+| HTTP address of the server (if enabled).
| STRING
|
| {check-mark}
| httpsAddress
-| Https address of the server (if enabled).
+| HTTPS address of the server (if enabled).
| STRING
|
| {check-mark}
| state
-| Information of the state of the server: `free`, `enabled`, `deallocating`,`cordoned`, or `dropped`.
+| Information of the state of the server. Possible values are `Free`, `Enabled`, `Cordoned`, `Deallocating`, `Deallocated`, or `Dropped`.
| STRING
| {check-mark}
| {check-mark}
| health
-| The availability of the server: `available` or `unavailable`.
+| The availability of the server: `Available` or `Unavailable`.
| STRING
| {check-mark}
| {check-mark}
@@ -286,59 +315,60 @@ Composite databases do not currently appear in this list, though they do appear
[[cluster-add-server]]
-== Add a server to the cluster
+== Adding a server to the cluster
-To add a server to a running cluster (see xref:clustering/setup/deploy.adoc[Deploy a basic cluster] for more information on how to set up a basic cluster), configure it to discover other existing cluster members.
+To add a server to a running cluster, configure it to discover other existing cluster members.
There are several different ways to do this, see xref:clustering/setup/discovery.adoc[Cluster server discovery].
-Once the new server is configured to discover the cluster's members, it can be started.
-Once started, the new server appears in the output of `SHOW SERVERS` with the _Free_ state.
-Copy the server's name from `SHOW SERVERS` and enable it:
+In the example below, you set `dbms.cluster.discovery.resolver_type=LIST`.
-[source,cypher]
+. Prepare the _neo4j.conf_ file for the new `server.07`.
++
+._neo4j.conf_ on server07.example.com:
+[source, properties]
----
-neo4j@neo4j> ENABLE SERVER '42a97acc-acf6-40c0-aff2-3993e90db1ff';
+server.default_listen_address=0.0.0.0
+server.default_advertised_address=server07.example.com
+dbms.cluster.discovery.resolver_type=LIST
+dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000,server06.example.com:6000,
+server.cluster.system_database_mode=PRIMARY
----
++
+Additionally, you can configure a set of initial settings to provide values for the server's options.
+Those settings will be used as the default input for the `ENABLE SERVER` command:
++
+[source,properties]
+----
+initial.server.mode_constraint='PRIMARY'
+initial.server.allowed_databases='foo'
+initial.server.denied_databases='bar','baz'
+initial.server.tags=eu,eu-west
+----
++
+Besides, you can also set the xref:configuration/configuration-settings.adoc#config_initial.dbms.automatically_enable_free_servers[`initial.dbms.automatically_enable_free_servers`] to `true`, allowing the DBMS automatically enable a free server.
-The `ENABLE` command can take several options:
-
+. Once the new server is configured to discover the cluster's members, start the Neo4j process.
+. Once started, the new server appears in the output of `SHOW SERVERS` with the `Free` state.
+. Copy the server's ID from the `SHOW SERVERS` output and enable the server.
++
+The `ENABLE SERVER` command can take several options and it will override the initial settings if they are conflicting:
++
[source,cypher, role=noplay]
----
-neo4j@neo4j> ENABLE SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' OPTIONS
+neo4j@system> ENABLE SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' OPTIONS
{modeConstraint:'PRIMARY', allowedDatabases:['foo'], tags:['eu','eu-west']};
----
-
-`modeConstraint` is used to control whether a server can be used to host a database in only primary or secondary mode.
-`allowedDatabases` and `deniedDatabases` are collections of database names that filter which databases may be hosted on a server.
++
+* `modeConstraint` is used to control whether a server can be used to host a database in only primary, or only secondary mode, or both.
+* `allowedDatabases` and `deniedDatabases` are collections of database names that filter which databases may be hosted on a server.
The `allowedDatabases` and `deniedDatabases` are mutually exclusive and if both are specified, an error is returned.
-
-Optionally, it is possible to automatically enable free servers by setting the xref:configuration/configuration-settings.adoc#config_initial.dbms.automatically_enable_free_servers[`initial.dbms.automatically_enable_free_servers`] to `true`.
-This can be changed after startup using the xref:procedures.adoc#procedure_dbms_cluster_setAutomaticallyEnableFreeServers[`dbms.cluster.setAutomaticallyEnableFreeServers`] procedure.
-
-Server `tags` are used when configuring load balancing and replication policies.
+`allowedDatabases` and `deniedDatabases` do not affect composite databases, they are always available everywhere.
+* Server `tags` are used when configuring load balancing and replication policies.
They cannot contain duplicates, so `tags:['eu', 'eu']` will return an error.
Server tags also cannot contain commas.
When altering server tags via cypher, the encoding is done via UTF-8.
-
-[NOTE]
-====
-`allowedDatabases` and `deniedDatabases` do not affect Composite databases, they are always available everywhere.
-====
-
-If no options are set, a server can host any database in any mode.
-Servers can also provide default values for these options via their _neo4j.conf_ files when enabled.
-
-[source,properties]
-----
-initial.server.mode_constraint='PRIMARY'
-initial.server.allowed_databases='foo'
-initial.server.denied_databases='bar','baz'
-initial.server.tags=eu,eu-west
-----
-
-If conflicting options are provided between _neo4j.conf_ and the `ENABLE SERVER` command, those provided to `ENABLE SERVER` are used.
-
-[NOTE]
++
+[TIP]
====
The input for server tags is a comma-separated list that cannot have duplicates.
@@ -349,16 +379,18 @@ The _.conf_ files can use *UTF-8* by setting the environment variable `NEO4J_CON
This allows setting server tags with the larger character set via the config.
====
-=== Hosting databases on added servers
+
+== Hosting databases on added servers
Once enabled, a server does not automatically host databases unless:
* New databases are created.
* Existing database topologies are altered to request more hosts.
-* Another server is transitioned to the _Deallocating_ state.
+* Another server is transitioned to the _deallocating_ state.
* You explicitly rebalance the databases across the cluster.
-The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s), see xref:clustering/databases.adoc#reallocate-databases[Reallocate databases] for more information.
+The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s).
+See xref:clustering/databases.adoc#reallocate-databases[Managing databases in a cluster -> Reallocate databases] for more information.
[[removing-servers]]
@@ -368,25 +400,27 @@ Removing a server from the cluster requires two steps: deallocating, then droppi
=== Deallocating databases from a server
-In preparation for removing a server from the cluster, set it to not host any databases with `DEALLOCATE DATABASES FROM SERVER 'name'` (see xref:clustering/servers.adoc#deallocating-state[Deallocating state] for more information).
+In preparation for removing a server from the cluster, set it to not host any databases with the `DEALLOCATE DATABASES FROM SERVER 'name'` command.
+
+See <> for more information.
Either the server ID or its name can be used with the `DEALLOCATE DATABASES` command:
[source,cypher]
----
-neo4j@neo4j> DRYRUN DEALLOCATE DATABASES FROM SERVER '135ad202-5405-4d3c-9822-df39f59b823c';
+neo4j@system> DRYRUN DEALLOCATE DATABASES FROM SERVER '135ad202-5405-4d3c-9822-df39f59b823c';
----
When deallocating databases from servers, it is important to be mindful of the topology for each database to ensure that there are sufficient servers left in the cluster to satisfy the topologies of each database.
Attempting to deallocate database(s) from a server that would result in less available servers than required fails with an error and no changes are made.
-For example, if the cluster contains 5 servers and a database `foo` has a topology requiring 3 primaries and 2 secondaries, then it is _not_ possible to deallocate any of the original 5 servers, without first enabling a 6th, or altering the desired topology of `foo` to require fewer servers overall.
+For example, if the cluster contains five servers and a database `foo` has a topology requiring three primary copies and two secondary copies, then it is *not* possible to deallocate any of the original five servers, without first adding and enabling new unconstrained servers, or altering the desired topology of `foo` to require fewer servers overall.
The command can be used with `DRYRUN` to get a view of how the databases would be moved from the deallocated server(s).
[source,cypher]
----
-neo4j@neo4j> DRYRUN DEALLOCATE DATABASES FROM SERVER '135ad202-5405-4d3c-9822-df39f59b823c';
+neo4j@system> DRYRUN DEALLOCATE DATABASES FROM SERVER '135ad202-5405-4d3c-9822-df39f59b823c';
+------------------------------------------------------------------------------------------------------------------------------------------+
| database | fromServerName | fromServerId | toServerName | toServerId | mode |
+------------------------------------------------------------------------------------------------------------------------------------------+
@@ -396,25 +430,26 @@ neo4j@neo4j> DRYRUN DEALLOCATE DATABASES FROM SERVER '135ad202-5405-4d3c-9822-df
[NOTE]
====
-Deallocation is currently prevented in the following situations.
+Deallocation is currently prevented in the following situations:
-* If a database the server is hosting is offline.
-* If the server is hosting a database with an allocation of 1 primary.
-* If a quorum of servers hosting the database in primary mode are cordoned.
+* If a database, the server is hosting, is offline.
+* If the server is hosting a database with an allocation of one primary.
+* If a quorum of servers, hosting the database in primary mode, are cordoned.
====
-Once the command has been executed, the server changes state to `deallocating` and it cannot readily be enabled again, see xref:clustering/servers.adoc#_dropped_state[Dropped state] for more information.
+Once the command has been executed, the server changes state to `Deallocating` and it cannot readily be enabled again.
+See <<#_dropped_state, dropped state>> for more information.
=== Dropping a server
-Once `DEALLOCATE DATABASES` is executed for a server, its databases begin being moved.
-It is important not to attempt the next step before `SHOW SERVERS` reports that the deallocating server is in the (xref:clustering/servers.adoc#deallocating-state[Deallocated state]).
+Once `DEALLOCATE DATABASES` is executed against a server, its databases begin being moved.
+It is important not to attempt the next step before `SHOW SERVERS` reports that the deallocating server is in the <>.
For example, do not drop the server `135ad202-5405-4d3c-9822-df39f59b823c` given the following output:
[source,cypher,role=noplay]
----
-neo4j@neo4j> SHOW SERVERS;
+SHOW SERVERS;
+------------------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+------------------------------------------------------------------------------------------------------------------+
@@ -424,15 +459,15 @@ neo4j@neo4j> SHOW SERVERS;
The deallocation process may take some time, as `foo` must be successfully copied and started on a new server before it is stopped on `135ad202-5405-4d3c-9822-df39f59b823c` in order to preserve the availability and fault tolerance of `foo`.
-Once `SHOW SERVERS` reflects that the server is deallocated and thus no longer hosts `foo`, the server may be dropped.
+Once `SHOW SERVERS` reflects that the server is `Deallocated` and thus no longer hosts `foo`, the server may be dropped.
Either the server ID or its name can be used:
[source,cypher]
----
-neo4j@neo4j> DROP SERVER '135ad202-5405-4d3c-9822-df39f59b823c';
+neo4j@system> DROP SERVER '135ad202-5405-4d3c-9822-df39f59b823c';
----
-Once this command has been executed successfully, the neo4j process on the server in question may be stopped.
+Once this command has been executed successfully, the Neo4j process on the server in question may be stopped.
== Controlling a server's metadata
@@ -442,11 +477,17 @@ Once this command has been executed successfully, the neo4j process on the serve
A running server can have its options modified using the `ALTER SERVER 'name' SET OPTIONS { option: value }` command.
Either the ID or the name of the server can be used.
+.Syntax
+[source, syntax, role=noheader]
+----
+ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}"
+----
+
For example, to prevent a server from hosting databases in `PRIMARY`, execute the following:
[source,cypher]
----
-neo4j@neo4j> ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {modeConstraint:'SECONDARY'};
+neo4j@system> ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {modeConstraint:'SECONDARY'};
----
Altering servers may cause databases to be moved, and should be performed with care.
@@ -484,7 +525,7 @@ This may not be specified in combination with `allowedDatabases`.
[NOTE]
====
-`allowedDatabases` and `deniedDatabases` do not affect Composite databases, they are always available everywhere.
+`allowedDatabases` and `deniedDatabases` do not affect composite databases; they are always available everywhere.
====
As with the `DEALLOCATE DATABASES FROM SERVER ...` command, if the alteration of a server's options renders it impossible for the cluster to satisfy one or more of the databases' topologies, then the command fails and no changes are made.
@@ -521,12 +562,18 @@ Always check the current configuration with `SHOW SERVERS YIELD *` and reapply u
=== Renaming a server
+.Syntax
+[source, syntax, role=noheader]
+----
+RENAME SERVER 'name' TO 'newName'
+----
+
When first discovered, a server's name defaults to the value of its generated server ID.
However, as long as the server is enabled, this can be changed later using the following command:
[source,cypher]
----
-neo4j@neo4j> RENAME SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' TO 'eu-server-4';
+neo4j@system> RENAME SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' TO 'eu-server-4';
----
This only affects the name of the server; the ID of the server remains fixed as `25a7efc7-d063-44b8-bdee-f23357f89f01`.
@@ -536,38 +583,40 @@ Keep in mind that the name of the server must be unique among existing servers.
== Error handling
Occasionally, servers in a cluster may suffer issues such as network partitions or process crashes.
-These easiest way to observe these server failures is by executing `SHOW SERVERS` and checking for `'Unavailable'` in the `health` column.
+The easiest way to observe these server failures is by executing `SHOW SERVERS` and checking for `Unavailable` in the `health` column.
[NOTE]
====
An `Available` health status does not indicate that a server is functioning perfectly, only that other servers in the cluster are able to make contact with it.
+
For more in depth monitoring of cluster and server health, see xref:clustering/monitoring/show-servers-monitoring.adoc[Monitor servers].
====
-If the issue with the `Unavailable` server proves permanent, then the server should be xref:clustering/servers.adoc#removing-servers[removed].
+If the issue with the `Unavailable` server proves permanent, then the server should be <>.
However, if the issue is temporary then it likely is not desirable to remove these servers entirely as this causes all their hosted databases to be moved.
Instead it is preferable to prevent those servers from being allocated any new databases to host, either as a result of databases being created or moved.
-This is known as _cordoning_ the server in question, and can be achieved by executing the following procedure against the `system` database:
+This is known as cordoning the server in question, and can be achieved by executing the following procedure against the `system` database:
[source,cypher]
----
-neo4j@neo4j> CALL dbms.cluster.cordonServer('25a7efc7-d063-44b8-bdee-f23357f89f01');
+neo4j@system> CALL dbms.cluster.cordonServer('25a7efc7-d063-44b8-bdee-f23357f89f01');
----
-`SHOW SERVERS` should then reflect that the server in question is now in _Cordoned_ state.
+`SHOW SERVERS` should then reflect that the server in question is now in _cordoned_ state.
-Once the issue with the server has been resolved, the server can be returned to its previous _Enabled_ state as follows:
+Once the issue with the server has been resolved, the server can be returned to its previous _enabled_ state as follows:
[source,cypher]
----
-neo4j@neo4j> ENABLE SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01';
+neo4j@system> ENABLE SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01';
----
[NOTE]
====
An unavailable server which has not been cordoned may still be allocated to host new databases.
-When the server recovers it observes that it is due to host these databases and begin catching up from some other available server (if one exists).
+When the server recovers it observes that it is due to host these databases and begin catching up from some other available servers (if one exists).
However, in the meantime those databases have reduced fault tolerance or, worse, reduced availability.
See xref:clustering/multi-region-deployment/disaster-recovery.adoc[Disaster Recovery] for more details.
====
+