=================================================
 ceph-authtool -- ceph keyring manipulation tool
=================================================

.. program:: ceph-authtool

Synopsis
========

| **ceph-authtool** *keyringfile* [ -l | --list ] [ -C | --create-keyring
  ] [ -p | --print ] [ -n | --name *entityname* ] [ --gen-key ] [ -a |
  --add-key *base64_key* ] [ --caps *capfils* ]


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
=======

.. option:: -l, --list

   will list all keys and capabilities present in the keyring

.. option:: -p, --print

   will print an encoded key for the specified entityname. This is
   suitable for the ``mount -o secret=`` argument

.. option:: -C, --create-keyring

   will create a new keyring, overwriting any existing keyringfile

.. option:: --gen-key

   will generate a new secret key for the specified entityname

.. option:: --add-key

   will add an encoded key to the keyring

.. option:: --cap subsystem capability

   will set the capability for given subsystem

.. option:: --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 [pool=foo[,bar]]|[uid=baz[,bay]]"

	# 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::

        osd = "allow rw pool foo"

A client mounting the file system with minimal permissions would need caps like::

        mds = "allow"

        osd = "allow rw pool=data"

        mon = "allow r"


Caps file format
================

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::

        ceph-authtool -l 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 file system. Please
refer to the Ceph documentation at http://ceph.com/docs for more
information.


See also
========

:doc:`ceph <ceph>`\(8)