doc/cephadm: rewrite client-setup.rst

This improves the text in client-setup.rst.

We should make certain that the technical details
in this file remain current in July 2021. This
file was origingally written in November 2019.

Signed-off-by: Zac Dover <zac.dover@gmail.com>

diff --git a/doc/cephadm/client-setup.rst b/doc/cephadm/client-setup.rst
index 3efc1cc11ffa7018afaa75eb386debd311d1e10d..f98ba798b5fd662f6532018970d1a9eca9eaca41 100644 (file)
--- a/doc/cephadm/client-setup.rst
+++ b/doc/cephadm/client-setup.rst
@@ -1,40 +1,45 @@
 =======================
 Basic Ceph Client Setup
 =======================
-Client machines need some basic configuration in order to interact with
-a cluster. This document describes how to configure a client machine
-for cluster interaction.
+Client machines require some basic configuration to interact with
+Ceph clusters. This section describes how to configure a client machine
+so that it can interact with a Ceph cluster.
 
-.. note:: Most client machines only need the `ceph-common` package and
-          its dependencies installed. That will supply the basic `ceph`
-          and `rados` commands, as well as other commands like
-          `mount.ceph` and `rbd`.
+.. note:: 
+   Most client machines need to install only the `ceph-common` package
+   and its dependencies. Such a setup supplies the basic `ceph` and
+   `rados` commands, as well as other commands including `mount.ceph`
+   and `rbd`.
 
 Config File Setup
 =================
-Client machines can generally get away with a smaller config file than
-a full-fledged cluster member. To generate a minimal config file, log
-into a host that is already configured as a client or running a cluster
-daemon, and then run
+Client machines usually require smaller configuration files (here
+sometimes called "config files") than do full-fledged cluster members.
+To generate a minimal config file, log into a host that has been
+configured as a client or that is running a cluster daemon, and then run the following command:
 
-.. code-block:: bash
+.. prompt:: bash #
 
-    ceph config generate-minimal-conf
+  ceph config generate-minimal-conf
 
-This will generate a minimal config file that will tell the client how to
-reach the Ceph Monitors. The contents of this file should typically be
-installed in `/etc/ceph/ceph.conf`.
+This command generates a minimal config file that tells the client how
+to reach the Ceph monitors. The contents of this file should usually 
+be installed in ``/etc/ceph/ceph.conf``.
 
 Keyring Setup
 =============
-Most Ceph clusters are run with authentication enabled, and the client will
-need keys in order to communicate with cluster machines. To generate a
-keyring file with credentials for `client.fs`, log into an extant cluster
-member and run
+Most Ceph clusters run with authentication enabled. This means that
+the client needs keys in order to communicate with the machines in the
+cluster. To generate a keyring file with credentials for `client.fs`,
+log into an running cluster member and run the following command:
 
-.. code-block:: bash
+.. prompt:: bash $
 
-    ceph auth get-or-create client.fs
+  ceph auth get-or-create client.fs
 
-The resulting output should be put into a keyring file, typically
-`/etc/ceph/ceph.keyring`.
+The resulting output is directed into a keyring file, typically
+``/etc/ceph/ceph.keyring``.
+
+To gain a broader understanding of client keyring distribution and administration, you should read :ref:`client_keyrings_and_configs`.
+
+To see an example that explains how to distribute ``ceph.conf`` configuration files to hosts that are tagged with the ``bare_config`` label, you should read the section called "Distributing ceph.conf to hosts tagged with bare_config" in the section called :ref:`etc_ceph_conf_distribution`.

diff --git a/doc/cephadm/operations.rst b/doc/cephadm/operations.rst
index 00f43a78e74d7b244105e140b366fd8859f17750..45ae1575b75408e38a4aca892e62522575a99c8a 100644 (file)
--- a/doc/cephadm/operations.rst
+++ b/doc/cephadm/operations.rst
@@ -384,6 +384,8 @@ The OS kernel version (maj.min) is checked for consistency across the hosts.
 The kernel version of the majority of the hosts is used as the basis for 
 identifying anomalies.
 
+.. _client_keyrings_and_configs:
+
 Client keyrings and configs
 ===========================
 
@@ -460,6 +462,7 @@ To disable management of a keyring file, run a command of the following form:
   This deletes any keyring files for this entity that were previously written
   to cluster nodes.
 
+.. _etc_ceph_conf_distribution:
 
 /etc/ceph/ceph.conf
 ===================
@@ -491,6 +494,11 @@ the following form:
 For example, to distribute configs to hosts with the ``bare_config`` label, run
 the following command:
 
+Distributing ceph.conf to hosts tagged with bare_config 
+-------------------------------------------------------
+
+For example, to distribute configs to hosts with the ``bare_config`` label, run the following command:
+
 .. prompt:: bash #
 
   ceph config set mgr mgr/cephadm/manage_etc_ceph_ceph_conf_hosts label:bare_config