debian: include cauthtool

diff --git a/debian/ceph.install b/debian/ceph.install
index 5e14bc3cedfaff680bca66ed628a0622e2a60a92..c0c098ec67287c8b3fa6e32c22dc48e4fa6a0ef5 100644 (file)
--- a/debian/ceph.install
+++ b/debian/ceph.install
@@ -9,6 +9,7 @@ usr/bin/cmon
 usr/bin/cmds
 usr/bin/cosd
 usr/bin/mkmonfs
+usr/bin/cauthtool
 usr/sbin/mount.ceph
 usr/sbin/mkcephfs
 usr/lib/ceph/ceph_common.sh

diff --git a/man/Makefile.am b/man/Makefile.am
index c72102355853e476dc79938be8fa75ff1a79b496..a13eac92f7782d829fd64528a6d9dcf8b189b68d 100644 (file)
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -16,4 +16,5 @@ dist_man_MANS = \
        ceph.8 \
        mount.ceph.8 \
        radosgw.8 \
-       radosgw_admin.8
+       radosgw_admin.8 \
+       cauthtool.8

diff --git a/man/cauthtool.8 b/man/cauthtool.8
new file mode 100644 (file)
index 0000000..7e624b4
--- /dev/null
+++ b/man/cauthtool.8
@@ -0,0 +1,83 @@
+.TH CAUTHTOOL 8
+.SH NAME
+cauthtool \- ceph keyring manipulation tool
+.SH SYNOPSIS
+.B cauthtool
+\fIkeyringfile\fP
+[ \fB\-l\fR | \fB\-\-list\fR ]
+[ \fB\-c\fR | \fB\-\-create-keyring\fR ]
+[ \fB\-p\fR | \fB\-\-print\fR ]
+[ \fB\-n\fR | \fB\-\-name\fR \fIentityname\fP ]
+[ \fB\-\-gen-key\fR ]
+[ \fB\-a\fR | \fB\-\-add-key \fIbase64_key\fP ]
+[ \fB\-\-caps\fR \fIcapfils\fP ]
+.SH DESCRIPTION
+.B cauthtool
+is a utility to create, view, and modify a Ceph keyring file.  A keyring
+file stores one or more Ceph authentication keys and possibly an 
+associated capability specification.  Each key is associated with an
+entity name, of the form \fI{client,mon,mds,osd}.name\fP.
+.SH OPTIONS
+.TP
+\fB\-l\fP, \fB\-\-list\fP
+will list all keys and capabilities present in the keyring.
+.TP
+\fB\-p\fP, \fB\-\-print\fP
+will print an encoded key for the specified \fIentityname\fP.  This is suitable for the mount -o secret= argument.
+.TP
+\fB\-c\fP, \fB\-\-create-keyring\fP
+will create a new keyring, overwriting any existing \fIkeyringfile\fP.
+.TP
+\fB\-\-gen\-key\fP
+will generate a new secret key for the specified \fIentityname\fP:
+.TP
+\fB\-\-add\-key\fP
+will add an encoded key to the keyring.
+.TP
+\fB\-\-caps\fI capsfile \fP
+will set the capabilities associated with a given key.
+.SH CAPS FILE FORMAT
+The caps file format consists of zero or more key/value pairs.  The key is the name of the Ceph
+subsystem (osd, mds, mon).  The value is a comma separated list of allow, deny clauses with a permission
+specifier containing one or more of \fIrwx\fP, for read, write, and execute permission.  For
+example,
+.IP
+osd = "allow rwx [pool foo]"  # can read, write, and execute objects
+.IP
+mds = "allow"      # can access mds server
+.IP
+mon = "allow rwx"  # can modify cluster state (i.e., is a server daemon)
+.PP
+A librados user restricted to a single pool might look like
+.IP
+osd = "allow rw pool foo"
+.PP
+A client mounting the file system with minimal permissions would need caps like
+.IP
+mds = "allow"
+.IP
+osd = "allow rw pool data"
+.PP
+.SH EXAMPLE
+To create a new keyring containing a key for \fIclient.foo\fP:
+.IP
+cauthtool -c -n client.foo --gen-key keyring.bin
+.PP
+To associate some capabilities with the key:
+.IP
+cauthtool -n client.foo --caps foocaps.conf keyring.bin
+.PP
+To display the contents of the keyring:
+.IP
+cauthtool -l keyring.bin
+.PP
+When mount a Ceph file system, you can grab the appropriately encoded secret key with
+.IP
+mount -t ceph serverhost:/ mountpoint -o name=foo,secret=`cauthtool -p -n client.foo keyring.bin`
+.PP
+.SH AVAILABILITY
+.B cauthtool
+is part of the Ceph distributed file system.  Please refer to the Ceph wiki at
+http://ceph.newdream.net/wiki for more information.
+.SH SEE ALSO
+.BR ceph (8)