1 files changed, 48 insertions, 28 deletions
diff --git a/man/ceph-rest-api.8 b/man/ceph-rest-api.8
index 33425fecc00..5170b7f37cf 100644
--- a/man/ceph-rest-api.8
+++ b/man/ceph-rest-api.8
@@ -1,4 +1,4 @@
-.TH "CEPH-REST-API" "8" "July 12, 2013" "dev" "Ceph"
+.TH "CEPH-REST-API" "8" "July 26, 2013" "dev" "Ceph"
 .SH NAME
 ceph-rest-api \- ceph RESTlike administration server
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .
 .SH SYNOPSIS
 .nf
-\fBceph\-rest\-api\fP [ \-c \fIconffile\fP ] [ \-n \fIname\fP ... ]
+\fBceph\-rest\-api\fP [ \-c \fIconffile\fP ] [\-\-cluster \fIclustername\fP ] [ \-n \fIname\fP ] [\-i \fIid\fP ]
 .fi
 .sp
 .SH DESCRIPTION
@@ -44,7 +44,7 @@ command\-line tool through an HTTP\-accessible interface.
 .SH OPTIONS
 .INDENT 0.0
 .TP
-.B \-c/\-\-conf *conffile*
+.B \-c/\-\-conf conffile
 names the ceph.conf file to use for configuration.  If \-c is not
 specified, the default depends on the state of the \-\-cluster option
 (default \(aqceph\(aq; see below).  The configuration file is searched
@@ -64,43 +64,54 @@ so you can also pass this option in the environment as CEPH_CONF.
 .UNINDENT
 .INDENT 0.0
 .TP
-.B \-\-cluster *clustername*
+.B \-\-cluster clustername
 set \fIclustername\fP for use in the $cluster metavariable, for
 locating the ceph.conf file.  The default is \(aqceph\(aq.
-You can also pass this option in the environment as
-CEPH_CLUSTER_NAME.
 .UNINDENT
 .INDENT 0.0
 .TP
-.B \-n/\-\-name *name*
+.B \-n/\-\-name name
 specifies the client \(aqname\(aq, which is used to find the
 client\-specific configuration options in the config file, and
 also is the name used for authentication when connecting
 to the cluster (the entity name appearing in ceph auth list output,
-for example).  The default is \(aqclient.restapi\(aq.  You can also
-pass this option in the environment as CEPH_NAME.
+for example).  The default is \(aqclient.restapi\(aq.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-i/\-\-id id
+specifies the client \(aqid\(aq, which will form the clientname
+as \(aqclient.<id>\(aq if clientname is not set.  If \-n/\-name is
+set, that takes precedence.
+.sp
+Also, global Ceph options are supported.
 .UNINDENT
 .SH CONFIGURATION PARAMETERS
 .sp
 Supported configuration parameters include:
 .INDENT 0.0
 .IP \(bu 2
-\fBrestapi client name\fP the \(aqclientname\(aq used for auth and ceph.conf
+\fBkeyring\fP the keyring file holding the key for \(aqclientname\(aq
 .IP \(bu 2
-\fBrestapi keyring\fP the keyring file holding the key for \(aqclientname\(aq
+\fBpublic addr\fP ip:port to listen on (default 0.0.0.0:5000)
 .IP \(bu 2
-\fBrestapi public addr\fP ip:port to listen on (default 0.0.0.0:5000)
+\fBlog file\fP (usual Ceph default)
 .IP \(bu 2
 \fBrestapi base url\fP the base URL to answer requests on (default /api/v0.1)
 .IP \(bu 2
-\fBrestapi log level\fP critical, error, warning, info, debug
-.IP \(bu 2
-\fBrestapi log file\fP (default /var/local/ceph/<clientname>.log)
+\fBrestapi log level\fP critical, error, warning, info, debug (default warning)
 .UNINDENT
 .sp
-A server will run on \fBrestapi public addr\fP if the ceph\-rest\-api
-executed directly; otherwise, configuration is specified by the
-enclosing WSGI web server.
+Configuration parameters are searched in the standard order:
+first in the section named \(aq<clientname>\(aq, then \(aqclient\(aq, then \(aqglobal\(aq.
+.sp
+<clientname> is either supplied by \-n/\-\-name, "client.<id>" where
+<id> is supplied by \-i/\-\-id, or \(aqclient.restapi\(aq if neither option
+is present.
+.sp
+A single\-threaded server will run on \fBpublic addr\fP if the ceph\-rest\-api
+executed directly; otherwise, configuration is specified by the enclosing
+WSGI web server.
 .SH COMMANDS
 .sp
 Commands are submitted with HTTP GET requests (for commands that
@@ -122,28 +133,37 @@ with a small description of each command, is provided when the requested
 path is incomplete/partially matching.  Requesting / will redirect to
 the value of  \fBrestapi base url\fP, and that path will give a full list
 of all known commands.  The command set is very similar to the commands
-supported by the \fBceph\fP tool.
+supported by the \fBceph\fP tool.  One notable exception is that the
+\fBceph pg <pgid> <command>\fP style of commands is supported here
+as \fBtell/<pgid>/command?args\fP.
 .SH DEPLOYMENT AS WSGI APPLICATION
 .sp
 When deploying as WSGI application (say, with Apache/mod_wsgi,
 or nginx/uwsgi, or gunicorn, etc.), use the \fBceph_rest_api.py\fP module
 (\fBceph\-rest\-api\fP is a thin layer around this module).  The standalone web
 server is of course not used, so address/port configuration is done in
-the WSGI server.  Also, configuration switches are not passed; rather,
-environment variables are used:
+the WSGI server.  Use a python .wsgi module or the equivalent to call
+\fBapp = generate_app(conf, cluster, clientname, clientid, args)\fP where:
 .INDENT 0.0
 .IP \(bu 2
-CEPH_CONF holds \-c/\-\-conf
+conf is as \-c/\-\-conf above
+.IP \(bu 2
+cluster is as \-\-cluster above
 .IP \(bu 2
-CEPH_CLUSTER_NAME holds \-\-cluster
+clientname, \-n/\-\-name
 .IP \(bu 2
-CEPH_NAME holds \-n/\-\-name
+clientid, \-i/\-\-id, and
+.IP \(bu 2
+args are any other generic Ceph arguments
 .UNINDENT
 .sp
-Any errors reading configuration or connecting to the cluster cause
-ImportError to be raised with a descriptive message on import; see
-your WSGI server documentation for how to see those messages in case
-of problem.
+When app is returned, it will have attributes \(aqceph_addr\(aq and \(aqceph_port\(aq
+set to what the address and port are in the Ceph configuration;
+those may be used for the server, or ignored.
+.sp
+Any errors reading configuration or connecting to the cluster cause an
+exception to be raised; see your WSGI server documentation for how to
+see those messages in case of problem.
 .SH AVAILABILITY
 .sp
 \fBceph\-rest\-api\fP is part of the Ceph distributed file system. Please refer to the Ceph documentation at