]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | :orphan: |
2 | ||
3 | ================================================= | |
4 | ceph-authtool -- ceph keyring manipulation tool | |
5 | ================================================= | |
6 | ||
7 | .. program:: ceph-authtool | |
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | | **ceph-authtool** *keyringfile* | |
13 | [ -l | --list ] | |
14 | [ -p | --print-key ] | |
15 | [ -C | --create-keyring ] | |
16 | [ -g | --gen-key ] | |
17 | [ --gen-print-key ] | |
18 | [ --import-keyring *otherkeyringfile* ] | |
19 | [ -n | --name *entityname* ] | |
20 | [ -u | --set-uid *auid* ] | |
21 | [ -a | --add-key *base64_key* ] | |
22 | [ --cap *subsystem* *capability* ] | |
23 | [ --caps *capfile* ] | |
94b18763 | 24 | [ --mode *mode* ] |
7c673cae FG |
25 | |
26 | ||
27 | Description | |
28 | =========== | |
29 | ||
30 | **ceph-authtool** is a utility to create, view, and modify a Ceph keyring | |
31 | file. A keyring file stores one or more Ceph authentication keys and | |
32 | possibly an associated capability specification. Each key is | |
33 | associated with an entity name, of the form | |
34 | ``{client,mon,mds,osd}.name``. | |
35 | ||
36 | **WARNING** Ceph provides authentication and protection against | |
37 | man-in-the-middle attacks once secret keys are in place. However, | |
38 | data over the wire is not encrypted, which may include the messages | |
39 | used to configure said keys. The system is primarily intended to be | |
40 | used in trusted environments. | |
41 | ||
42 | Options | |
43 | ======= | |
44 | ||
45 | .. option:: -l, --list | |
46 | ||
47 | will list all keys and capabilities present in the keyring | |
48 | ||
49 | .. option:: -p, --print-key | |
50 | ||
51 | will print an encoded key for the specified entityname. This is | |
52 | suitable for the ``mount -o secret=`` argument | |
53 | ||
54 | .. option:: -C, --create-keyring | |
55 | ||
56 | will create a new keyring, overwriting any existing keyringfile | |
57 | ||
58 | .. option:: -g, --gen-key | |
59 | ||
60 | will generate a new secret key for the specified entityname | |
61 | ||
62 | .. option:: --gen-print-key | |
63 | ||
64 | will generate a new secret key for the specified entityname, | |
65 | without altering the keyringfile, printing the secret to stdout | |
66 | ||
67 | .. option:: --import-keyring *secondkeyringfile* | |
68 | ||
69 | will import the content of a given keyring to the keyringfile | |
70 | ||
71 | .. option:: -n, --name *name* | |
72 | ||
73 | specify entityname to operate on | |
74 | ||
75 | .. option:: -u, --set-uid *auid* | |
76 | ||
77 | sets the auid (authenticated user id) for the specified entityname | |
78 | ||
79 | .. option:: -a, --add-key *base64_key* | |
80 | ||
81 | will add an encoded key to the keyring | |
82 | ||
83 | .. option:: --cap *subsystem* *capability* | |
84 | ||
85 | will set the capability for given subsystem | |
86 | ||
87 | .. option:: --caps *capsfile* | |
88 | ||
89 | will set all of capabilities associated with a given key, for all subsystems | |
90 | ||
94b18763 FG |
91 | .. option:: --mode *mode* |
92 | ||
93 | will set the desired file mode to the keyring e.g: 0644, defaults to 0600 | |
94 | ||
7c673cae FG |
95 | |
96 | Capabilities | |
97 | ============ | |
98 | ||
99 | The subsystem is the name of a Ceph subsystem: ``mon``, ``mds``, or | |
100 | ``osd``. | |
101 | ||
102 | The capability is a string describing what the given user is allowed | |
103 | to do. This takes the form of a comma separated list of allow | |
104 | clauses with a permission specifier containing one or more of rwx for | |
105 | read, write, and execute permission. The ``allow *`` grants full | |
106 | superuser permissions for the given subsystem. | |
107 | ||
108 | For example:: | |
109 | ||
110 | # can read, write, and execute objects | |
111 | osd = "allow rwx" | |
112 | ||
113 | # can access mds server | |
114 | mds = "allow" | |
115 | ||
116 | # can modify cluster state (i.e., is a server daemon) | |
117 | mon = "allow rwx" | |
118 | ||
119 | A librados user restricted to a single pool might look like:: | |
120 | ||
121 | mon = "allow r" | |
122 | ||
123 | osd = "allow rw pool foo" | |
124 | ||
125 | A client using rbd with read access to one pool and read/write access to another:: | |
126 | ||
127 | mon = "allow r" | |
128 | ||
129 | osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx" | |
130 | ||
131 | A client mounting the file system with minimal permissions would need caps like:: | |
132 | ||
133 | mds = "allow" | |
134 | ||
135 | osd = "allow rw pool data" | |
136 | ||
137 | mon = "allow r" | |
138 | ||
139 | ||
140 | OSD Capabilities | |
141 | ================ | |
142 | ||
143 | In general, an osd capability follows the grammar:: | |
144 | ||
145 | osdcap := grant[,grant...] | |
146 | grant := allow (match capspec | capspec match) | |
147 | match := [pool[=]<poolname> | object_prefix <prefix>] | |
148 | capspec := * | [r][w][x] [class-read] [class-write] | |
149 | ||
150 | The capspec determines what kind of operations the entity can perform:: | |
151 | ||
152 | r = read access to objects | |
153 | w = write access to objects | |
154 | x = can call any class method (same as class-read class-write) | |
155 | class-read = can call class methods that are reads | |
156 | class-write = can call class methods that are writes | |
157 | * = equivalent to rwx, plus the ability to run osd admin commands, | |
158 | i.e. ceph osd tell ... | |
159 | ||
160 | The match criteria restrict a grant based on the pool being accessed. | |
161 | Grants are additive if the client fulfills the match condition. For | |
162 | example, if a client has the osd capabilities: "allow r object_prefix | |
163 | prefix, allow w pool foo, allow x pool bar", then it has rw access to | |
164 | pool foo, rx access to pool bar, and r access to objects whose | |
165 | names begin with 'prefix' in any pool. | |
166 | ||
167 | Caps file format | |
168 | ================ | |
169 | ||
170 | The caps file format consists of zero or more key/value pairs, one per | |
171 | line. The key and value are separated by an ``=``, and the value must | |
172 | be quoted (with ``'`` or ``"``) if it contains any whitespace. The key | |
173 | is the name of the Ceph subsystem (``osd``, ``mds``, ``mon``), and the | |
174 | value is the capability string (see above). | |
175 | ||
176 | ||
177 | Example | |
178 | ======= | |
179 | ||
94b18763 | 180 | To create a new keyring containing a key for client.foo with a 0644 file mode:: |
7c673cae | 181 | |
94b18763 | 182 | ceph-authtool -C -n client.foo --gen-key keyring --mode 0644 |
7c673cae FG |
183 | |
184 | To associate some capabilities with the key (namely, the ability to | |
185 | mount a Ceph filesystem):: | |
186 | ||
187 | ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring | |
188 | ||
189 | To display the contents of the keyring:: | |
190 | ||
191 | ceph-authtool -l keyring | |
192 | ||
193 | When mounting a Ceph file system, you can grab the appropriately encoded secret key with:: | |
194 | ||
195 | mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring` | |
196 | ||
197 | ||
198 | Availability | |
199 | ============ | |
200 | ||
201 | **ceph-authtool** is part of Ceph, a massively scalable, open-source, distributed storage system. Please | |
202 | refer to the Ceph documentation at http://ceph.com/docs for more | |
203 | information. | |
204 | ||
205 | ||
206 | See also | |
207 | ======== | |
208 | ||
209 | :doc:`ceph <ceph>`\(8) |