]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ======================== |
2 | Cephx Config Reference | |
3 | ======================== | |
4 | ||
5 | The ``cephx`` protocol is enabled by default. Cryptographic authentication has | |
6 | some computational costs, though they should generally be quite low. If the | |
11fdf7f2 | 7 | network environment connecting your client and server hosts is very safe and |
7c673cae FG |
8 | you cannot afford authentication, you can turn it off. **This is not generally |
9 | recommended**. | |
10 | ||
11 | .. note:: If you disable authentication, you are at risk of a man-in-the-middle | |
11fdf7f2 | 12 | attack altering your client/server messages, which could lead to disastrous |
7c673cae FG |
13 | security effects. |
14 | ||
15 | For creating users, see `User Management`_. For details on the architecture | |
16 | of Cephx, see `Architecture - High Availability Authentication`_. | |
17 | ||
18 | ||
19 | Deployment Scenarios | |
20 | ==================== | |
21 | ||
11fdf7f2 TL |
22 | There are two main scenarios for deploying a Ceph cluster, which impact |
23 | how you initially configure Cephx. Most first time Ceph users use | |
f67539c2 | 24 | ``cephadm`` to create a cluster (easiest). For clusters using |
7c673cae | 25 | other deployment tools (e.g., Chef, Juju, Puppet, etc.), you will need |
11fdf7f2 | 26 | to use the manual procedures or configure your deployment tool to |
7c673cae FG |
27 | bootstrap your monitor(s). |
28 | ||
7c673cae FG |
29 | Manual Deployment |
30 | ----------------- | |
31 | ||
32 | When you deploy a cluster manually, you have to bootstrap the monitor manually | |
33 | and create the ``client.admin`` user and keyring. To bootstrap monitors, follow | |
34 | the steps in `Monitor Bootstrapping`_. The steps for monitor bootstrapping are | |
35 | the logical steps you must perform when using third party deployment tools like | |
36 | Chef, Puppet, Juju, etc. | |
37 | ||
38 | ||
39 | Enabling/Disabling Cephx | |
40 | ======================== | |
41 | ||
42 | Enabling Cephx requires that you have deployed keys for your monitors, | |
11fdf7f2 | 43 | OSDs and metadata servers. If you are simply toggling Cephx on / off, |
7c673cae FG |
44 | you do not have to repeat the bootstrapping procedures. |
45 | ||
46 | ||
47 | Enabling Cephx | |
48 | -------------- | |
49 | ||
50 | When ``cephx`` is enabled, Ceph will look for the keyring in the default search | |
11fdf7f2 TL |
51 | path, which includes ``/etc/ceph/$cluster.$name.keyring``. You can override |
52 | this location by adding a ``keyring`` option in the ``[global]`` section of | |
7c673cae FG |
53 | your `Ceph configuration`_ file, but this is not recommended. |
54 | ||
55 | Execute the following procedures to enable ``cephx`` on a cluster with | |
56 | authentication disabled. If you (or your deployment utility) have already | |
57 | generated the keys, you may skip the steps related to generating keys. | |
58 | ||
11fdf7f2 | 59 | #. Create a ``client.admin`` key, and save a copy of the key for your client |
f67539c2 TL |
60 | host |
61 | ||
62 | .. prompt:: bash $ | |
7c673cae | 63 | |
f67539c2 | 64 | ceph auth get-or-create client.admin mon 'allow *' mds 'allow *' mgr 'allow *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring |
7c673cae | 65 | |
11fdf7f2 TL |
66 | **Warning:** This will clobber any existing |
67 | ``/etc/ceph/client.admin.keyring`` file. Do not perform this step if a | |
7c673cae FG |
68 | deployment tool has already done it for you. Be careful! |
69 | ||
11fdf7f2 | 70 | #. Create a keyring for your monitor cluster and generate a monitor |
f67539c2 | 71 | secret key. |
7c673cae | 72 | |
f67539c2 TL |
73 | .. prompt:: bash $ |
74 | ||
75 | ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon. --cap mon 'allow *' | |
7c673cae | 76 | |
11fdf7f2 TL |
77 | #. Copy the monitor keyring into a ``ceph.mon.keyring`` file in every monitor's |
78 | ``mon data`` directory. For example, to copy it to ``mon.a`` in cluster ``ceph``, | |
f67539c2 TL |
79 | use the following |
80 | ||
81 | .. prompt:: bash $ | |
82 | ||
83 | cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/keyring | |
84 | ||
85 | #. Generate a secret key for every MGR, where ``{$id}`` is the MGR letter | |
7c673cae | 86 | |
f67539c2 | 87 | .. prompt:: bash $ |
7c673cae | 88 | |
f67539c2 | 89 | ceph auth get-or-create mgr.{$id} mon 'allow profile mgr' mds 'allow *' osd 'allow *' -o /var/lib/ceph/mgr/ceph-{$id}/keyring |
11fdf7f2 | 90 | |
f67539c2 | 91 | #. Generate a secret key for every OSD, where ``{$id}`` is the OSD number |
11fdf7f2 | 92 | |
f67539c2 | 93 | .. prompt:: bash $ |
7c673cae | 94 | |
f67539c2 | 95 | ceph auth get-or-create osd.{$id} mon 'allow rwx' osd 'allow *' -o /var/lib/ceph/osd/ceph-{$id}/keyring |
7c673cae | 96 | |
f67539c2 | 97 | #. Generate a secret key for every MDS, where ``{$id}`` is the MDS letter |
7c673cae | 98 | |
f67539c2 TL |
99 | .. prompt:: bash $ |
100 | ||
101 | ceph auth get-or-create mds.{$id} mon 'allow rwx' osd 'allow *' mds 'allow *' mgr 'allow profile mds' -o /var/lib/ceph/mds/ceph-{$id}/keyring | |
7c673cae | 102 | |
11fdf7f2 | 103 | #. Enable ``cephx`` authentication by setting the following options in the |
f67539c2 TL |
104 | ``[global]`` section of your `Ceph configuration`_ file |
105 | ||
106 | .. code-block:: ini | |
7c673cae | 107 | |
f67539c2 TL |
108 | auth_cluster_required = cephx |
109 | auth_service_required = cephx | |
110 | auth_client_required = cephx | |
7c673cae FG |
111 | |
112 | ||
11fdf7f2 | 113 | #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details. |
7c673cae FG |
114 | |
115 | For details on bootstrapping a monitor manually, see `Manual Deployment`_. | |
116 | ||
117 | ||
118 | ||
119 | Disabling Cephx | |
120 | --------------- | |
121 | ||
122 | The following procedure describes how to disable Cephx. If your cluster | |
123 | environment is relatively safe, you can offset the computation expense of | |
124 | running authentication. **We do not recommend it.** However, it may be easier | |
125 | during setup and/or troubleshooting to temporarily disable authentication. | |
126 | ||
11fdf7f2 | 127 | #. Disable ``cephx`` authentication by setting the following options in the |
f67539c2 TL |
128 | ``[global]`` section of your `Ceph configuration`_ file |
129 | ||
130 | .. code-block:: ini | |
7c673cae | 131 | |
f67539c2 TL |
132 | auth_cluster_required = none |
133 | auth_service_required = none | |
134 | auth_client_required = none | |
7c673cae FG |
135 | |
136 | ||
137 | #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details. | |
138 | ||
139 | ||
140 | Configuration Settings | |
141 | ====================== | |
142 | ||
143 | Enablement | |
144 | ---------- | |
145 | ||
146 | ||
20effc67 TL |
147 | .. confval:: auth_cluster_required |
148 | .. confval:: auth_service_required | |
149 | .. confval:: auth_client_required | |
7c673cae FG |
150 | |
151 | .. index:: keys; keyring | |
152 | ||
153 | Keys | |
154 | ---- | |
155 | ||
156 | When you run Ceph with authentication enabled, ``ceph`` administrative commands | |
157 | and Ceph Clients require authentication keys to access the Ceph Storage Cluster. | |
158 | ||
159 | The most common way to provide these keys to the ``ceph`` administrative | |
160 | commands and clients is to include a Ceph keyring under the ``/etc/ceph`` | |
f67539c2 | 161 | directory. For Octopus and later releases using ``cephadm``, the filename |
7c673cae FG |
162 | is usually ``ceph.client.admin.keyring`` (or ``$cluster.client.admin.keyring``). |
163 | If you include the keyring under the ``/etc/ceph`` directory, you don't need to | |
164 | specify a ``keyring`` entry in your Ceph configuration file. | |
165 | ||
166 | We recommend copying the Ceph Storage Cluster's keyring file to nodes where you | |
167 | will run administrative commands, because it contains the ``client.admin`` key. | |
168 | ||
39ae355f | 169 | To perform this step manually, execute the following: |
7c673cae | 170 | |
39ae355f TL |
171 | .. prompt:: bash $ |
172 | ||
173 | sudo scp {user}@{ceph-cluster-host}:/etc/ceph/ceph.client.admin.keyring /etc/ceph/ceph.client.admin.keyring | |
7c673cae | 174 | |
11fdf7f2 | 175 | .. tip:: Ensure the ``ceph.keyring`` file has appropriate permissions set |
7c673cae FG |
176 | (e.g., ``chmod 644``) on your client machine. |
177 | ||
178 | You may specify the key itself in the Ceph configuration file using the ``key`` | |
179 | setting (not recommended), or a path to a keyfile using the ``keyfile`` setting. | |
180 | ||
20effc67 TL |
181 | .. confval:: keyring |
182 | :default: /etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin | |
183 | .. confval:: keyfile | |
184 | .. confval:: key | |
7c673cae FG |
185 | |
186 | .. index:: signatures | |
187 | ||
188 | Signatures | |
189 | ---------- | |
190 | ||
28e407b8 AA |
191 | Ceph performs a signature check that provides some limited protection |
192 | against messages being tampered with in flight (e.g., by a "man in the | |
193 | middle" attack). | |
7c673cae FG |
194 | |
195 | Like other parts of Ceph authentication, Ceph provides fine-grained control so | |
f67539c2 TL |
196 | you can enable/disable signatures for service messages between clients and |
197 | Ceph, and so you can enable/disable signatures for messages between Ceph daemons. | |
7c673cae | 198 | |
28e407b8 AA |
199 | Note that even with signatures enabled data is not encrypted in |
200 | flight. | |
7c673cae | 201 | |
20effc67 TL |
202 | .. confval:: cephx_require_signatures |
203 | .. confval:: cephx_cluster_require_signatures | |
204 | .. confval:: cephx_service_require_signatures | |
205 | .. confval:: cephx_sign_messages | |
7c673cae FG |
206 | |
207 | Time to Live | |
208 | ------------ | |
209 | ||
20effc67 | 210 | .. confval:: auth_service_ticket_ttl |
7c673cae | 211 | |
7c673cae FG |
212 | .. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping |
213 | .. _Operating a Cluster: ../../operations/operating | |
214 | .. _Manual Deployment: ../../../install/manual-deployment | |
7c673cae | 215 | .. _Ceph configuration: ../ceph-conf |
7c673cae FG |
216 | .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication |
217 | .. _User Management: ../../operations/user-management |