doc: fix rbd permissions for unprotect

Unprotect examines all pools, so use blanket x before 0.54. After
that, use class-read restricted by object_prefix to rbd_children.

Signed-off-by: Josh Durgin <josh.durgin@inktank.com>

doc/man/8/ceph-authtool.rst

@@ -93,7 +93,7 @@ A client using rbd with read access to one pool and read/write access to another
 
         mon = "allow r"
 
-        osd = "allow pool templates r class-read, allow pool vms rwx"
+        osd = "allow class-read object_prefix rbd_children, allow pool templates r class-read, allow pool vms rwx"
 
 A client mounting the file system with minimal permissions would need caps like::
 
@@ -111,7 +111,7 @@ In general, an osd capability follows the grammar::
 
         osdcap  := grant[,grant...]
         grant   := allow (match capspec | capspec match)
-        match   := [pool[=]<poolname>]
+        match   := [pool[=]<poolname> | object_prefix <prefix>]
         capspec := * | [r][w][x] [class-read] [class-write]
 
 The capspec determines what kind of operations the entity can perform::
@@ -126,10 +126,10 @@ The capspec determines what kind of operations the entity can perform::
 
 The match criteria restrict a grant based on the pool being accessed.
 Grants are additive if the client fulfills the match condition. For
-example, if a client has the osd capabilities: "allow r, allow w pool
-foo, allow x pool bar", then it has rw access to pool foo, rx access
-to pool bar, and r access to all other pools.
-
+example, if a client has the osd capabilities: "allow r object_prefix
+prefix, allow w pool foo, allow x pool bar", then it has rw access to
+pool foo, rx access to pool bar, and r access to objects whose
+names begin with 'prefix' in any pool.
 
 Caps file format
 ================

doc/rados/operations/authentication.rst

@@ -236,7 +236,7 @@ daemon type 'osd' and 'r' for daemon type 'mon'::
    sudo ceph auth get-or-create-key client.foo osd rw mon r > keyring.foo
 
 .. note: User names are associated to user types, which include ``client``
-   ``admin``, ``osd``, ``mon``, and ``mds``. In most cases, you will be 
+   ``osd``, ``mon``, and ``mds``. In most cases, you will be
    creating keys for ``client`` users.
 
 .. _auth-delete-key:

doc/rbd/rbd-openstack.rst

@@ -97,10 +97,16 @@ Setup Ceph Client Authentication
 --------------------------------
 
 If you have `cephx authentication`_ enabled, create a new user for Nova/Cinder
-and Glance::
+and Glance. For Ceph before version 0.54 or lower::
 
-    ceph auth get-or-create client.volumes mon 'allow r' osd 'allow rwx pool=volumes, allow rx pool=images'
-    ceph auth get-or-create client.images mon 'allow r' osd 'allow rwx pool=images'
+    ceph auth get-or-create client.volumes mon 'allow r' osd 'allow x, allow rwx pool=volumes, allow rx pool=images'
+    ceph auth get-or-create client.images mon 'allow r' osd 'allow x, allow rwx pool=images'
+
+In Ceph version 0.54, more specific permissions were added, so the
+users can be restricted further::
+
+    ceph auth get-or-create client.volumes mon 'allow r' osd 'allow class-read object_prefix rbd_children, allow rwx pool=volumes, allow rx pool=images'
+    ceph auth get-or-create client.images mon 'allow r' osd 'allow class-read object_prefix rbd_children, allow rwx pool=images'
 
 Add the keyrings for ``client.volumes`` and ``client.images`` to the
 appropriate hosts and change their ownership::

man/ceph-authtool.8

@@ -1,4 +1,4 @@
-.TH "CEPH-AUTHTOOL" "8" "September 28, 2012" "dev" "Ceph"
+.TH "CEPH-AUTHTOOL" "8" "December 29, 2012" "dev" "Ceph"
 .SH NAME
 ceph-authtool \- ceph keyring manipulation tool
 .
@@ -99,6 +99,8 @@ read, write, and execute permission. The \fBallow *\fP grants full
 superuser permissions for the given subsystem.
 .sp
 For example:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
@@ -112,8 +114,12 @@ mds = "allow"
 mon = "allow rwx"
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 A librados user restricted to a single pool might look like:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
@@ -122,18 +128,26 @@ mon = "allow r"
 osd = "allow rw pool foo"
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 A client using rbd with read access to one pool and read/write access to another:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 mon = "allow r"
 
-osd = "allow pool templates r class\-read, allow pool vms rwx"
+osd = "allow class\-read object_prefix rbd_children, allow pool templates r class\-read, allow pool vms rwx"
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 A client mounting the file system with minimal permissions would need caps like:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
@@ -144,20 +158,28 @@ osd = "allow rw pool data"
 mon = "allow r"
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .SH OSD CAPABILITIES
 .sp
 In general, an osd capability follows the grammar:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 osdcap  := grant[,grant...]
 grant   := allow (match capspec | capspec match)
-match   := [pool[=]<poolname>]
+match   := [pool[=]<poolname> | object_prefix <prefix>]
 capspec := * | [r][w][x] [class\-read] [class\-write]
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 The capspec determines what kind of operations the entity can perform:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
@@ -170,12 +192,15 @@ class\-write = can call class methods that are writes
               i.e. ceph osd tell ...
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 The match criteria restrict a grant based on the pool being accessed.
 Grants are additive if the client fulfills the match condition. For
-example, if a client has the osd capabilities: "allow r, allow w pool
-foo, allow x pool bar", then it has rw access to pool foo, rx access
-to pool bar, and r access to all other pools.
+example, if a client has the osd capabilities: "allow r object_prefix
+prefix, allow w pool foo, allow x pool bar", then it has rw access to
+pool foo, rx access to pool bar, and r access to objects whose
+names begin with \(aqprefix\(aq in any pool.
 .SH CAPS FILE FORMAT
 .sp
 The caps file format consists of zero or more key/value pairs, one per
@@ -186,37 +211,53 @@ value is the capability string (see above).
 .SH EXAMPLE
 .sp
 To create a new keyring containing a key for client.foo:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 ceph\-authtool \-C \-n client.foo \-\-gen\-key keyring
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 To associate some capabilities with the key (namely, the ability to
 mount a Ceph filesystem):
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 ceph\-authtool \-n client.foo \-\-cap mds \(aqallow\(aq \-\-cap osd \(aqallow rw pool=data\(aq \-\-cap mon \(aqallow r\(aq keyring
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 To display the contents of the keyring:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 ceph\-authtool \-l keyring
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 When mount a Ceph file system, you can grab the appropriately encoded secret key with:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 mount \-t ceph serverhost:/ mountpoint \-o name=foo,secret=\(gaceph\-authtool \-p \-n client.foo keyring\(ga
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .SH AVAILABILITY
 .sp
 \fBceph\-authtool\fP is part of the Ceph distributed file system. Please
@@ -226,6 +267,6 @@ information.
 .sp
 \fBceph\fP(8)
 .SH COPYRIGHT
-2012, Inktank Storage, Inc.
+2010-2012, Inktank Storage, Inc. and contributors. Licensed under Creative Commons BY-SA
 .\" Generated by docutils manpage writer.
 .