api-viewer: use verbose_description if available

[pve-docs.git] / pvecm.adoc

diff --git a/pvecm.adoc b/pvecm.adoc
index 5f99fd1020ebf0ea0818d37cfb5d9d51b3c524c2..6f8b3826c63dd38a9a38593258552a4c6cd0d699 100644 (file)
--- a/pvecm.adoc
+++ b/pvecm.adoc
@@ -89,7 +89,6 @@ hostname and IP is not possible after cluster creation.
 Currently the cluster creation has to be done on the console, so you
 need to login via 'ssh'.
 
-
 Create the Cluster
 ------------------
 
@@ -98,6 +97,10 @@ your cluster. This name cannot be changed later.
 
  hp1# pvecm create YOUR-CLUSTER-NAME
 
+CAUTION: The cluster name is used to compute the default multicast
+address. Please use unique cluster names if you run more than one
+cluster inside your network.
+
 To check the state of your cluster use:
 
  hp1# pvecm status
@@ -278,6 +281,50 @@ cluster again, you have to
 * then join it, as explained in the previous section.
 
 
+Quorum
+------
+
+{pve} use a quorum-based technique to provide a consistent state among
+all cluster nodes.
+
+[quote, from Wikipedia, Quorum (distributed computing)]
+____
+A quorum is the minimum number of votes that a distributed transaction
+has to obtain in order to be allowed to perform an operation in a
+distributed system.
+____
+
+In case of network partitioning, state changes requires that a
+majority of nodes are online. The cluster switches to read-only mode
+if it loose quorum.
+
+NOTE: {pve} assigns a single vote to each node by default.
+
+
+Cluster Cold Start
+------------------
+
+It is obvious that a cluster is not quorate when all nodes are
+offline. This is a common case after a power failure.
+
+NOTE: It is always a good idea to use an uninterruptible power supply
+('UPS', also called 'battery backup') to avoid this state. Especially if
+you want HA.
+
+On node startup, service 'pve-manager' waits up to 60 seconds to reach
+quorum, and then starts all guests. If it fails to get quorum, that
+service simply aborts, and you need to start your guest manually once
+you have quorum.
+
+If you start all nodes at the same time (for example when power comes
+back), it is likely that you reach quorum within above timeout. But
+startup can fail if some nodes starts much faster than others, so you
+need to start your guest manually after reaching quorum. You can do
+that on the GUI, or on the command line with:
+
+ systemctl start pve-manager
+
+
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
 endif::manvolnum[]