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 [ -u | --set-uid auid ]
18 [ -a | --add-key base64_key ]
19 [ --cap subsystem capability ]
20 [ --caps capfile ]
21 [ --mode mode ]
22
25 ceph-authtool is a utility to create, view, and modify a Ceph keyring
26 file. A keyring file stores one or more Ceph authentication keys and
27 possibly an associated capability specification. Each key is associated
28 with an entity name, of the form {client,mon,mds,osd}.name.
29 WARNING Ceph provides authentication and protection against
31 man-in-the-middle attacks once secret keys are in place. However, data
32 over the wire is not encrypted, which may include the messages used to
33 configure said keys. The system is primarily intended to be used in
34 trusted environments.
35
37 -l, --list
38 will list all keys and capabilities present in the keyring
39 -p, --print-key
41 will print an encoded key for the specified entityname. This is
42 suitable for the mount -o secret= argument
43 -C, --create-keyring
45 will create a new keyring, overwriting any existing keyringfile
46 -g, --gen-key
48 will generate a new secret key for the specified entityname
49 --gen-print-key
51 will generate a new secret key for the specified entityname,
52 without altering the keyringfile, printing the secret to stdout
53 --import-keyring *secondkeyringfile*
55 will import the content of a given keyring to the keyringfile
56 -n, --name *name*
58 specify entityname to operate on
59 -u, --set-uid *auid*
61 sets the auid (authenticated user id) for the specified entity‐
62 name
63 -a, --add-key *base64_key*
65 will add an encoded key to the keyring
66 --cap *subsystem* *capability*
68 will set the capability for given subsystem
69 --caps *capsfile*
71 will set all of capabilities associated with a given key, for
72 all subsystems
73 --mode *mode*
75 will set the desired file mode to the keyring e.g: 0644,
76 defaults to 0600
77
79 The subsystem is the name of a Ceph subsystem: mon, mds, or osd.
80 The capability is a string describing what the given user is allowed to
82 do. This takes the form of a comma separated list of allow clauses with
83 a permission specifier containing one or more of rwx for read, write,
84 and execute permission. The allow * grants full superuser permissions
85 for the given subsystem.
86 For example:
88 # can read, write, and execute objects
90 osd = "allow rwx"
91 # can access mds server
93 mds = "allow"
94 # can modify cluster state (i.e., is a server daemon)
96 mon = "allow rwx"
97 A librados user restricted to a single pool might look like:
99 mon = "allow r"
101 osd = "allow rw pool foo"
103 A client using rbd with read access to one pool and read/write access
105 to another:
106 mon = "allow r"
108 osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx"
110 A client mounting the file system with minimal permissions would need
112 caps like:
113 mds = "allow"
115 osd = "allow rw pool data"
117 mon = "allow r"
119
121 In general, an osd capability follows the grammar:
122 osdcap := grant[,grant...]
124 grant := allow (match capspec | capspec match)
125 match := [pool[=]<poolname> | object_prefix <prefix>]
126 capspec := * | [r][w][x] [class-read] [class-write]
127 The capspec determines what kind of operations the entity can perform:
129 r = read access to objects
131 w = write access to objects
132 x = can call any class method (same as class-read class-write)
133 class-read = can call class methods that are reads
134 class-write = can call class methods that are writes
135 * = equivalent to rwx, plus the ability to run osd admin commands,
136 i.e. ceph osd tell ...
137 The match criteria restrict a grant based on the pool being accessed.
139 Grants are additive if the client fulfills the match condition. For
140 example, if a client has the osd capabilities: "allow r object_prefix
141 prefix, allow w pool foo, allow x pool bar", then it has rw access to
142 pool foo, rx access to pool bar, and r access to objects whose names
143 begin with 'prefix' in any pool.
144
146 The caps file format consists of zero or more key/value pairs, one per
147 line. The key and value are separated by an =, and the value must be
148 quoted (with ' or ") if it contains any whitespace. The key is the name
149 of the Ceph subsystem (osd, mds, mon), and the value is the capability
150 string (see above).
151
153 To create a new keyring containing a key for client.foo with a 0644
154 file mode:
155 ceph-authtool -C -n client.foo --gen-key keyring --mode 0644
157 To associate some capabilities with the key (namely, the ability to
159 mount a Ceph filesystem):
160 ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring
162 To display the contents of the keyring:
164 ceph-authtool -l keyring
166 When mounting a Ceph file system, you can grab the appropriately
168 encoded secret key with:
169 mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring`
171
173 ceph-authtool is part of Ceph, a massively scalable, open-source, dis‐
174 tributed storage system. Please refer to the Ceph documentation at
175 http://ceph.com/docs for more information.
176
178 ceph(8)
179
181 2010-2014, Inktank Storage, Inc. and contributors. Licensed under Cre‐
182 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
183dev Apr 14, 2019 CEPH-AUTHTOOL(8)