From cf509f2888155f7e598a08aeaf69ded035cb8fb8 Mon Sep 17 00:00:00 2001
From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com>
Date: Wed, 4 Sep 2024 16:38:36 +1000
Subject: [PATCH] Clarify QDevice/QNetd configuration (#405)

* Clarify QDevice/QNetd configuration

bsc#1227649
jsc#DOCTEAM-1497

* Add root

* Apply suggestions from editorial review

Co-authored-by: Daria Vladykina <daria.vladykina@suse.com>

---------

Co-authored-by: Daria Vladykina <daria.vladykina@suse.com>
---
 xml/ha_qdevice-qnetd.xml | 47 +++++++++++++++++++++++++---------------
 1 file changed, 29 insertions(+), 18 deletions(-)

diff --git a/xml/ha_qdevice-qnetd.xml b/xml/ha_qdevice-qnetd.xml
index 25b96115..0a303937 100644
--- a/xml/ha_qdevice-qnetd.xml
+++ b/xml/ha_qdevice-qnetd.xml
@@ -207,8 +207,8 @@
    <sect1 xml:id="sec-ha-qdevice-setup-qnetd">
       <title>Setting up the &qnet; server</title>
       <para>
-         The &qnet; server is not part of the cluster stack, and it is also
-         not a real member of your cluster. As such, you cannot move resources
+         The &qnet; server runs outside the cluster and can support multiple clusters
+         (as long as each cluster has a unique name). As such, you cannot move resources
          to this server.
       </para>
       <para>
@@ -251,8 +251,8 @@
 
       <para>
          Your &qnet; server is ready to accept connections from a &qdevice; client
-         <systemitem>corosync-qdevice</systemitem>.
-         Further configuration is not needed.
+         (<systemitem>corosync-qdevice</systemitem>).
+         Further configuration is handled by &crmsh; when you connect &qdevice; clients.
       </para>
    </sect1>
 
@@ -264,6 +264,12 @@
          of your cluster, or you can add them later. This procedure documents how
          to add them later.
       </para>
+      <important role="compact">
+        <para>
+          To complete the &qnet; configuration, the clients must have &rootuser; SSH access
+          to the &qnet; server.
+        </para>
+       </important>
       <procedure>
          <step>
             <para>
@@ -289,22 +295,27 @@ Heuristics COMMAND to run with absolute path; For multiple commands, use ";" to
              remaining fields, you can accept the default values or change them
              if required.
             </para>
-            <important>
-             <title><literal>SBD_WATCHDOG_TIMEOUT</literal> for diskless SBD and &qdevice;</title>
-             <para>
-              If you use &qdevice; with diskless SBD, the <literal>SBD_WATCHDOG_TIMEOUT</literal>
-              value must be greater than &qdevice;'s <literal>sync_timeout</literal> value,
-              or SBD will time out and fail to start.
-             </para>
-             <para>
-              The default value for <literal>sync_timeout</literal> is 30 seconds.
-              Therefore, in the file <filename>/etc/sysconfig/sbd</filename>, make sure
-              that <literal>SBD_WATCHDOG_TIMEOUT</literal> is set to a greater value,
-              such as <literal>35</literal>.
-             </para>
-            </important>
          </step>
       </procedure>
+      <para>
+        The script configures &qdevice; on the nodes and completes the &qnet; configuration
+        on the &qnet; server, including generating CA and server certificates, starting the
+        &qnet; daemon, and updating the cluster's quorum configuration.
+      </para>
+      <important>
+        <title><literal>SBD_WATCHDOG_TIMEOUT</literal> for diskless SBD and &qdevice;</title>
+        <para>
+          If you use &qdevice; with diskless SBD, the <literal>SBD_WATCHDOG_TIMEOUT</literal>
+          value must be greater than &qdevice;'s <literal>sync_timeout</literal> value,
+          or SBD will time out and fail to start.
+        </para>
+        <para>
+          The default value for <literal>sync_timeout</literal> is 30 seconds.
+          Therefore, in the file <filename>/etc/sysconfig/sbd</filename>, make sure
+          that <literal>SBD_WATCHDOG_TIMEOUT</literal> is set to a greater value,
+          such as <literal>35</literal>.
+        </para>
+      </important>
    </sect1>
 
    <sect1 xml:id="sec-ha-qdevice-heuristic">