NAME¶
ceph-authtool - ceph keyring manipulation tool
SYNOPSIS¶
ceph-authtool keyringfile [ -l | --list ] [ -C | --create-keyring
] [ -p | --print ] [ -n | --name entityname ] [ --gen-key ] [ -a |
--add-key base64_key ] [ --caps capfile ]
DESCRIPTION¶
ceph-authtool 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
{client,mon,mds,osd}.name.
WARNING 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.
OPTIONS¶
- -l, --list
- will list all keys and capabilities present in the
keyring
- -p, --print
- will print an encoded key for the specified entityname.
This is suitable for the mount -o secret= argument
- -C, --create-keyring
- will create a new keyring, overwriting any existing
keyringfile
- --gen-key
- will generate a new secret key for the specified
entityname
- --add-key
- will add an encoded key to the keyring
- --cap subsystem capability
- will set the capability for given subsystem
- --caps capsfile
- will set all of capabilities associated with a given key,
for all subsystems
CAPABILITIES¶
The subsystem is the name of a Ceph subsystem:
mon,
mds, or
osd.
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
allow * grants full superuser permissions for the given
subsystem.
For example:
# 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"
A librados user restricted to a single pool might look like:
mon = "allow r"
osd = "allow rw pool foo"
A client using rbd with read access to one pool and read/write access to
another:
mon = "allow r"
osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx"
A client mounting the file system with minimal permissions would need caps like:
mds = "allow"
osd = "allow rw pool data"
mon = "allow r"
OSD CAPABILITIES¶
In general, an osd capability follows the grammar:
osdcap := grant[,grant...]
grant := allow (match capspec | capspec match)
match := [pool[=]<poolname> | object_prefix <prefix>]
capspec := * | [r][w][x] [class-read] [class-write]
The capspec determines what kind of operations the entity can perform:
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 ...
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 'prefix' in any pool.
The caps file format consists of zero or more key/value pairs, one per line. The
key and value are separated by an
=, and the value must be quoted (with
' or
") if it contains any whitespace. The key is the name
of the Ceph subsystem (
osd,
mds,
mon), and the value is
the capability string (see above).
EXAMPLE¶
To create a new keyring containing a key for client.foo:
ceph-authtool -C -n client.foo --gen-key keyring
To associate some capabilities with the key (namely, the ability to mount a Ceph
filesystem):
ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring
To display the contents of the keyring:
When mount a Ceph file system, you can grab the appropriately encoded secret key
with:
mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring`
AVAILABILITY¶
ceph-authtool is part of the Ceph distributed storage system. Please
refer to the Ceph documentation at
http://ceph.com/docs for more
information.
SEE ALSO¶
ceph(8)
COPYRIGHT¶
2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative
Commons BY-SA