mirror of https://github.com/ceph/ceph
273 lines
6.5 KiB
Groff
273 lines
6.5 KiB
Groff
.TH "CEPH-AUTHTOOL" "8" "December 29, 2012" "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 \-\-gen\-key
|
|
will generate a new secret key for the specified entityname
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-add\-key
|
|
will add an encoded key to the keyring
|
|
.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:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.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
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
A librados user restricted to a single pool might look like:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mon = "allow r"
|
|
|
|
osd = "allow rw pool foo"
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
A client using rbd with read access to one pool and read/write access to another:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.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
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
A client mounting the file system with minimal permissions would need caps like:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mds = "allow"
|
|
|
|
osd = "allow rw pool data"
|
|
|
|
mon = "allow r"
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH OSD CAPABILITIES
|
|
.sp
|
|
In general, an osd capability follows the grammar:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.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
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The capspec determines what kind of operations the entity can perform:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.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
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.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:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
ceph\-authtool \-C \-n client.foo \-\-gen\-key keyring
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
To associate some capabilities with the key (namely, the ability to
|
|
mount a Ceph filesystem):
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.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
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
To display the contents of the keyring:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
ceph\-authtool \-l keyring
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
When mount a Ceph file system, you can grab the appropriately encoded secret key with:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mount \-t ceph serverhost:/ mountpoint \-o name=foo,secret=\(gaceph\-authtool \-p \-n client.foo keyring\(ga
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.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-2012, Inktank Storage, Inc. and contributors. Licensed under Creative Commons BY-SA
|
|
.\" Generated by docutils manpage writer.
|
|
.
|