doc/cephadm: improve "Maintenance Mode"

Improve the English in the section "Maintenance Mode" in the file
doc/cephadm/host-management.rst.

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 2d4ee6aea3a3003eff910feb130110a6588fb384)

diff --git a/doc/cephadm/host-management.rst b/doc/cephadm/host-management.rst
index 2486a90b7f59d347a3621caa72f41e40fcefa72b..b0d015a4a2295a553209c2f15506c0648750b91c 100644 (file)
--- a/doc/cephadm/host-management.rst
+++ b/doc/cephadm/host-management.rst
@@ -228,22 +228,34 @@ The following host labels have a special meaning to cephadm.  All start with ``_
 Maintenance Mode
 ================
 
-Place a host in and out of maintenance mode (stops all Ceph daemons on host):
+Putting a host into "maintenance mode" stops all Ceph daemons on the host. Run
+a command of the following form to put a host into maintenance mode or to take
+a host out of maintenance mode: 
 
 .. prompt:: bash #
 
    ceph orch host maintenance enter <hostname> [--force] [--yes-i-really-mean-it]
    ceph orch host maintenance exit <hostname>
 
-The ``--force`` flag allows the user to bypass warnings (but not alerts). The ``--yes-i-really-mean-it``
-flag bypasses all safety checks and will attempt to force the host into maintenance mode no
-matter what.
-
-.. warning:: Using the --yes-i-really-mean-it flag to force the host to enter maintenance
-   mode can potentially cause loss of data availability, the mon quorum to break down due
-   to too few running monitors, mgr module commands (such as ``ceph orch . . .`` commands)
-   to be become unresponsive, and a number of other possible issues. Please only use this
-   flag if you're absolutely certain you know what you're doing.
+* Adding the ``--force`` flag to the ``enter`` command allows the user to bypass
+  warnings (but not alerts). 
+* Adding the ``--yes-i-really-mean-it`` flag to the ``enter`` command bypasses
+  all safety checks and makes an attempt to force the host into maintenance
+  mode.
+* Adding the ``--force`` and ``--offline`` flags to the ``exit`` command cause
+  cephadm to mark hosts that are in maintenance mode and offline as no longer
+  in maintenance mode. Note that if the host comes online, the Ceph daemons on
+  the host will remain in the stopped state. The ``--force`` and ``--offline``
+  flags of the ``exit`` command are meant to be run on hosts that are in
+  maintenance mode and that are permanently offline prior to the removal of
+  those hosts from cephadm management by running the ``ceph orch host rm``
+  command.
+
+.. warning:: Using the ``--yes-i-really-mean-it`` flag to force the host to
+   enter maintenance mode can cause loss of data availability, breakdown of the
+   mon quorum due to too few running monitors, unresponsive mgr module commands
+   (such as ``ceph orch . . .`` commands), and other issues. Use this flag only
+   if you're absolutely certain that you know what you're doing.
 
 See also :ref:`cephadm-fqdn`