From: Zac Dover Date: Mon, 12 Jul 2021 20:07:49 +0000 (+1000) Subject: doc/cephadm: rewrite client-setup.rst X-Git-Tag: v17.1.0~1134^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=18a15891df23222a60affdf9cfcd5760cfb0fa05;p=ceph-ci.git 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 --- diff --git a/doc/cephadm/client-setup.rst b/doc/cephadm/client-setup.rst index 3efc1cc11ff..f98ba798b5f 100644 --- 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 00f43a78e74..45ae1575b75 100644 --- 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