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