doc: update ceph-authtool man page

* document osd capabilities
* fix librados user example
* fix example with outdated syntax (pool= and uid= are not supported)
* ignore auid, object prefix, and class restrictions for now since
  they aren't usable yet
* fix header for keyring file section

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

1 files changed, 38 insertions, 8 deletions

diff --git a/man/ceph-authtool.8 b/man/ceph-authtool.8
index 179ecb16859..46b150b4203 100644
--- a/man/ceph-authtool.8
+++ b/man/ceph-authtool.8
@@ -1,4 +1,4 @@
-.TH "CEPH-AUTHTOOL" "8" "May 21, 2012" "dev" "Ceph"
+.TH "CEPH-AUTHTOOL" "8" "September 26, 2012" "dev" "Ceph"
 .SH NAME
 ceph-authtool \- ceph keyring manipulation tool
 .
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.\" Man page generated from reStructeredText.
+.\" Man page generated from reStructuredText.
 .
 .SH SYNOPSIS
 .nf
@@ -93,7 +93,7 @@ The subsystem is the name of a Ceph subsystem: \fBmon\fP, \fBmds\fP, or
 \fBosd\fP.
 .sp
 The capability is a string describing what the given user is allowed
-to do. This takes the form of a comma separated list of allow, deny
+to do. This takes the form of a comma separated list of allow
 clauses with a permission specifier containing one or more of rwx for
 read, write, and execute permission. The \fBallow *\fP grants full
 superuser permissions for the given subsystem.
@@ -103,7 +103,7 @@ For example:
 .nf
 .ft C
 # can read, write, and execute objects
-osd = "allow rwx [pool=foo[,bar]]|[uid=baz[,bay]]"
+osd = "allow rwx"
 
 # can access mds server
 mds = "allow"
@@ -117,6 +117,8 @@ A librados user restricted to a single pool might look like:
 .sp
 .nf
 .ft C
+mon = "allow r"
+
 osd = "allow rw pool foo"
 .ft P
 .fi
@@ -127,11 +129,40 @@ A client mounting the file system with minimal permissions would need caps like:
 .ft C
 mds = "allow"
 
-osd = "allow rw pool=data"
+osd = "allow rw pool data"
 
 mon = "allow r"
 .ft P
 .fi
+.SH OSD CAPABILITIES
+.sp
+In general, an osd capability follows the grammar:
+.sp
+.nf
+.ft C
+osdcap  := grant[,grant...]
+grant   := allow (match capspec | capspec match)
+match   := [pool <poolname>]
+capspec := * | [r][w][x]
+.ft P
+.fi
+.sp
+The capspec determines what kind of operations the entity can perform:
+.sp
+.nf
+.ft C
+r = read access to objects
+w = write access to objects
+x = able to run class methods on objects
+* = equivalent to rwx
+.ft P
+.fi
+.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.
 .SH CAPS FILE FORMAT
 .sp
 The caps file format consists of zero or more key/value pairs, one per
@@ -176,13 +207,12 @@ mount \-t ceph serverhost:/ mountpoint \-o name=foo,secret=\(gaceph\-authtool \-
 .SH AVAILABILITY
 .sp
 \fBceph\-authtool\fP is part of the Ceph distributed file system. Please
-refer to the Ceph wiki at \fI\%http://ceph.newdream.net/wiki\fP for more
+refer to the Ceph documentation at \fI\%http://ceph.com/docs\fP for more
 information.
 .SH SEE ALSO
 .sp
 \fBceph\fP(8)
 .SH COPYRIGHT
-2012, New Dream Network
+2012, Inktank Storage, Inc.
 .\" Generated by docutils manpage writer.
-.\" 
 .