src/ceph/doc/man/8/ceph-authtool.rst

   1 :orphan:
   2
   3 =================================================
   4  ceph-authtool -- ceph keyring manipulation tool
   5 =================================================
   6
   7 .. program:: ceph-authtool
   8
   9 Synopsis
  10 ========
  11
  12 | **ceph-authtool** *keyringfile*
  13   [ -l | --list ]
  14   [ -p | --print-key ]
  15   [ -C | --create-keyring ]
  16   [ -g | --gen-key ]
  17   [ --gen-print-key ]
  18   [ --import-keyring *otherkeyringfile* ]
  19   [ -n | --name *entityname* ]
  20   [ -u | --set-uid *auid* ]
  21   [ -a | --add-key *base64_key* ]
  22   [ --cap *subsystem* *capability* ]
  23   [ --caps *capfile* ]
  24
  25
  26 Description
  27 ===========
  28
  29 **ceph-authtool** is a utility to create, view, and modify a Ceph keyring
  30 file. A keyring file stores one or more Ceph authentication keys and
  31 possibly an associated capability specification. Each key is
  32 associated with an entity name, of the form
  33 ``{client,mon,mds,osd}.name``.
  34
  35 **WARNING** Ceph provides authentication and protection against
  36 man-in-the-middle attacks once secret keys are in place.  However,
  37 data over the wire is not encrypted, which may include the messages
  38 used to configure said keys. The system is primarily intended to be
  39 used in trusted environments.
  40
  41 Options
  42 =======
  43
  44 .. option:: -l, --list
  45
  46    will list all keys and capabilities present in the keyring
  47
  48 .. option:: -p, --print-key
  49
  50    will print an encoded key for the specified entityname. This is
  51    suitable for the ``mount -o secret=`` argument
  52
  53 .. option:: -C, --create-keyring
  54
  55    will create a new keyring, overwriting any existing keyringfile
  56
  57 .. option:: -g, --gen-key
  58
  59    will generate a new secret key for the specified entityname
  60
  61 .. option:: --gen-print-key
  62
  63    will generate a new secret key for the specified entityname,
  64    without altering the keyringfile, printing the secret to stdout
  65
  66 .. option:: --import-keyring *secondkeyringfile*
  67
  68    will import the content of a given keyring to the keyringfile
  69
  70 .. option:: -n, --name *name*
  71
  72    specify entityname to operate on
  73
  74 .. option:: -u, --set-uid *auid*
  75
  76    sets the auid (authenticated user id) for the specified entityname
  77
  78 .. option:: -a, --add-key *base64_key*
  79
  80    will add an encoded key to the keyring
  81
  82 .. option:: --cap *subsystem* *capability*
  83
  84    will set the capability for given subsystem
  85
  86 .. option:: --caps *capsfile*
  87
  88    will set all of capabilities associated with a given key, for all subsystems
  89
  90
  91 Capabilities
  92 ============
  93
  94 The subsystem is the name of a Ceph subsystem: ``mon``, ``mds``, or
  95 ``osd``.
  96
  97 The capability is a string describing what the given user is allowed
  98 to do. This takes the form of a comma separated list of allow
  99 clauses with a permission specifier containing one or more of rwx for
 100 read, write, and execute permission. The ``allow *`` grants full
 101 superuser permissions for the given subsystem.
 102
 103 For example::
 104
 105         # can read, write, and execute objects
 106         osd = "allow rwx"
 107
 108         # can access mds server
 109         mds = "allow"
 110
 111         # can modify cluster state (i.e., is a server daemon)
 112         mon = "allow rwx"
 113
 114 A librados user restricted to a single pool might look like::
 115
 116         mon = "allow r"
 117
 118         osd = "allow rw pool foo"
 119
 120 A client using rbd with read access to one pool and read/write access to another::
 121
 122         mon = "allow r"
 123
 124         osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx"
 125
 126 A client mounting the file system with minimal permissions would need caps like::
 127
 128         mds = "allow"
 129
 130         osd = "allow rw pool data"
 131
 132         mon = "allow r"
 133
 134
 135 OSD Capabilities
 136 ================
 137
 138 In general, an osd capability follows the grammar::
 139
 140         osdcap  := grant[,grant...]
 141         grant   := allow (match capspec | capspec match)
 142         match   := [pool[=]<poolname> | object_prefix <prefix>]
 143         capspec := * | [r][w][x] [class-read] [class-write]
 144
 145 The capspec determines what kind of operations the entity can perform::
 146
 147     r           = read access to objects
 148     w           = write access to objects
 149     x           = can call any class method (same as class-read class-write)
 150     class-read  = can call class methods that are reads
 151     class-write = can call class methods that are writes
 152     *           = equivalent to rwx, plus the ability to run osd admin commands,
 153                   i.e. ceph osd tell ...
 154
 155 The match criteria restrict a grant based on the pool being accessed.
 156 Grants are additive if the client fulfills the match condition. For
 157 example, if a client has the osd capabilities: "allow r object_prefix
 158 prefix, allow w pool foo, allow x pool bar", then it has rw access to
 159 pool foo, rx access to pool bar, and r access to objects whose
 160 names begin with 'prefix' in any pool.
 161
 162 Caps file format
 163 ================
 164
 165 The caps file format consists of zero or more key/value pairs, one per
 166 line. The key and value are separated by an ``=``, and the value must
 167 be quoted (with ``'`` or ``"``) if it contains any whitespace. The key
 168 is the name of the Ceph subsystem (``osd``, ``mds``, ``mon``), and the
 169 value is the capability string (see above).
 170
 171
 172 Example
 173 =======
 174
 175 To create a new keyring containing a key for client.foo::
 176
 177         ceph-authtool -C -n client.foo --gen-key keyring
 178
 179 To associate some capabilities with the key (namely, the ability to
 180 mount a Ceph filesystem)::
 181
 182         ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring
 183
 184 To display the contents of the keyring::
 185
 186         ceph-authtool -l keyring
 187
 188 When mounting a Ceph file system, you can grab the appropriately encoded secret key with::
 189
 190         mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring`
 191
 192
 193 Availability
 194 ============
 195
 196 **ceph-authtool** is part of Ceph, a massively scalable, open-source, distributed storage system. Please
 197 refer to the Ceph documentation at http://ceph.com/docs for more
 198 information.
 199
 200
 201 See also
 202 ========
 203
 204 :doc:`ceph <ceph>`\(8)