ceph-rest-api manpage

Signed-off-by: Dan Mick <dan.mick@inktank.com>

3 files changed, 220 insertions, 1 deletions

diff --git a/doc/man/8/ceph-rest-api.rst b/doc/man/8/ceph-rest-api.rst
new file mode 100644
index 00000000000..d8727abb49a
--- /dev/null
+++ b/doc/man/8/ceph-rest-api.rst
@@ -0,0 +1,96 @@
+=====================================================
+ ceph-rest-api -- ceph RESTlike administration server
+=====================================================
+
+.. program:: ceph-rest-api
+
+Synopsis
+========
+
+| **ceph-rest-api** [ -c *conffile* ] [ -n *name* ... ]
+
+
+Description
+===========
+
+**ceph-rest-api** is a WSGI application that can run as a
+standalone web service or run under a web server that supports
+WSGI.  It provides much of the functionality of the **ceph**
+command-line tool through an HTTP-accessible interface.
+
+Options
+=======
+
+.. option:: -c/--conf *conffile*
+
+    names the ceph.conf file to use for configuration.  If -c
+    is not specified, the configuration file is searched for in
+    this order:
+
+    * $CEPH_CONF
+    * /etc/ceph/ceph.conf
+    * ~/.ceph/ceph.conf
+    * ceph.conf (in the current directory)
+
+.. option:: -n/--name *name*
+
+    specifies the client 'name', 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 'client.restapi'.
+
+
+Configuration parameters
+========================
+
+Supported configuration parameters include:
+
+* **restapi keyring** the keyring file holding the key for 'clientname'
+* **restapi public addr** ip:port to listen on (default 0.0.0.0:5000)
+* **restapi base url** the base URL to answer requests on (default /api/v0.1)
+* **restapi log level** critical, error, warning, info, debug
+* **restapi log file** (default /var/local/ceph/<clientname>.log)
+
+A server will run on **restapi public addr** if the ceph-rest-api
+executed directly; otherwise, configuration is specified by the
+enclosing WSGI web server.
+
+Commands
+========
+
+Commands are submitted with HTTP GET requests (for commands that
+primarily return data) or PUT (for commands that affect cluster state).
+HEAD and OPTIONS are also supported.  Standard HTTP status codes
+are returned.
+
+For commands that return bulk data, the request can include
+Accept: application/json or Accept: application/xml to select the
+desired structured output, or you may use a .json or .xml addition
+to the requested PATH.  Parameters are supplied as query parameters
+in the request; for parameters that take more than one value, repeat
+the key=val construct.  For instance, to remove OSDs 2 and 3,
+send a PUT request to ``osd/rm?ids=2&ids=3``.
+
+Discovery
+=========
+
+Human-readable discovery of supported commands and parameters, along
+with a small description of each command, is provided when the requested
+path is incomplete/partially matching.  Requesting / will redirect to
+the value of  **restapi base url**, and that path will give a full list
+of all known commands.  The command set is very similar to the commands
+supported by the **ceph** tool.
+
+
+Availability
+============
+
+**ceph-rest-api** is part of the Ceph distributed file system. Please refer to the Ceph documentation at
+http://ceph.com/docs for more information.
+
+
+See also
+========
+
+:doc:`ceph <ceph>`\(8)
diff --git a/doc/rados/man/index.rst b/doc/rados/man/index.rst
index 82645287f51..d7bbe9d3acb 100644
--- a/doc/rados/man/index.rst
+++ b/doc/rados/man/index.rst
@@ -6,6 +6,7 @@
    :maxdepth: 1
 
    ../../man/8/ceph.rst
+   ../../man/8/ceph-rest-api.rst
    ../../man/8/ceph-authtool.rst
    ../../man/8/ceph-clsinfo.rst
    ../../man/8/ceph-conf.rst
@@ -19,4 +20,4 @@
    ../../man/8/librados-config.rst
    ../../man/8/monmaptool.rst
    ../../man/8/osdmaptool.rst
-   ../../man/8/rados.rst
\ No newline at end of file
+   ../../man/8/rados.rst
diff --git a/man/ceph-rest-api.8 b/man/ceph-rest-api.8
new file mode 100644
index 00000000000..77a9ef29c38
--- /dev/null
+++ b/man/ceph-rest-api.8
@@ -0,0 +1,122 @@
+.TH "CEPH-REST-API" "8" "July 10, 2013" "dev" "Ceph"
+.SH NAME
+ceph-rest-api \- ceph RESTlike administration server
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.\" Man page generated from reStructuredText.
+.
+.SH SYNOPSIS
+.nf
+\fBceph\-rest\-api\fP [ \-c \fIconffile\fP ] [ \-n \fIname\fP ... ]
+.fi
+.sp
+.SH DESCRIPTION
+.sp
+\fBceph\-rest\-api\fP is a WSGI application that can run as a
+standalone web service or run under a web server that supports
+WSGI.  It provides much of the functionality of the \fBceph\fP
+command\-line tool through an HTTP\-accessible interface.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \-c/\-\-conf *conffile*
+names the ceph.conf file to use for configuration.  If \-c
+is not specified, the configuration file is searched for in
+this order:
+.INDENT 7.0
+.IP \(bu 2
+$CEPH_CONF
+.IP \(bu 2
+/etc/ceph/ceph.conf
+.IP \(bu 2
+~/.ceph/ceph.conf
+.IP \(bu 2
+ceph.conf (in the current directory)
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.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.
+.UNINDENT
+.SH CONFIGURATION PARAMETERS
+.sp
+Supported configuration parameters include:
+.INDENT 0.0
+.IP \(bu 2
+\fBrestapi keyring\fP the keyring file holding the key for \(aqclientname\(aq
+.IP \(bu 2
+\fBrestapi public addr\fP ip:port to listen on (default 0.0.0.0:5000)
+.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)
+.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.
+.SH COMMANDS
+.sp
+Commands are submitted with HTTP GET requests (for commands that
+primarily return data) or PUT (for commands that affect cluster state).
+HEAD and OPTIONS are also supported.  Standard HTTP status codes
+are returned.
+.sp
+For commands that return bulk data, the request can include
+Accept: application/json or Accept: application/xml to select the
+desired structured output, or you may use a .json or .xml addition
+to the requested PATH.  Parameters are supplied as query parameters
+in the request; for parameters that take more than one value, repeat
+the key=val construct.  For instance, to remove OSDs 2 and 3,
+send a PUT request to \fBosd/rm?ids=2&ids=3\fP.
+.SH DISCOVERY
+.sp
+Human\-readable discovery of supported commands and parameters, along
+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.
+.SH AVAILABILITY
+.sp
+\fBceph\-rest\-api\fP is part of the Ceph distributed file system. Please refer to the Ceph documentation at
+\fI\%http://ceph.com/docs\fP for more information.
+.SH SEE ALSO
+.sp
+\fBceph\fP(8)
+.SH COPYRIGHT
+2010-2013, Inktank Storage, Inc. and contributors. Licensed under Creative Commons BY-SA
+.\" Generated by docutils manpage writer.
+.