-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathceph-authtool.8
249 lines (242 loc) · 6.47 KB
/
ceph-authtool.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
.TH "CEPH-AUTHTOOL" "8" "April 29, 2013" "dev" "Ceph"
.SH NAME
ceph-authtool \- ceph keyring manipulation tool
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructuredText.
.
.SH SYNOPSIS
.nf
\fBceph\-authtool\fP \fIkeyringfile\fP [ \-l | \-\-list ] [ \-C | \-\-create\-keyring
] [ \-p | \-\-print ] [ \-n | \-\-name \fIentityname\fP ] [ \-\-gen\-key ] [ \-a |
\-\-add\-key \fIbase64_key\fP ] [ \-\-caps \fIcapfils\fP ]
.fi
.sp
.SH DESCRIPTION
.sp
\fBceph\-authtool\fP is a utility to create, view, and modify a Ceph keyring
file. A keyring file stores one or more Ceph authentication keys and
possibly an associated capability specification. Each key is
associated with an entity name, of the form
\fB{client,mon,mds,osd}.name\fP.
.sp
\fBWARNING\fP Ceph provides authentication and protection against
man\-in\-the\-middle attacks once secret keys are in place. However,
data over the wire is not encrypted, which may include the messages
used to configure said keys. The system is primarily intended to be
used in trusted environments.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-l, \-\-list
will list all keys and capabilities present in the keyring
.UNINDENT
.INDENT 0.0
.TP
.B \-p, \-\-print
will print an encoded key for the specified entityname. This is
suitable for the \fBmount \-o secret=\fP argument
.UNINDENT
.INDENT 0.0
.TP
.B \-C, \-\-create\-keyring
will create a new keyring, overwriting any existing keyringfile
.UNINDENT
.INDENT 0.0
.TP
.B \-g, \-\-gen\-key
will generate a new secret key for the specified entityname
.UNINDENT
.INDENT 0.0
.TP
.B \-a, \-\-add\-key
will add an encoded key to the keyring
.UNINDENT
.INDENT 0.0
.TP
.B \-u, \-\-set\-uid
sets the auid (authenticated user id) for the specified entityname
.UNINDENT
.INDENT 0.0
.TP
.B \-\-gen\-print\-key
will generate and print a new secret key without adding it to the keyringfile
NOTE: will work without a given keyringfile
.UNINDENT
.INDENT 0.0
.TP
.B \-\-import\-keyring
will import the content of a given keyring into the keyringfile
.UNINDENT
.INDENT 0.0
.TP
.B \-\-cap subsystem capability
will set the capability for given subsystem
.UNINDENT
.INDENT 0.0
.TP
.B \-\-caps capsfile
will set all of capabilities associated with a given key, for all subsystems
.UNINDENT
.SH CAPABILITIES
.sp
The subsystem is the name of a Ceph subsystem: \fBmon\fP, \fBmds\fP, or
\fBosd\fP.
.sp
The capability is a string describing what the given user is allowed
to do. This takes the form of a comma separated list of allow
clauses with a permission specifier containing one or more of rwx for
read, write, and execute permission. The \fBallow *\fP grants full
superuser permissions for the given subsystem.
.sp
For example:
.sp
.nf
.ft C
# can read, write, and execute objects
osd = "allow rwx"
# can access mds server
mds = "allow"
# can modify cluster state (i.e., is a server daemon)
mon = "allow rwx"
.ft P
.fi
.sp
A librados user restricted to a single pool might look like:
.sp
.nf
.ft C
mon = "allow r"
osd = "allow rw pool foo"
.ft P
.fi
.sp
A client using rbd with read access to one pool and read/write access to another:
.sp
.nf
.ft C
mon = "allow r"
osd = "allow class\-read object_prefix rbd_children, allow pool templates r class\-read, allow pool vms rwx"
.ft P
.fi
.sp
A client mounting the file system with minimal permissions would need caps like:
.sp
.nf
.ft C
mds = "allow"
osd = "allow rw pool data"
mon = "allow r"
.ft P
.fi
.SH OSD CAPABILITIES
.sp
In general, an osd capability follows the grammar:
.sp
.nf
.ft C
osdcap := grant[,grant...]
grant := allow (match capspec | capspec match)
match := [pool[=]<poolname> | object_prefix <prefix>]
capspec := * | [r][w][x] [class\-read] [class\-write]
.ft P
.fi
.sp
The capspec determines what kind of operations the entity can perform:
.sp
.nf
.ft C
r = read access to objects
w = write access to objects
x = can call any class method (same as class\-read class\-write)
class\-read = can call class methods that are reads
class\-write = can call class methods that are writes
* = equivalent to rwx, plus the ability to run osd admin commands,
i.e. ceph osd tell ...
.ft P
.fi
.sp
The match criteria restrict a grant based on the pool being accessed.
Grants are additive if the client fulfills the match condition. For
example, if a client has the osd capabilities: "allow r object_prefix
prefix, allow w pool foo, allow x pool bar", then it has rw access to
pool foo, rx access to pool bar, and r access to objects whose
names begin with \(aqprefix\(aq in any pool.
.SH CAPS FILE FORMAT
.sp
The caps file format consists of zero or more key/value pairs, one per
line. The key and value are separated by an \fB=\fP, and the value must
be quoted (with \fB\(aq\fP or \fB"\fP) if it contains any whitespace. The key
is the name of the Ceph subsystem (\fBosd\fP, \fBmds\fP, \fBmon\fP), and the
value is the capability string (see above).
.SH EXAMPLE
.sp
To create a new keyring containing a key for client.foo:
.sp
.nf
.ft C
ceph\-authtool \-C \-n client.foo \-\-gen\-key keyring
.ft P
.fi
.sp
To associate some capabilities with the key (namely, the ability to
mount a Ceph filesystem):
.sp
.nf
.ft C
ceph\-authtool \-n client.foo \-\-cap mds \(aqallow\(aq \-\-cap osd \(aqallow rw pool=data\(aq \-\-cap mon \(aqallow r\(aq keyring
.ft P
.fi
.sp
To display the contents of the keyring:
.sp
.nf
.ft C
ceph\-authtool \-l keyring
.ft P
.fi
.sp
When mount a Ceph file system, you can grab the appropriately encoded secret key with:
.sp
.nf
.ft C
mount \-t ceph serverhost:/ mountpoint \-o name=foo,secret=\(gaceph\-authtool \-p \-n client.foo keyring\(ga
.ft P
.fi
.SH AVAILABILITY
.sp
\fBceph\-authtool\fP is part of the Ceph distributed file system. Please
refer to the Ceph documentation at \fI\%http://ceph.com/docs\fP for more
information.
.SH SEE ALSO
.sp
\fBceph\fP(8)
.SH COPYRIGHT
2010-2013, Inktank Storage, Inc. and contributors. Licensed under Creative Commons BY-SA
.\" Generated by docutils manpage writer.
.