mirror of
https://github.com/ceph/ceph
synced 2024-12-16 08:26:25 +00:00
8af47755af
ceph-rest-api: * create app from wrapper by calling generate_app() * pass args to generate_app() (early parsed in wrapper) * parse -i/--id here as well * set addr:port on returned app object * handle only EnvironmentError exceptions; let others spew traceback * turn off debug when running singlethreaded server ceph_rest_api.py: * put glob.* on app.ceph_* instead; pass around app in init code * drop conf parsing (let librados do its job) Documentation updated to match. Signed-off-by: Dan Mick <dan.mick@inktank.com> Reviewed-by: Sage Weil <sage@inktank.com>
178 lines
6.0 KiB
Groff
178 lines
6.0 KiB
Groff
.TH "CEPH-REST-API" "8" "July 26, 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 ] [\-\-cluster \fIclustername\fP ] [ \-n \fIname\fP ] [\-i \fIid\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.
|
|
.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
|
|
.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
|
|
\fBkeyring\fP the keyring file holding the key for \(aqclientname\(aq
|
|
.IP \(bu 2
|
|
\fBpublic addr\fP ip:port to listen on (default 0.0.0.0:5000)
|
|
.IP \(bu 2
|
|
\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 (default warning)
|
|
.UNINDENT
|
|
.sp
|
|
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
|
|
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. 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. 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
|
|
conf is as \-c/\-\-conf above
|
|
.IP \(bu 2
|
|
cluster is as \-\-cluster above
|
|
.IP \(bu 2
|
|
clientname, \-n/\-\-name
|
|
.IP \(bu 2
|
|
clientid, \-i/\-\-id, and
|
|
.IP \(bu 2
|
|
args are any other generic Ceph arguments
|
|
.UNINDENT
|
|
.sp
|
|
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
|
|
\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.
|
|
.
|