mirror of
https://github.com/ceph/ceph
synced 2024-12-27 22:13:28 +00:00
cc10988850
To deploy ceph-rest-api within a WSGI server (apache/mod_wsgi, nginx/uwsgi, etc.), there needs to be an importable (.py) module that performs all init/config when imported. ceph-rest-api was close, but it needs to be named properly, and there's no argument passing, so it needs to get args from a fixed file or the env. Separate most of ceph-rest-api into pybind/ceph_rest_api.py, and make its arguments come from the environment, and init errors be ImportError exceptions. Recase ceph-rest-api as a thin layer that does the usual setup and arg parsing, and then sets args into the environment and imports ceph_rest_api.py, catching exceptions and reporting errors. This allows standalone execution as usual. ceph-rest-api grabs a few module globals (addr/port and the flask.app) to use after it imports. Accept cluster name, and do the ceph.conf search using cluster name in the appropriate places in the searched-for files. Also ceph_rest_api.py gets a little cleanup (fewer global variables, cleaner conf file search algorithm, better error reporting on conf load) Also: doc updates, packaging updates to include ceph_rest_api.py Signed-off-by: Dan Mick <dan.mick@inktank.com>
158 lines
5.2 KiB
Groff
158 lines
5.2 KiB
Groff
.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.
|
|
.
|