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   [ -a | --add-key *base64_key* ]
  21   [ --cap *subsystem* *capability* ]
  22   [ --caps *capfile* ]
  23   [ --mode *mode* ]
  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:: -a, --add-key *base64_key*
  75
  76    will add an encoded key to the keyring
  77
  78 .. option:: --cap *subsystem* *capability*
  79
  80    will set the capability for given subsystem
  81
  82 .. option:: --caps *capsfile*
  83
  84    will set all of capabilities associated with a given key, for all subsystems
  85
  86  .. option:: --mode *mode*
  87
  88     will set the desired file mode to the keyring e.g: 0644, defaults to 0600
  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                     | namespace[=]<rados-namespace>
 144                     | tag <application-name> <key>=<value> ]
 145         capspec := * | [r][w][x] [class-read] [class-write]
 146
 147 The capspec determines what kind of operations the entity can perform::
 148
 149     r           = read access to objects
 150     w           = write access to objects
 151     x           = can call any class method (same as class-read class-write)
 152     class-read  = can call class methods that are reads
 153     class-write = can call class methods that are writes
 154     * or "all"  = equivalent to rwx, plus the ability to run osd admin commands,
 155                   i.e. ceph osd tell ...
 156
 157 The match criteria restrict a grant based on the pool being accessed.
 158 Grants are additive if the client fulfills the match condition. For
 159 example, if a client has the osd capabilities: "allow r object_prefix
 160 prefix, allow w pool foo, allow x pool bar", then it has rw access to
 161 pool foo, rx access to pool bar, and r access to objects whose
 162 names begin with 'prefix' in any pool.
 163
 164 Caps file format
 165 ================
 166
 167 The caps file format consists of zero or more key/value pairs, one per
 168 line. The key and value are separated by an ``=``, and the value must
 169 be quoted (with ``'`` or ``"``) if it contains any whitespace. The key
 170 is the name of the Ceph subsystem (``osd``, ``mds``, ``mon``), and the
 171 value is the capability string (see above).
 172
 173
 174 Example
 175 =======
 176
 177 To create a new keyring containing a key for client.foo with a 0644 file mode::
 178
 179         ceph-authtool -C -n client.foo --gen-key keyring --mode 0644
 180
 181 To associate some capabilities with the key (namely, the ability to
 182 mount a Ceph file system)::
 183
 184         ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring
 185
 186 To display the contents of the keyring::
 187
 188         ceph-authtool -l keyring
 189
 190 When mounting a Ceph file system, you can grab the appropriately encoded secret key with::
 191
 192         mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring`
 193
 194
 195 Availability
 196 ============
 197
 198 **ceph-authtool** is part of Ceph, a massively scalable, open-source, distributed storage system. Please
 199 refer to the Ceph documentation at http://ceph.com/docs for more
 200 information.
 201
 202
 203 See also
 204 ========
 205
 206 :doc:`ceph <ceph>`\(8)