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