X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=src%2Fceph%2Fdoc%2Fman%2F8%2Fceph-rest-api.rst;fp=src%2Fceph%2Fdoc%2Fman%2F8%2Fceph-rest-api.rst;h=9864a9b6f566e7ef771400c72bd496c8c47a1b96;hb=812ff6ca9fcd3e629e49d4328905f33eee8ca3f5;hp=0000000000000000000000000000000000000000;hpb=15280273faafb77777eab341909a3f495cf248d9;p=stor4nfv.git diff --git a/src/ceph/doc/man/8/ceph-rest-api.rst b/src/ceph/doc/man/8/ceph-rest-api.rst new file mode 100644 index 0000000..9864a9b --- /dev/null +++ b/src/ceph/doc/man/8/ceph-rest-api.rst @@ -0,0 +1,150 @@ +:orphan: + +===================================================== + ceph-rest-api -- ceph RESTlike administration server +===================================================== + +.. program:: ceph-rest-api + +Synopsis +======== + +| **ceph-rest-api** [ -c *conffile* ] [--cluster *clustername* ] [ -n *name* ] [-i *id* ] + + +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 default depends on the state of the --cluster option + (default 'ceph'; see below). The configuration file is searched + for in this order: + + * $CEPH_CONF + * /etc/ceph/${cluster}.conf + * ~/.ceph/${cluster}.conf + * ${cluster}.conf (in the current directory) + + so you can also pass this option in the environment as CEPH_CONF. + +.. option:: --cluster clustername + + set *clustername* for use in the $cluster metavariable, for + locating the ceph.conf file. The default is 'ceph'. + +.. 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 ls' output, + for example). The default is 'client.restapi'. + +.. option:: -i/--id id + + specifies the client 'id', which will form the clientname + as 'client.' if clientname is not set. If -n/-name is + set, that takes precedence. + + Also, global Ceph options are supported. + + +Configuration parameters +======================== + +Supported configuration parameters include: + +* **keyring** the keyring file holding the key for 'clientname' +* **public addr** ip:port to listen on (default 0.0.0.0:5000) +* **log file** (usual Ceph default) +* **restapi base url** the base URL to answer requests on (default /api/v0.1) +* **restapi log level** critical, error, warning, info, debug (default warning) + +Configuration parameters are searched in the standard order: +first in the section named '', then 'client', then 'global'. + + is either supplied by -n/--name, "client." where + is supplied by -i/--id, or 'client.restapi' if neither option +is present. + +A single-threaded server will run on **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. +For example, requesting ``api/vX.X/mon`` will return the list of API calls for +monitors - ``api/vX.X/osd`` will return the list of API calls for OSD and so on. + +The command set is very similar to the commands +supported by the **ceph** tool. One notable exception is that the +``ceph pg `` style of commands is supported here +as ``tell//command?args``. + +Deployment as WSGI application +============================== + +When deploying as WSGI application (say, with Apache/mod_wsgi, +or nginx/uwsgi, or gunicorn, etc.), use the ``ceph_rest_api.py`` module +(``ceph-rest-api`` 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 +``app = generate_app(conf, cluster, clientname, clientid, args)`` where: + +* conf is as -c/--conf above +* cluster is as --cluster above +* clientname, -n/--name +* clientid, -i/--id, and +* args are any other generic Ceph arguments + +When app is returned, it will have attributes 'ceph_addr' and 'ceph_port' +set to what the address and port are in the Ceph configuration; +those may be used for the server, or ignored. + +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. + +Availability +============ + +**ceph-rest-api** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to the Ceph documentation at +http://ceph.com/docs for more information. + + +See also +======== + +:doc:`ceph `\(8)