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