mirror of
https://github.com/ceph/ceph
synced 2024-12-22 03:22:00 +00:00
8c3bfaa30a
* document osd capabilities * fix librados user example * fix example with outdated syntax (pool= and uid= are not supported) * ignore auid, object prefix, and class restrictions for now since they aren't usable yet * fix header for keyring file section Signed-off-by: Josh Durgin <josh.durgin@inktank.com>
219 lines
5.4 KiB
Groff
219 lines
5.4 KiB
Groff
.TH "CEPH-AUTHTOOL" "8" "September 26, 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:
|
|
.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 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>]
|
|
capspec := * | [r][w][x]
|
|
.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 = able to run class methods on objects
|
|
* = equivalent to rwx
|
|
.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, 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 all other pools.
|
|
.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
|
|
2012, Inktank Storage, Inc.
|
|
.\" Generated by docutils manpage writer.
|
|
.
|