From 7de47c56822bd3c4862d10b4da05c50fc9ae2a42 Mon Sep 17 00:00:00 2001
From: Jeff Layton <jlayton@redhat.com>
Date: Mon, 25 Nov 2019 13:38:49 -0500
Subject: [PATCH] doc: add a basic client configuration document

Signed-off-by: Jeff Layton <jlayton@redhat.com>
(cherry picked from commit 85df3a5fb2d388045c0b01bc5bd069a53b0216c5)
---
 doc/cephadm/client-setup.rst | 36 ++++++++++++++++++++++++++++++++++++
 doc/cephadm/index.rst        |  1 +
 2 files changed, 37 insertions(+)
 create mode 100644 doc/cephadm/client-setup.rst

diff --git a/doc/cephadm/client-setup.rst b/doc/cephadm/client-setup.rst
new file mode 100644
index 0000000000000..dd0bc32856732
--- /dev/null
+++ b/doc/cephadm/client-setup.rst
@@ -0,0 +1,36 @@
+=======================
+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.
+
+.. 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`.
+
+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::
+
+    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`.
+
+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::
+
+    ceph auth get-or-create client.fs
+
+The resulting output should be put into a keyring file, typically
+`/etc/ceph/ceph.keyring`.
diff --git a/doc/cephadm/index.rst b/doc/cephadm/index.rst
index e1be17e8d2fdf..4ffcab80abd83 100644
--- a/doc/cephadm/index.rst
+++ b/doc/cephadm/index.rst
@@ -34,5 +34,6 @@ versions of Ceph.
     Cephadm operations <operations>
     Cephadm monitoring <monitoring>
     Cephadm CLI <../mgr/orchestrator>
+    Client Setup <client-setup>
     DriveGroups <drivegroups>
     troubleshooting
-- 
2.39.5