1CEPH-AUTHTOOL(8)                     Ceph                     CEPH-AUTHTOOL(8)
2
3
4

NAME

6       ceph-authtool - ceph keyring manipulation tool
7

SYNOPSIS

9       ceph-authtool keyringfile
10       [ -l | --list ]
11       [ -p | --print-key ]
12       [ -C | --create-keyring ]
13       [ -g | --gen-key ]
14       [ --gen-print-key ]
15       [ --import-keyring otherkeyringfile ]
16       [ -n | --name entityname ]
17       [ -a | --add-key base64_key ]
18       [ --cap subsystem capability ]
19       [ --caps capfile ]
20       [ --mode mode ]
21
22

DESCRIPTION

24       ceph-authtool  is  a utility to create, view, and modify a Ceph keyring
25       file. A keyring file stores one or more Ceph  authentication  keys  and
26       possibly an associated capability specification. Each key is associated
27       with an entity name, of the form {client,mon,mds,osd}.name.
28
29       WARNING   Ceph   provides   authentication   and   protection   against
30       man-in-the-middle attacks once secret keys are in place.  However, data
31       over the wire is not encrypted, which may include the messages used  to
32       configure  said  keys.  The  system is primarily intended to be used in
33       trusted environments.
34

OPTIONS

36       -l, --list
37              will list all keys and capabilities present in the keyring
38
39       -p, --print-key
40              will print an encoded key for the specified entityname. This  is
41              suitable for the mount -o secret= argument
42
43       -C, --create-keyring
44              will create a new keyring, overwriting any existing keyringfile
45
46       -g, --gen-key
47              will generate a new secret key for the specified entityname
48
49       --gen-print-key
50              will  generate  a  new  secret key for the specified entityname,
51              without altering the keyringfile, printing the secret to stdout
52
53       --import-keyring *secondkeyringfile*
54              will import the content of a given keyring to the keyringfile
55
56       -n, --name *name*
57              specify entityname to operate on
58
59       -a, --add-key *base64_key*
60              will add an encoded key to the keyring
61
62       --cap *subsystem* *capability*
63              will set the capability for given subsystem
64
65       --caps *capsfile*
66                 will set all of capabilities associated with a given key, for
67                 all subsystems
68
69              --mode *mode*
70                     will  set the desired file mode to the keyring e.g: 0644,
71                     defaults to 0600
72

CAPABILITIES

74       The subsystem is the name of a Ceph subsystem: mon, mds, or osd.
75
76       The capability is a string describing what the given user is allowed to
77       do. This takes the form of a comma separated list of allow clauses with
78       a permission specifier containing one or more of rwx for  read,  write,
79       and  execute  permission. The allow * grants full superuser permissions
80       for the given subsystem.
81
82       For example:
83
84          # can read, write, and execute objects
85          osd = "allow rwx"
86
87          # can access mds server
88          mds = "allow"
89
90          # can modify cluster state (i.e., is a server daemon)
91          mon = "allow rwx"
92
93       A librados user restricted to a single pool might look like:
94
95          mon = "allow r"
96
97          osd = "allow rw pool foo"
98
99       A client using rbd with read access to one pool and  read/write  access
100       to another:
101
102          mon = "allow r"
103
104          osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx"
105
106       A  client  mounting the file system with minimal permissions would need
107       caps like:
108
109          mds = "allow"
110
111          osd = "allow rw pool data"
112
113          mon = "allow r"
114

OSD CAPABILITIES

116       In general, an osd capability follows the grammar:
117
118          osdcap  := grant[,grant...]
119          grant   := allow (match capspec | capspec match)
120          match   := [ pool[=]<poolname> | object_prefix <prefix>
121                      | namespace[=]<rados-namespace>
122                      | tag <application-name> <key>=<value> ]
123          capspec := * | [r][w][x] [class-read] [class-write]
124
125       The capspec determines what kind of operations the entity can perform:
126
127          r           = read access to objects
128          w           = write access to objects
129          x           = can call any class method (same as class-read class-write)
130          class-read  = can call class methods that are reads
131          class-write = can call class methods that are writes
132          * or "all"  = equivalent to rwx, plus the ability to run osd admin commands,
133                        i.e. ceph osd tell ...
134
135       The match criteria restrict a grant based on the pool  being  accessed.
136       Grants are additive if the client fulfills the match condition. For ex‐
137       ample, if a client has the osd  capabilities:  "allow  r  object_prefix
138       prefix,  allow  w pool foo, allow x pool bar", then it has rw access to
139       pool foo, rx access to pool bar, and r access to  objects  whose  names
140       begin with 'prefix' in any pool.
141

CAPS FILE FORMAT

143       The  caps file format consists of zero or more key/value pairs, one per
144       line. The key and value are separated by an =, and the  value  must  be
145       quoted (with ' or ") if it contains any whitespace. The key is the name
146       of the Ceph subsystem (osd, mds, mon), and the value is the  capability
147       string (see above).
148

EXAMPLE

150       To  create  a  new  keyring containing a key for client.foo with a 0644
151       file mode:
152
153          ceph-authtool -C -n client.foo --gen-key keyring --mode 0644
154
155       To associate some capabilities with the key  (namely,  the  ability  to
156       mount a Ceph file system):
157
158          ceph-authtool -n client.foo --cap mds 'allow' --cap osd 'allow rw pool=data' --cap mon 'allow r' keyring
159
160       To display the contents of the keyring:
161
162          ceph-authtool -l keyring
163
164       When  mounting  a  Ceph file system, you can grab the appropriately en‐
165       coded secret key with:
166
167          mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`ceph-authtool -p -n client.foo keyring`
168

AVAILABILITY

170       ceph-authtool is part of Ceph, a massively scalable, open-source,  dis‐
171       tributed  storage  system.  Please  refer  to the Ceph documentation at
172       http://ceph.com/docs for more information.
173

SEE ALSO

175       ceph(8)
176
178       2010-2021, Inktank Storage, Inc. and contributors. Licensed under  Cre‐
179       ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
180
181
182
183
184dev                              May 13, 2021                 CEPH-AUTHTOOL(8)
Impressum