=============================================
 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* ] [ -b | --bin ]


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``.


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

.. option:: -b, --bin

   will create a binary formatted keyring


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, deny
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 wiki at http://ceph.newdream.net/wiki for more
information.


See also
========

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