.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.\(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\(aq, then \(aqclient\(aq, then \(aqglobal\(aq. .sp is either supplied by \-n/\-\-name, "client." where 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 \fP style of commands is supported here as \fBtell//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. .