]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ================= |
2 | User Management | |
3 | ================= | |
4 | ||
5 | This document describes :term:`Ceph Client` users, and their authentication and | |
6 | authorization with the :term:`Ceph Storage Cluster`. Users are either | |
7 | individuals or system actors such as applications, which use Ceph clients to | |
8 | interact with the Ceph Storage Cluster daemons. | |
9 | ||
10 | .. ditaa:: +-----+ | |
11 | | {o} | | |
12 | | | | |
13 | +--+--+ /---------\ /---------\ | |
14 | | | Ceph | | Ceph | | |
15 | ---+---*----->| |<------------->| | | |
16 | | uses | Clients | | Servers | | |
17 | | \---------/ \---------/ | |
18 | /--+--\ | |
19 | | | | |
20 | | | | |
21 | actor | |
22 | ||
23 | ||
24 | When Ceph runs with authentication and authorization enabled (enabled by | |
25 | default), you must specify a user name and a keyring containing the secret key | |
26 | of the specified user (usually via the command line). If you do not specify a | |
27 | user name, Ceph will use ``client.admin`` as the default user name. If you do | |
28 | not specify a keyring, Ceph will look for a keyring via the ``keyring`` setting | |
29 | in the Ceph configuration. For example, if you execute the ``ceph health`` | |
30 | command without specifying a user or keyring:: | |
31 | ||
32 | ceph health | |
33 | ||
34 | Ceph interprets the command like this:: | |
35 | ||
36 | ceph -n client.admin --keyring=/etc/ceph/ceph.client.admin.keyring health | |
37 | ||
38 | Alternatively, you may use the ``CEPH_ARGS`` environment variable to avoid | |
39 | re-entry of the user name and secret. | |
40 | ||
41 | For details on configuring the Ceph Storage Cluster to use authentication, | |
42 | see `Cephx Config Reference`_. For details on the architecture of Cephx, see | |
43 | `Architecture - High Availability Authentication`_. | |
44 | ||
45 | ||
46 | Background | |
47 | ========== | |
48 | ||
49 | Irrespective of the type of Ceph client (e.g., Block Device, Object Storage, | |
50 | Filesystem, native API, etc.), Ceph stores all data as objects within `pools`_. | |
51 | Ceph users must have access to pools in order to read and write data. | |
52 | Additionally, Ceph users must have execute permissions to use Ceph's | |
53 | administrative commands. The following concepts will help you understand Ceph | |
54 | user management. | |
55 | ||
56 | ||
57 | User | |
58 | ---- | |
59 | ||
60 | A user is either an individual or a system actor such as an application. | |
61 | Creating users allows you to control who (or what) can access your Ceph Storage | |
62 | Cluster, its pools, and the data within pools. | |
63 | ||
64 | Ceph has the notion of a ``type`` of user. For the purposes of user management, | |
65 | the type will always be ``client``. Ceph identifies users in period (.) | |
66 | delimited form consisting of the user type and the user ID: for example, | |
67 | ``TYPE.ID``, ``client.admin``, or ``client.user1``. The reason for user typing | |
68 | is that Ceph Monitors, OSDs, and Metadata Servers also use the Cephx protocol, | |
69 | but they are not clients. Distinguishing the user type helps to distinguish | |
70 | between client users and other users--streamlining access control, user | |
71 | monitoring and traceability. | |
72 | ||
73 | Sometimes Ceph's user type may seem confusing, because the Ceph command line | |
74 | allows you to specify a user with or without the type, depending upon your | |
75 | command line usage. If you specify ``--user`` or ``--id``, you can omit the | |
76 | type. So ``client.user1`` can be entered simply as ``user1``. If you specify | |
77 | ``--name`` or ``-n``, you must specify the type and name, such as | |
78 | ``client.user1``. We recommend using the type and name as a best practice | |
79 | wherever possible. | |
80 | ||
81 | .. note:: A Ceph Storage Cluster user is not the same as a Ceph Object Storage | |
82 | user or a Ceph Filesystem user. The Ceph Object Gateway uses a Ceph Storage | |
83 | Cluster user to communicate between the gateway daemon and the storage | |
84 | cluster, but the gateway has its own user management functionality for end | |
85 | users. The Ceph Filesystem uses POSIX semantics. The user space associated | |
86 | with the Ceph Filesystem is not the same as a Ceph Storage Cluster user. | |
87 | ||
88 | ||
89 | ||
90 | Authorization (Capabilities) | |
91 | ---------------------------- | |
92 | ||
93 | Ceph uses the term "capabilities" (caps) to describe authorizing an | |
94 | authenticated user to exercise the functionality of the monitors, OSDs and | |
95 | metadata servers. Capabilities can also restrict access to data within a pool or | |
96 | a namespace within a pool. A Ceph administrative user sets a user's | |
97 | capabilities when creating or updating a user. | |
98 | ||
99 | Capability syntax follows the form:: | |
100 | ||
101 | {daemon-type} 'allow {capability}' [{daemon-type} 'allow {capability}'] | |
102 | ||
103 | ||
104 | - **Monitor Caps:** Monitor capabilities include ``r``, ``w``, ``x`` and | |
105 | ``allow profile {cap}``. For example:: | |
106 | ||
107 | mon 'allow rwx' | |
108 | mon 'allow profile osd' | |
109 | ||
110 | - **OSD Caps:** OSD capabilities include ``r``, ``w``, ``x``, ``class-read``, | |
111 | ``class-write`` and ``profile osd``. Additionally, OSD capabilities also | |
112 | allow for pool and namespace settings. :: | |
113 | ||
114 | osd 'allow {capability}' [pool={poolname}] [namespace={namespace-name}] | |
115 | ||
116 | - **Metadata Server Caps:** Metadata server capability simply requires ``allow``, | |
117 | or blank and does not parse anything further. :: | |
118 | ||
119 | mds 'allow' | |
120 | ||
121 | ||
122 | .. note:: The Ceph Object Gateway daemon (``radosgw``) is a client of the | |
123 | Ceph Storage Cluster, so it isn't represented as a Ceph Storage | |
124 | Cluster daemon type. | |
125 | ||
126 | The following entries describe each capability. | |
127 | ||
128 | ``allow`` | |
129 | ||
130 | :Description: Precedes access settings for a daemon. Implies ``rw`` | |
131 | for MDS only. | |
132 | ||
133 | ||
134 | ``r`` | |
135 | ||
136 | :Description: Gives the user read access. Required with monitors to retrieve | |
137 | the CRUSH map. | |
138 | ||
139 | ||
140 | ``w`` | |
141 | ||
142 | :Description: Gives the user write access to objects. | |
143 | ||
144 | ||
145 | ``x`` | |
146 | ||
147 | :Description: Gives the user the capability to call class methods | |
148 | (i.e., both read and write) and to conduct ``auth`` | |
149 | operations on monitors. | |
150 | ||
151 | ||
152 | ``class-read`` | |
153 | ||
154 | :Descriptions: Gives the user the capability to call class read methods. | |
155 | Subset of ``x``. | |
156 | ||
157 | ||
158 | ``class-write`` | |
159 | ||
160 | :Description: Gives the user the capability to call class write methods. | |
161 | Subset of ``x``. | |
162 | ||
163 | ||
164 | ``*`` | |
165 | ||
166 | :Description: Gives the user read, write and execute permissions for a | |
167 | particular daemon/pool, and the ability to execute | |
168 | admin commands. | |
169 | ||
170 | ||
171 | ``profile osd`` | |
172 | ||
173 | :Description: Gives a user permissions to connect as an OSD to other OSDs or | |
174 | monitors. Conferred on OSDs to enable OSDs to handle replication | |
175 | heartbeat traffic and status reporting. | |
176 | ||
177 | ||
178 | ``profile mds`` | |
179 | ||
180 | :Description: Gives a user permissions to connect as a MDS to other MDSs or | |
181 | monitors. | |
182 | ||
183 | ||
184 | ``profile bootstrap-osd`` | |
185 | ||
186 | :Description: Gives a user permissions to bootstrap an OSD. Conferred on | |
187 | deployment tools such as ``ceph-disk``, ``ceph-deploy``, etc. | |
188 | so that they have permissions to add keys, etc. when | |
189 | bootstrapping an OSD. | |
190 | ||
191 | ||
192 | ``profile bootstrap-mds`` | |
193 | ||
194 | :Description: Gives a user permissions to bootstrap a metadata server. | |
195 | Conferred on deployment tools such as ``ceph-deploy``, etc. | |
196 | so they have permissions to add keys, etc. when bootstrapping | |
197 | a metadata server. | |
198 | ||
199 | ||
200 | ||
201 | Pool | |
202 | ---- | |
203 | ||
204 | A pool is a logical partition where users store data. | |
205 | In Ceph deployments, it is common to create a pool as a logical partition for | |
206 | similar types of data. For example, when deploying Ceph as a backend for | |
207 | OpenStack, a typical deployment would have pools for volumes, images, backups | |
208 | and virtual machines, and users such as ``client.glance``, ``client.cinder``, | |
209 | etc. | |
210 | ||
211 | ||
212 | Namespace | |
213 | --------- | |
214 | ||
215 | Objects within a pool can be associated to a namespace--a logical group of | |
216 | objects within the pool. A user's access to a pool can be associated with a | |
217 | namespace such that reads and writes by the user take place only within the | |
218 | namespace. Objects written to a namespace within the pool can only be accessed | |
219 | by users who have access to the namespace. | |
220 | ||
221 | .. note:: Currently (i.e., ``firefly``), namespaces are only useful for | |
222 | applications written on top of ``librados``. Ceph clients such as block | |
223 | device, object storage and file system do not currently support this | |
224 | feature. | |
225 | ||
226 | The rationale for namespaces is that pools can be a computationally expensive | |
227 | method of segregating data sets for the purposes of authorizing separate sets | |
228 | of users. For example, a pool should have ~100 placement groups per OSD. So an | |
229 | exemplary cluster with 1000 OSDs would have 100,000 placement groups for one | |
230 | pool. Each pool would create another 100,000 placement groups in the exemplary | |
231 | cluster. By contrast, writing an object to a namespace simply associates the | |
232 | namespace to the object name with out the computational overhead of a separate | |
233 | pool. Rather than creating a separate pool for a user or set of users, you may | |
234 | use a namespace. **Note:** Only available using ``librados`` at this time. | |
235 | ||
236 | ||
237 | Managing Users | |
238 | ============== | |
239 | ||
240 | User management functionality provides Ceph Storage Cluster administrators with | |
241 | the ability to create, update and delete users directly in the Ceph Storage | |
242 | Cluster. | |
243 | ||
244 | When you create or delete users in the Ceph Storage Cluster, you may need to | |
245 | distribute keys to clients so that they can be added to keyrings. See `Keyring | |
246 | Management`_ for details. | |
247 | ||
248 | ||
249 | List Users | |
250 | ---------- | |
251 | ||
252 | To list the users in your cluster, execute the following:: | |
253 | ||
254 | ceph auth list | |
255 | ||
256 | Ceph will list out all users in your cluster. For example, in a two-node | |
257 | exemplary cluster, ``ceph auth list`` will output something that looks like | |
258 | this:: | |
259 | ||
260 | installed auth entries: | |
261 | ||
262 | osd.0 | |
263 | key: AQCvCbtToC6MDhAATtuT70Sl+DymPCfDSsyV4w== | |
264 | caps: [mon] allow profile osd | |
265 | caps: [osd] allow * | |
266 | osd.1 | |
267 | key: AQC4CbtTCFJBChAAVq5spj0ff4eHZICxIOVZeA== | |
268 | caps: [mon] allow profile osd | |
269 | caps: [osd] allow * | |
270 | client.admin | |
271 | key: AQBHCbtT6APDHhAA5W00cBchwkQjh3dkKsyPjw== | |
272 | caps: [mds] allow | |
273 | caps: [mon] allow * | |
274 | caps: [osd] allow * | |
275 | client.bootstrap-mds | |
276 | key: AQBICbtTOK9uGBAAdbe5zcIGHZL3T/u2g6EBww== | |
277 | caps: [mon] allow profile bootstrap-mds | |
278 | client.bootstrap-osd | |
279 | key: AQBHCbtT4GxqORAADE5u7RkpCN/oo4e5W0uBtw== | |
280 | caps: [mon] allow profile bootstrap-osd | |
281 | ||
282 | ||
283 | Note that the ``TYPE.ID`` notation for users applies such that ``osd.0`` is a | |
284 | user of type ``osd`` and its ID is ``0``, ``client.admin`` is a user of type | |
285 | ``client`` and its ID is ``admin`` (i.e., the default ``client.admin`` user). | |
286 | Note also that each entry has a ``key: <value>`` entry, and one or more | |
287 | ``caps:`` entries. | |
288 | ||
289 | You may use the ``-o {filename}`` option with ``ceph auth list`` to | |
290 | save the output to a file. | |
291 | ||
292 | ||
293 | Get a User | |
294 | ---------- | |
295 | ||
296 | To retrieve a specific user, key and capabilities, execute the | |
297 | following:: | |
298 | ||
299 | ceph auth get {TYPE.ID} | |
300 | ||
301 | For example:: | |
302 | ||
303 | ceph auth get client.admin | |
304 | ||
305 | You may also use the ``-o {filename}`` option with ``ceph auth get`` to | |
306 | save the output to a file. Developers may also execute the following:: | |
307 | ||
308 | ceph auth export {TYPE.ID} | |
309 | ||
310 | The ``auth export`` command is identical to ``auth get``, but also prints | |
311 | out the internal ``auid``, which isn't relevant to end users. | |
312 | ||
313 | ||
314 | ||
315 | Add a User | |
316 | ---------- | |
317 | ||
318 | Adding a user creates a username (i.e., ``TYPE.ID``), a secret key and | |
319 | any capabilities included in the command you use to create the user. | |
320 | ||
321 | A user's key enables the user to authenticate with the Ceph Storage Cluster. | |
322 | The user's capabilities authorize the user to read, write, or execute on Ceph | |
323 | monitors (``mon``), Ceph OSDs (``osd``) or Ceph Metadata Servers (``mds``). | |
324 | ||
325 | There are a few ways to add a user: | |
326 | ||
327 | - ``ceph auth add``: This command is the canonical way to add a user. It | |
328 | will create the user, generate a key and add any specified capabilities. | |
329 | ||
330 | - ``ceph auth get-or-create``: This command is often the most convenient way | |
331 | to create a user, because it returns a keyfile format with the user name | |
332 | (in brackets) and the key. If the user already exists, this command | |
333 | simply returns the user name and key in the keyfile format. You may use the | |
334 | ``-o {filename}`` option to save the output to a file. | |
335 | ||
336 | - ``ceph auth get-or-create-key``: This command is a convenient way to create | |
337 | a user and return the user's key (only). This is useful for clients that | |
338 | need the key only (e.g., libvirt). If the user already exists, this command | |
339 | simply returns the key. You may use the ``-o {filename}`` option to save the | |
340 | output to a file. | |
341 | ||
342 | When creating client users, you may create a user with no capabilities. A user | |
343 | with no capabilities is useless beyond mere authentication, because the client | |
344 | cannot retrieve the cluster map from the monitor. However, you can create a | |
345 | user with no capabilities if you wish to defer adding capabilities later using | |
346 | the ``ceph auth caps`` command. | |
347 | ||
348 | A typical user has at least read capabilities on the Ceph monitor and | |
349 | read and write capability on Ceph OSDs. Additionally, a user's OSD permissions | |
350 | are often restricted to accessing a particular pool. :: | |
351 | ||
352 | ceph auth add client.john mon 'allow r' osd 'allow rw pool=liverpool' | |
353 | ceph auth get-or-create client.paul mon 'allow r' osd 'allow rw pool=liverpool' | |
354 | ceph auth get-or-create client.george mon 'allow r' osd 'allow rw pool=liverpool' -o george.keyring | |
355 | ceph auth get-or-create-key client.ringo mon 'allow r' osd 'allow rw pool=liverpool' -o ringo.key | |
356 | ||
357 | ||
358 | .. important:: If you provide a user with capabilities to OSDs, but you DO NOT | |
359 | restrict access to particular pools, the user will have access to ALL | |
360 | pools in the cluster! | |
361 | ||
362 | ||
31f18b77 | 363 | .. _modify-user-capabilities: |
224ce89b | 364 | |
7c673cae FG |
365 | Modify User Capabilities |
366 | ------------------------ | |
367 | ||
368 | The ``ceph auth caps`` command allows you to specify a user and change the | |
369 | user's capabilities. Setting new capabilities will overwrite current capabilities. | |
370 | To view current capabilities run ``ceph auth get USERTYPE.USERID``. To add | |
371 | capabilities, you should also specify the existing capabilities when using the form:: | |
372 | ||
373 | ceph auth caps USERTYPE.USERID {daemon} 'allow [r|w|x|*|...] [pool={pool-name}] [namespace={namespace-name}]' [{daemon} 'allow [r|w|x|*|...] [pool={pool-name}] [namespace={namespace-name}]'] | |
374 | ||
375 | For example:: | |
376 | ||
377 | ceph auth get client.john | |
378 | ceph auth caps client.john mon 'allow r' osd 'allow rw pool=liverpool' | |
379 | ceph auth caps client.paul mon 'allow rw' osd 'allow rwx pool=liverpool' | |
380 | ceph auth caps client.brian-manager mon 'allow *' osd 'allow *' | |
381 | ||
382 | To remove a capability, you may reset the capability. If you want the user | |
383 | to have no access to a particular daemon that was previously set, specify | |
384 | an empty string. For example:: | |
385 | ||
386 | ceph auth caps client.ringo mon ' ' osd ' ' | |
387 | ||
388 | See `Authorization (Capabilities)`_ for additional details on capabilities. | |
389 | ||
390 | ||
391 | Delete a User | |
392 | ------------- | |
393 | ||
394 | To delete a user, use ``ceph auth del``:: | |
395 | ||
396 | ceph auth del {TYPE}.{ID} | |
397 | ||
398 | Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``, | |
399 | and ``{ID}`` is the user name or ID of the daemon. | |
400 | ||
401 | ||
402 | Print a User's Key | |
403 | ------------------ | |
404 | ||
405 | To print a user's authentication key to standard output, execute the following:: | |
406 | ||
407 | ceph auth print-key {TYPE}.{ID} | |
408 | ||
409 | Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``, | |
410 | and ``{ID}`` is the user name or ID of the daemon. | |
411 | ||
412 | Printing a user's key is useful when you need to populate client | |
413 | software with a user's key (e.g., libvirt). :: | |
414 | ||
415 | mount -t ceph serverhost:/ mountpoint -o name=client.user,secret=`ceph auth print-key client.user` | |
416 | ||
417 | ||
418 | Import a User(s) | |
419 | ---------------- | |
420 | ||
421 | To import one or more users, use ``ceph auth import`` and | |
422 | specify a keyring:: | |
423 | ||
424 | ceph auth import -i /path/to/keyring | |
425 | ||
426 | For example:: | |
427 | ||
428 | sudo ceph auth import -i /etc/ceph/ceph.keyring | |
429 | ||
430 | ||
431 | .. note:: The ceph storage cluster will add new users, their keys and their | |
432 | capabilities and will update existing users, their keys and their | |
433 | capabilities. | |
434 | ||
435 | ||
436 | Keyring Management | |
437 | ================== | |
438 | ||
439 | When you access Ceph via a Ceph client, the Ceph client will look for a local | |
440 | keyring. Ceph presets the ``keyring`` setting with the following four keyring | |
441 | names by default so you don't have to set them in your Ceph configuration file | |
442 | unless you want to override the defaults (not recommended): | |
443 | ||
444 | - ``/etc/ceph/$cluster.$name.keyring`` | |
445 | - ``/etc/ceph/$cluster.keyring`` | |
446 | - ``/etc/ceph/keyring`` | |
447 | - ``/etc/ceph/keyring.bin`` | |
448 | ||
449 | The ``$cluster`` metavariable is your Ceph cluster name as defined by the | |
450 | name of the Ceph configuration file (i.e., ``ceph.conf`` means the cluster name | |
451 | is ``ceph``; thus, ``ceph.keyring``). The ``$name`` metavariable is the user | |
452 | type and user ID (e.g., ``client.admin``; thus, ``ceph.client.admin.keyring``). | |
453 | ||
454 | .. note:: When executing commands that read or write to ``/etc/ceph``, you may | |
455 | need to use ``sudo`` to execute the command as ``root``. | |
456 | ||
457 | After you create a user (e.g., ``client.ringo``), you must get the key and add | |
458 | it to a keyring on a Ceph client so that the user can access the Ceph Storage | |
459 | Cluster. | |
460 | ||
461 | The `User Management`_ section details how to list, get, add, modify and delete | |
462 | users directly in the Ceph Storage Cluster. However, Ceph also provides the | |
463 | ``ceph-authtool`` utility to allow you to manage keyrings from a Ceph client. | |
464 | ||
465 | ||
466 | Create a Keyring | |
467 | ---------------- | |
468 | ||
469 | When you use the procedures in the `Managing Users`_ section to create users, | |
470 | you need to provide user keys to the Ceph client(s) so that the Ceph client | |
471 | can retrieve the key for the specified user and authenticate with the Ceph | |
472 | Storage Cluster. Ceph Clients access keyrings to lookup a user name and | |
473 | retrieve the user's key. | |
474 | ||
475 | The ``ceph-authtool`` utility allows you to create a keyring. To create an | |
476 | empty keyring, use ``--create-keyring`` or ``-C``. For example:: | |
477 | ||
478 | ceph-authtool --create-keyring /path/to/keyring | |
479 | ||
480 | When creating a keyring with multiple users, we recommend using the cluster name | |
481 | (e.g., ``$cluster.keyring``) for the keyring filename and saving it in the | |
482 | ``/etc/ceph`` directory so that the ``keyring`` configuration default setting | |
483 | will pick up the filename without requiring you to specify it in the local copy | |
484 | of your Ceph configuration file. For example, create ``ceph.keyring`` by | |
485 | executing the following:: | |
486 | ||
487 | sudo ceph-authtool -C /etc/ceph/ceph.keyring | |
488 | ||
489 | When creating a keyring with a single user, we recommend using the cluster name, | |
490 | the user type and the user name and saving it in the ``/etc/ceph`` directory. | |
491 | For example, ``ceph.client.admin.keyring`` for the ``client.admin`` user. | |
492 | ||
493 | To create a keyring in ``/etc/ceph``, you must do so as ``root``. This means | |
494 | the file will have ``rw`` permissions for the ``root`` user only, which is | |
495 | appropriate when the keyring contains administrator keys. However, if you | |
496 | intend to use the keyring for a particular user or group of users, ensure | |
497 | that you execute ``chown`` or ``chmod`` to establish appropriate keyring | |
498 | ownership and access. | |
499 | ||
500 | ||
501 | Add a User to a Keyring | |
502 | ----------------------- | |
503 | ||
504 | When you `Add a User`_ to the Ceph Storage Cluster, you can use the `Get a | |
505 | User`_ procedure to retrieve a user, key and capabilities and save the user to a | |
506 | keyring. | |
507 | ||
508 | When you only want to use one user per keyring, the `Get a User`_ procedure with | |
509 | the ``-o`` option will save the output in the keyring file format. For example, | |
510 | to create a keyring for the ``client.admin`` user, execute the following:: | |
511 | ||
512 | sudo ceph auth get client.admin -o /etc/ceph/ceph.client.admin.keyring | |
513 | ||
514 | Notice that we use the recommended file format for an individual user. | |
515 | ||
516 | When you want to import users to a keyring, you can use ``ceph-authtool`` | |
517 | to specify the destination keyring and the source keyring. | |
518 | For example:: | |
519 | ||
520 | sudo ceph-authtool /etc/ceph/ceph.keyring --import-keyring /etc/ceph/ceph.client.admin.keyring | |
521 | ||
522 | ||
523 | Create a User | |
524 | ------------- | |
525 | ||
526 | Ceph provides the `Add a User`_ function to create a user directly in the Ceph | |
527 | Storage Cluster. However, you can also create a user, keys and capabilities | |
528 | directly on a Ceph client keyring. Then, you can import the user to the Ceph | |
529 | Storage Cluster. For example:: | |
530 | ||
531 | sudo ceph-authtool -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' /etc/ceph/ceph.keyring | |
532 | ||
533 | See `Authorization (Capabilities)`_ for additional details on capabilities. | |
534 | ||
535 | You can also create a keyring and add a new user to the keyring simultaneously. | |
536 | For example:: | |
537 | ||
538 | sudo ceph-authtool -C /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' --gen-key | |
539 | ||
540 | In the foregoing scenarios, the new user ``client.ringo`` is only in the | |
541 | keyring. To add the new user to the Ceph Storage Cluster, you must still add | |
542 | the new user to the Ceph Storage Cluster. :: | |
543 | ||
544 | sudo ceph auth add client.ringo -i /etc/ceph/ceph.keyring | |
545 | ||
546 | ||
547 | Modify a User | |
548 | ------------- | |
549 | ||
550 | To modify the capabilities of a user record in a keyring, specify the keyring, | |
551 | and the user followed by the capabilities. For example:: | |
552 | ||
553 | sudo ceph-authtool /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' | |
554 | ||
555 | To update the user to the Ceph Storage Cluster, you must update the user | |
556 | in the keyring to the user entry in the the Ceph Storage Cluster. :: | |
557 | ||
558 | sudo ceph auth import -i /etc/ceph/ceph.keyring | |
559 | ||
560 | See `Import a User(s)`_ for details on updating a Ceph Storage Cluster user | |
561 | from a keyring. | |
562 | ||
563 | You may also `Modify User Capabilities`_ directly in the cluster, store the | |
564 | results to a keyring file; then, import the keyring into your main | |
565 | ``ceph.keyring`` file. | |
566 | ||
567 | ||
568 | Command Line Usage | |
569 | ================== | |
570 | ||
571 | Ceph supports the following usage for user name and secret: | |
572 | ||
573 | ``--id`` | ``--user`` | |
574 | ||
575 | :Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or | |
576 | ``client.admin``, ``client.user1``). The ``id``, ``name`` and | |
577 | ``-n`` options enable you to specify the ID portion of the user | |
578 | name (e.g., ``admin``, ``user1``, ``foo``, etc.). You can specify | |
579 | the user with the ``--id`` and omit the type. For example, | |
580 | to specify user ``client.foo`` enter the following:: | |
581 | ||
582 | ceph --id foo --keyring /path/to/keyring health | |
583 | ceph --user foo --keyring /path/to/keyring health | |
584 | ||
585 | ||
586 | ``--name`` | ``-n`` | |
587 | ||
588 | :Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or | |
589 | ``client.admin``, ``client.user1``). The ``--name`` and ``-n`` | |
590 | options enables you to specify the fully qualified user name. | |
591 | You must specify the user type (typically ``client``) with the | |
592 | user ID. For example:: | |
593 | ||
594 | ceph --name client.foo --keyring /path/to/keyring health | |
595 | ceph -n client.foo --keyring /path/to/keyring health | |
596 | ||
597 | ||
598 | ``--keyring`` | |
599 | ||
600 | :Description: The path to the keyring containing one or more user name and | |
601 | secret. The ``--secret`` option provides the same functionality, | |
602 | but it does not work with Ceph RADOS Gateway, which uses | |
603 | ``--secret`` for another purpose. You may retrieve a keyring with | |
604 | ``ceph auth get-or-create`` and store it locally. This is a | |
605 | preferred approach, because you can switch user names without | |
606 | switching the keyring path. For example:: | |
607 | ||
608 | sudo rbd map --id foo --keyring /path/to/keyring mypool/myimage | |
609 | ||
610 | ||
611 | .. _pools: ../pools | |
612 | ||
613 | ||
614 | Limitations | |
615 | =========== | |
616 | ||
617 | The ``cephx`` protocol authenticates Ceph clients and servers to each other. It | |
618 | is not intended to handle authentication of human users or application programs | |
619 | run on their behalf. If that effect is required to handle your access control | |
620 | needs, you must have another mechanism, which is likely to be specific to the | |
621 | front end used to access the Ceph object store. This other mechanism has the | |
622 | role of ensuring that only acceptable users and programs are able to run on the | |
623 | machine that Ceph will permit to access its object store. | |
624 | ||
625 | The keys used to authenticate Ceph clients and servers are typically stored in | |
626 | a plain text file with appropriate permissions in a trusted host. | |
627 | ||
628 | .. important:: Storing keys in plaintext files has security shortcomings, but | |
629 | they are difficult to avoid, given the basic authentication methods Ceph | |
630 | uses in the background. Those setting up Ceph systems should be aware of | |
631 | these shortcomings. | |
632 | ||
633 | In particular, arbitrary user machines, especially portable machines, should not | |
634 | be configured to interact directly with Ceph, since that mode of use would | |
635 | require the storage of a plaintext authentication key on an insecure machine. | |
636 | Anyone who stole that machine or obtained surreptitious access to it could | |
637 | obtain the key that will allow them to authenticate their own machines to Ceph. | |
638 | ||
639 | Rather than permitting potentially insecure machines to access a Ceph object | |
640 | store directly, users should be required to sign in to a trusted machine in | |
641 | your environment using a method that provides sufficient security for your | |
642 | purposes. That trusted machine will store the plaintext Ceph keys for the | |
643 | human users. A future version of Ceph may address these particular | |
644 | authentication issues more fully. | |
645 | ||
646 | At the moment, none of the Ceph authentication protocols provide secrecy for | |
647 | messages in transit. Thus, an eavesdropper on the wire can hear and understand | |
648 | all data sent between clients and servers in Ceph, even if it cannot create or | |
649 | alter them. Further, Ceph does not include options to encrypt user data in the | |
650 | object store. Users can hand-encrypt and store their own data in the Ceph | |
651 | object store, of course, but Ceph provides no features to perform object | |
652 | encryption itself. Those storing sensitive data in Ceph should consider | |
653 | encrypting their data before providing it to the Ceph system. | |
654 | ||
655 | ||
656 | .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication | |
657 | .. _Cephx Config Reference: ../../configuration/auth-config-ref |