ceph/man/ceph-rest-api.8

.TH "CEPH-REST-API" "8" "July 12, 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 default depends on the state of the \-\-cluster option
(default \(aqceph\(aq; see below).  The configuration file is searched
for in this order:
.INDENT 7.0
.IP \(bu 2
$CEPH_CONF
.IP \(bu 2
/etc/ceph/${cluster}.conf
.IP \(bu 2
~/.ceph/${cluster}.conf
.IP \(bu 2
${cluster}.conf (in the current directory)
.UNINDENT
.sp
so you can also pass this option in the environment as CEPH_CONF.
.UNINDENT
.INDENT 0.0
.TP
.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*
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.
.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
.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 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:
.INDENT 0.0
.IP \(bu 2
CEPH_CONF holds \-c/\-\-conf
.IP \(bu 2
CEPH_CLUSTER_NAME holds \-\-cluster
.IP \(bu 2
CEPH_NAME holds \-n/\-\-name
.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.
.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.
.