1CEPH-AUTHTOOL(8) Ceph CEPH-AUTHTOOL(8)
2
6 ceph-authtool - ceph keyring manipulation tool
7
9 ceph-authtool keyringfile
10 [ -l | --list ]
11 [ -p | --print-key ]
12 [ -C | --create-keyring ]
13 [ -g | --gen-key ]
14 [ --gen-print-key ]
15 [ --import-keyring otherkeyringfile ]
16 [ -n | --name entityname ]
17 [ -a | --add-key base64_key ]
18 [ --cap subsystem capability ]
19 [ --caps capfile ]
20 [ --mode mode ]
21
24 ceph-authtool is a utility to create, view, and modify a Ceph keyring
25 file. A keyring file stores one or more Ceph authentication keys and
26 possibly an associated capability specification. Each key is associated
27 with an entity name, of the form {client,mon,mds,osd}.name.
28 WARNING Ceph provides authentication and protection against
30 man-in-the-middle attacks once secret keys are in place. However, data
31 over the wire is not encrypted, which may include the messages used to
32 configure said keys. The system is primarily intended to be used in
33 trusted environments.
34
36 -l, --list
37 will list all keys and capabilities present in the keyring
38 -p, --print-key
40 will print an encoded key for the specified entityname. This is
41 suitable for the mount -o secret= argument
42 -C, --create-keyring
44 will create a new keyring, overwriting any existing keyringfile
45 -g, --gen-key
47 will generate a new secret key for the specified entityname
48 --gen-print-key
50 will generate a new secret key for the specified entityname,
51 without altering the keyringfile, printing the secret to stdout
52 --import-keyring *secondkeyringfile*
54 will import the content of a given keyring to the keyringfile
55 -n, --name *name*
57 specify entityname to operate on
58 -a, --add-key *base64_key*
60 will add an encoded key to the keyring
61 --cap *subsystem* *capability*
63 will set the capability for given subsystem
64 --caps *capsfile*
66 will set all of capabilities associated with a given key, for
67 all subsystems
68 --mode *mode*
70 will set the desired file mode to the keyring e.g: 0644, de‐
71 faults to 0600
72
74 The subsystem is the name of a Ceph subsystem: mon, mds, or osd.
75 The capability is a string describing what the given user is allowed to
77 do. This takes the form of a comma separated list of allow clauses with
78 a permission specifier containing one or more of rwx for read, write,
79 and execute permission. The allow * grants full superuser permissions
80 for the given subsystem.
81 For example:
83 # can read, write, and execute objects
85 osd = "allow rwx"
86 # can access mds server
88 mds = "allow"
89 # can modify cluster state (i.e., is a server daemon)
91 mon = "allow rwx"
92 A librados user restricted to a single pool might look like:
94 mon = "allow r"
96 osd = "allow rw pool foo"
98 A client using rbd with read access to one pool and read/write access
100 to another:
101 mon = "allow r"
103 osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx"
105 A client mounting the file system with minimal permissions would need
107 caps like:
108 mds = "allow"
110 osd = "allow rw pool data"
112 mon = "allow r"
114
116 In general, an osd capability follows the grammar:
117 osdcap := grant[,grant...]
119 grant := allow (match capspec | capspec match)
120 match := [ pool[=]<poolname> | object_prefix <prefix>
121 | namespace[=]<rados-namespace>
122 | tag <application-name> <key>=<value> ]
123 capspec := * | [r][w][x] [class-read] [class-write]
124 The capspec determines what kind of operations the entity can perform:
126 r = read access to objects
128 w = write access to objects
129 x = can call any class method (same as class-read class-write)
130 class-read = can call class methods that are reads
131 class-write = can call class methods that are writes
132 * or "all" = equivalent to rwx, plus the ability to run osd admin commands,
133 i.e. ceph osd tell ...
134 The match criteria restrict a grant based on the pool being accessed.
136 Grants are additive if the client fulfills the match condition. For ex‐
137 ample, if a client has the osd capabilities: "allow r object_prefix
138 prefix, allow w pool foo, allow x pool bar", then it has rw access to
139 pool foo, rx access to pool bar, and r access to objects whose names
140 begin with 'prefix' in any pool.
141
143 The caps file format consists of zero or more key/value pairs, one per
144 line. The key and value are separated by an =, and the value must be
145 quoted (with ' or ") if it contains any whitespace. The key is the name
146 of the Ceph subsystem (osd, mds, mon), and the value is the capability
147 string (see above).
148
150 To create a new keyring containing a key for client.foo with a 0644
151 file mode:
152 ceph-authtool -C -n client.foo --gen-key keyring --mode 0644
154 To associate some capabilities with the key (namely, the ability to
156 mount a Ceph file system):
157 ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring
159 To display the contents of the keyring:
161 ceph-authtool -l keyring
163 When mounting a Ceph file system, you can grab the appropriately en‐
165 coded secret key with:
166 mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring`
168
170 ceph-authtool is part of Ceph, a massively scalable, open-source, dis‐
171 tributed storage system. Please refer to the Ceph documentation at
172 https://docs.ceph.com for more information.
173
175 ceph(8)
176
178 2010-2023, Inktank Storage, Inc. and contributors. Licensed under Cre‐
179 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
180dev Nov 15, 2023 CEPH-AUTHTOOL(8)