]>
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 | |
7 | network environment connecting your client and server hosts is very safe and | |
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 | |
12 | attack altering your client/server messages, which could lead to disastrous | |
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 | ||
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 | |
24 | ``ceph-deploy`` to create a cluster (easiest). For clusters using | |
25 | other deployment tools (e.g., Chef, Juju, Puppet, etc.), you will need | |
26 | to use the manual procedures or configure your deployment tool to | |
27 | bootstrap your monitor(s). | |
28 | ||
29 | ceph-deploy | |
30 | ----------- | |
31 | ||
32 | When you deploy a cluster with ``ceph-deploy``, you do not have to bootstrap the | |
33 | monitor manually or create the ``client.admin`` user or keyring. The steps you | |
34 | execute in the `Storage Cluster Quick Start`_ will invoke ``ceph-deploy`` to do | |
35 | that for you. | |
36 | ||
37 | When you execute ``ceph-deploy new {initial-monitor(s)}``, Ceph will create a | |
38 | monitor keyring for you (only used to bootstrap monitors), and it will generate | |
39 | an initial Ceph configuration file for you, which contains the following | |
40 | authentication settings, indicating that Ceph enables authentication by | |
41 | default:: | |
42 | ||
43 | auth_cluster_required = cephx | |
44 | auth_service_required = cephx | |
45 | auth_client_required = cephx | |
46 | ||
47 | When you execute ``ceph-deploy mon create-initial``, Ceph will bootstrap the | |
48 | initial monitor(s), retrieve a ``ceph.client.admin.keyring`` file containing the | |
49 | key for the ``client.admin`` user. Additionally, it will also retrieve keyrings | |
50 | that give ``ceph-deploy`` and ``ceph-disk`` utilities the ability to prepare and | |
51 | activate OSDs and metadata servers. | |
52 | ||
53 | When you execute ``ceph-deploy admin {node-name}`` (**note:** Ceph must be | |
54 | installed first), you are pushing a Ceph configuration file and the | |
55 | ``ceph.client.admin.keyring`` to the ``/etc/ceph`` directory of the node. You | |
56 | will be able to execute Ceph administrative functions as ``root`` on the command | |
57 | line of that node. | |
58 | ||
59 | ||
60 | Manual Deployment | |
61 | ----------------- | |
62 | ||
63 | When you deploy a cluster manually, you have to bootstrap the monitor manually | |
64 | and create the ``client.admin`` user and keyring. To bootstrap monitors, follow | |
65 | the steps in `Monitor Bootstrapping`_. The steps for monitor bootstrapping are | |
66 | the logical steps you must perform when using third party deployment tools like | |
67 | Chef, Puppet, Juju, etc. | |
68 | ||
69 | ||
70 | Enabling/Disabling Cephx | |
71 | ======================== | |
72 | ||
73 | Enabling Cephx requires that you have deployed keys for your monitors, | |
74 | OSDs and metadata servers. If you are simply toggling Cephx on / off, | |
75 | you do not have to repeat the bootstrapping procedures. | |
76 | ||
77 | ||
78 | Enabling Cephx | |
79 | -------------- | |
80 | ||
81 | When ``cephx`` is enabled, Ceph will look for the keyring in the default search | |
82 | path, which includes ``/etc/ceph/$cluster.$name.keyring``. You can override | |
83 | this location by adding a ``keyring`` option in the ``[global]`` section of | |
84 | your `Ceph configuration`_ file, but this is not recommended. | |
85 | ||
86 | Execute the following procedures to enable ``cephx`` on a cluster with | |
87 | authentication disabled. If you (or your deployment utility) have already | |
88 | generated the keys, you may skip the steps related to generating keys. | |
89 | ||
90 | #. Create a ``client.admin`` key, and save a copy of the key for your client | |
91 | host:: | |
92 | ||
93 | ceph auth get-or-create client.admin mon 'allow *' mds 'allow *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring | |
94 | ||
95 | **Warning:** This will clobber any existing | |
96 | ``/etc/ceph/client.admin.keyring`` file. Do not perform this step if a | |
97 | deployment tool has already done it for you. Be careful! | |
98 | ||
99 | #. Create a keyring for your monitor cluster and generate a monitor | |
100 | secret key. :: | |
101 | ||
102 | ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon. --cap mon 'allow *' | |
103 | ||
104 | #. Copy the monitor keyring into a ``ceph.mon.keyring`` file in every monitor's | |
105 | ``mon data`` directory. For example, to copy it to ``mon.a`` in cluster ``ceph``, | |
106 | use the following:: | |
107 | ||
108 | cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/keyring | |
109 | ||
110 | #. Generate a secret key for every OSD, where ``{$id}`` is the OSD number:: | |
111 | ||
112 | ceph auth get-or-create osd.{$id} mon 'allow rwx' osd 'allow *' -o /var/lib/ceph/osd/ceph-{$id}/keyring | |
113 | ||
114 | #. Generate a secret key for every MDS, where ``{$id}`` is the MDS letter:: | |
115 | ||
116 | ceph auth get-or-create mds.{$id} mon 'allow rwx' osd 'allow *' mds 'allow *' -o /var/lib/ceph/mds/ceph-{$id}/keyring | |
117 | ||
118 | #. Enable ``cephx`` authentication by setting the following options in the | |
119 | ``[global]`` section of your `Ceph configuration`_ file:: | |
120 | ||
121 | auth cluster required = cephx | |
122 | auth service required = cephx | |
123 | auth client required = cephx | |
124 | ||
125 | ||
126 | #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details. | |
127 | ||
128 | For details on bootstrapping a monitor manually, see `Manual Deployment`_. | |
129 | ||
130 | ||
131 | ||
132 | Disabling Cephx | |
133 | --------------- | |
134 | ||
135 | The following procedure describes how to disable Cephx. If your cluster | |
136 | environment is relatively safe, you can offset the computation expense of | |
137 | running authentication. **We do not recommend it.** However, it may be easier | |
138 | during setup and/or troubleshooting to temporarily disable authentication. | |
139 | ||
140 | #. Disable ``cephx`` authentication by setting the following options in the | |
141 | ``[global]`` section of your `Ceph configuration`_ file:: | |
142 | ||
143 | auth cluster required = none | |
144 | auth service required = none | |
145 | auth client required = none | |
146 | ||
147 | ||
148 | #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details. | |
149 | ||
150 | ||
151 | Configuration Settings | |
152 | ====================== | |
153 | ||
154 | Enablement | |
155 | ---------- | |
156 | ||
157 | ||
158 | ``auth cluster required`` | |
159 | ||
160 | :Description: If enabled, the Ceph Storage Cluster daemons (i.e., ``ceph-mon``, | |
161 | ``ceph-osd``, and ``ceph-mds``) must authenticate with | |
162 | each other. Valid settings are ``cephx`` or ``none``. | |
163 | ||
164 | :Type: String | |
165 | :Required: No | |
166 | :Default: ``cephx``. | |
167 | ||
168 | ||
169 | ``auth service required`` | |
170 | ||
171 | :Description: If enabled, the Ceph Storage Cluster daemons require Ceph Clients | |
172 | to authenticate with the Ceph Storage Cluster in order to access | |
173 | Ceph services. Valid settings are ``cephx`` or ``none``. | |
174 | ||
175 | :Type: String | |
176 | :Required: No | |
177 | :Default: ``cephx``. | |
178 | ||
179 | ||
180 | ``auth client required`` | |
181 | ||
182 | :Description: If enabled, the Ceph Client requires the Ceph Storage Cluster to | |
183 | authenticate with the Ceph Client. Valid settings are ``cephx`` | |
184 | or ``none``. | |
185 | ||
186 | :Type: String | |
187 | :Required: No | |
188 | :Default: ``cephx``. | |
189 | ||
190 | ||
191 | .. index:: keys; keyring | |
192 | ||
193 | Keys | |
194 | ---- | |
195 | ||
196 | When you run Ceph with authentication enabled, ``ceph`` administrative commands | |
197 | and Ceph Clients require authentication keys to access the Ceph Storage Cluster. | |
198 | ||
199 | The most common way to provide these keys to the ``ceph`` administrative | |
200 | commands and clients is to include a Ceph keyring under the ``/etc/ceph`` | |
201 | directory. For Cuttlefish and later releases using ``ceph-deploy``, the filename | |
202 | is usually ``ceph.client.admin.keyring`` (or ``$cluster.client.admin.keyring``). | |
203 | If you include the keyring under the ``/etc/ceph`` directory, you don't need to | |
204 | specify a ``keyring`` entry in your Ceph configuration file. | |
205 | ||
206 | We recommend copying the Ceph Storage Cluster's keyring file to nodes where you | |
207 | will run administrative commands, because it contains the ``client.admin`` key. | |
208 | ||
209 | You may use ``ceph-deploy admin`` to perform this task. See `Create an Admin | |
210 | Host`_ for details. To perform this step manually, execute the following:: | |
211 | ||
212 | sudo scp {user}@{ceph-cluster-host}:/etc/ceph/ceph.client.admin.keyring /etc/ceph/ceph.client.admin.keyring | |
213 | ||
214 | .. tip:: Ensure the ``ceph.keyring`` file has appropriate permissions set | |
215 | (e.g., ``chmod 644``) on your client machine. | |
216 | ||
217 | You may specify the key itself in the Ceph configuration file using the ``key`` | |
218 | setting (not recommended), or a path to a keyfile using the ``keyfile`` setting. | |
219 | ||
220 | ||
221 | ``keyring`` | |
222 | ||
223 | :Description: The path to the keyring file. | |
224 | :Type: String | |
225 | :Required: No | |
226 | :Default: ``/etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin`` | |
227 | ||
228 | ||
229 | ``keyfile`` | |
230 | ||
231 | :Description: The path to a key file (i.e,. a file containing only the key). | |
232 | :Type: String | |
233 | :Required: No | |
234 | :Default: None | |
235 | ||
236 | ||
237 | ``key`` | |
238 | ||
239 | :Description: The key (i.e., the text string of the key itself). Not recommended. | |
240 | :Type: String | |
241 | :Required: No | |
242 | :Default: None | |
243 | ||
244 | ||
245 | Daemon Keyrings | |
246 | --------------- | |
247 | ||
248 | Administrative users or deployment tools (e.g., ``ceph-deploy``) may generate | |
249 | daemon keyrings in the same way as generating user keyrings. By default, Ceph | |
250 | stores daemons keyrings inside their data directory. The default keyring | |
251 | locations, and the capabilities necessary for the daemon to function, are shown | |
252 | below. | |
253 | ||
254 | ``ceph-mon`` | |
255 | ||
256 | :Location: ``$mon_data/keyring`` | |
257 | :Capabilities: ``mon 'allow *'`` | |
258 | ||
259 | ``ceph-osd`` | |
260 | ||
261 | :Location: ``$osd_data/keyring`` | |
262 | :Capabilities: ``mon 'allow profile osd' osd 'allow *'`` | |
263 | ||
264 | ``ceph-mds`` | |
265 | ||
266 | :Location: ``$mds_data/keyring`` | |
267 | :Capabilities: ``mds 'allow' mon 'allow profile mds' osd 'allow rwx'`` | |
268 | ||
269 | ``radosgw`` | |
270 | ||
271 | :Location: ``$rgw_data/keyring`` | |
272 | :Capabilities: ``mon 'allow rwx' osd 'allow rwx'`` | |
273 | ||
274 | ||
275 | .. note:: The monitor keyring (i.e., ``mon.``) contains a key but no | |
276 | capabilities, and is not part of the cluster ``auth`` database. | |
277 | ||
278 | The daemon data directory locations default to directories of the form:: | |
279 | ||
280 | /var/lib/ceph/$type/$cluster-$id | |
281 | ||
282 | For example, ``osd.12`` would be:: | |
283 | ||
284 | /var/lib/ceph/osd/ceph-12 | |
285 | ||
286 | You can override these locations, but it is not recommended. | |
287 | ||
288 | ||
289 | .. index:: signatures | |
290 | ||
291 | Signatures | |
292 | ---------- | |
293 | ||
28e407b8 AA |
294 | Ceph performs a signature check that provides some limited protection |
295 | against messages being tampered with in flight (e.g., by a "man in the | |
296 | middle" attack). | |
7c673cae FG |
297 | |
298 | Like other parts of Ceph authentication, Ceph provides fine-grained control so | |
299 | you can enable/disable signatures for service messages between the client and | |
300 | Ceph, and you can enable/disable signatures for messages between Ceph daemons. | |
301 | ||
28e407b8 AA |
302 | Note that even with signatures enabled data is not encrypted in |
303 | flight. | |
7c673cae FG |
304 | |
305 | ``cephx require signatures`` | |
306 | ||
307 | :Description: If set to ``true``, Ceph requires signatures on all message | |
308 | traffic between the Ceph Client and the Ceph Storage Cluster, and | |
309 | between daemons comprising the Ceph Storage Cluster. | |
310 | ||
28e407b8 AA |
311 | Ceph Argonaut and Linux kernel versions prior to 3.19 do |
312 | not support signatures; if such clients are in use this | |
313 | option can be turned off to allow them to connect. | |
314 | ||
7c673cae FG |
315 | :Type: Boolean |
316 | :Required: No | |
317 | :Default: ``false`` | |
318 | ||
319 | ||
320 | ``cephx cluster require signatures`` | |
321 | ||
322 | :Description: If set to ``true``, Ceph requires signatures on all message | |
323 | traffic between Ceph daemons comprising the Ceph Storage Cluster. | |
324 | ||
325 | :Type: Boolean | |
326 | :Required: No | |
327 | :Default: ``false`` | |
328 | ||
329 | ||
330 | ``cephx service require signatures`` | |
331 | ||
332 | :Description: If set to ``true``, Ceph requires signatures on all message | |
333 | traffic between Ceph Clients and the Ceph Storage Cluster. | |
334 | ||
335 | :Type: Boolean | |
336 | :Required: No | |
337 | :Default: ``false`` | |
338 | ||
339 | ||
340 | ``cephx sign messages`` | |
341 | ||
342 | :Description: If the Ceph version supports message signing, Ceph will sign | |
28e407b8 | 343 | all messages so they are more difficult to spoof. |
7c673cae FG |
344 | |
345 | :Type: Boolean | |
346 | :Default: ``true`` | |
347 | ||
348 | ||
349 | Time to Live | |
350 | ------------ | |
351 | ||
352 | ``auth service ticket ttl`` | |
353 | ||
354 | :Description: When the Ceph Storage Cluster sends a Ceph Client a ticket for | |
355 | authentication, the Ceph Storage Cluster assigns the ticket a | |
356 | time to live. | |
357 | ||
358 | :Type: Double | |
359 | :Default: ``60*60`` | |
360 | ||
361 | ||
362 | Backward Compatibility | |
363 | ====================== | |
364 | ||
365 | For Cuttlefish and earlier releases, see `Cephx`_. | |
366 | ||
367 | In Ceph Argonaut v0.48 and earlier versions, if you enable ``cephx`` | |
368 | authentication, Ceph only authenticates the initial communication between the | |
369 | client and daemon; Ceph does not authenticate the subsequent messages they send | |
370 | to each other, which has security implications. In Ceph Bobtail and subsequent | |
371 | versions, Ceph authenticates all ongoing messages between the entities using the | |
372 | session key set up for that initial authentication. | |
373 | ||
374 | We identified a backward compatibility issue between Argonaut v0.48 (and prior | |
375 | versions) and Bobtail (and subsequent versions). During testing, if you | |
376 | attempted to use Argonaut (and earlier) daemons with Bobtail (and later) | |
377 | daemons, the Argonaut daemons did not know how to perform ongoing message | |
378 | authentication, while the Bobtail versions of the daemons insist on | |
379 | authenticating message traffic subsequent to the initial | |
380 | request/response--making it impossible for Argonaut (and prior) daemons to | |
381 | interoperate with Bobtail (and subsequent) daemons. | |
382 | ||
383 | We have addressed this potential problem by providing a means for Argonaut (and | |
384 | prior) systems to interact with Bobtail (and subsequent) systems. Here's how it | |
385 | works: by default, the newer systems will not insist on seeing signatures from | |
386 | older systems that do not know how to perform them, but will simply accept such | |
387 | messages without authenticating them. This new default behavior provides the | |
388 | advantage of allowing two different releases to interact. **We do not recommend | |
389 | this as a long term solution**. Allowing newer daemons to forgo ongoing | |
390 | authentication has the unfortunate security effect that an attacker with control | |
391 | of some of your machines or some access to your network can disable session | |
392 | security simply by claiming to be unable to sign messages. | |
393 | ||
394 | .. note:: Even if you don't actually run any old versions of Ceph, | |
395 | the attacker may be able to force some messages to be accepted unsigned in the | |
396 | default scenario. While running Cephx with the default scenario, Ceph still | |
397 | authenticates the initial communication, but you lose desirable session security. | |
398 | ||
399 | If you know that you are not running older versions of Ceph, or you are willing | |
400 | to accept that old servers and new servers will not be able to interoperate, you | |
401 | can eliminate this security risk. If you do so, any Ceph system that is new | |
402 | enough to support session authentication and that has Cephx enabled will reject | |
403 | unsigned messages. To preclude new servers from interacting with old servers, | |
404 | include the following in the ``[global]`` section of your `Ceph | |
405 | configuration`_ file directly below the line that specifies the use of Cephx | |
406 | for authentication:: | |
407 | ||
408 | cephx require signatures = true ; everywhere possible | |
409 | ||
410 | You can also selectively require signatures for cluster internal | |
411 | communications only, separate from client-facing service:: | |
412 | ||
413 | cephx cluster require signatures = true ; for cluster-internal communication | |
414 | cephx service require signatures = true ; for client-facing service | |
415 | ||
416 | An option to make a client require signatures from the cluster is not | |
417 | yet implemented. | |
418 | ||
419 | **We recommend migrating all daemons to the newer versions and enabling the | |
420 | foregoing flag** at the nearest practical time so that you may avail yourself | |
421 | of the enhanced authentication. | |
422 | ||
423 | .. note:: Ceph kernel modules do not support signatures yet. | |
424 | ||
425 | ||
426 | .. _Storage Cluster Quick Start: ../../../start/quick-ceph-deploy/ | |
427 | .. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping | |
428 | .. _Operating a Cluster: ../../operations/operating | |
429 | .. _Manual Deployment: ../../../install/manual-deployment | |
430 | .. _Cephx: http://docs.ceph.com/docs/cuttlefish/rados/configuration/auth-config-ref/ | |
431 | .. _Ceph configuration: ../ceph-conf | |
432 | .. _Create an Admin Host: ../../deployment/ceph-deploy-admin | |
433 | .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication | |
434 | .. _User Management: ../../operations/user-management |