3 =====================================================
4 ceph-rest-api -- ceph RESTlike administration server
5 =====================================================
7 .. program:: ceph-rest-api
12 | **ceph-rest-api** [ -c *conffile* ] [--cluster *clustername* ] [ -n *name* ] [-i *id* ]
18 **ceph-rest-api** is a WSGI application that can run as a
19 standalone web service or run under a web server that supports
20 WSGI. It provides much of the functionality of the **ceph**
21 command-line tool through an HTTP-accessible interface.
26 .. option:: -c/--conf conffile
28 names the ceph.conf file to use for configuration. If -c is not
29 specified, the default depends on the state of the --cluster option
30 (default 'ceph'; see below). The configuration file is searched
34 * /etc/ceph/${cluster}.conf
35 * ~/.ceph/${cluster}.conf
36 * ${cluster}.conf (in the current directory)
38 so you can also pass this option in the environment as CEPH_CONF.
40 .. option:: --cluster clustername
42 set *clustername* for use in the $cluster metavariable, for
43 locating the ceph.conf file. The default is 'ceph'.
45 .. option:: -n/--name name
47 specifies the client 'name', which is used to find the
48 client-specific configuration options in the config file, and
49 also is the name used for authentication when connecting
50 to the cluster (the entity name appearing in 'ceph auth ls' output,
51 for example). The default is 'client.restapi'.
53 .. option:: -i/--id id
55 specifies the client 'id', which will form the clientname
56 as 'client.<id>' if clientname is not set. If -n/-name is
57 set, that takes precedence.
59 Also, global Ceph options are supported.
62 Configuration parameters
63 ========================
65 Supported configuration parameters include:
67 * **keyring** the keyring file holding the key for 'clientname'
68 * **public addr** ip:port to listen on (default 0.0.0.0:5000)
69 * **log file** (usual Ceph default)
70 * **restapi base url** the base URL to answer requests on (default /api/v0.1)
71 * **restapi log level** critical, error, warning, info, debug (default warning)
73 Configuration parameters are searched in the standard order:
74 first in the section named '<clientname>', then 'client', then 'global'.
76 <clientname> is either supplied by -n/--name, "client.<id>" where
77 <id> is supplied by -i/--id, or 'client.restapi' if neither option
80 A single-threaded server will run on **public addr** if the ceph-rest-api
81 executed directly; otherwise, configuration is specified by the enclosing
87 Commands are submitted with HTTP GET requests (for commands that
88 primarily return data) or PUT (for commands that affect cluster state).
89 HEAD and OPTIONS are also supported. Standard HTTP status codes
92 For commands that return bulk data, the request can include
93 Accept: application/json or Accept: application/xml to select the
94 desired structured output, or you may use a .json or .xml addition
95 to the requested PATH. Parameters are supplied as query parameters
96 in the request; for parameters that take more than one value, repeat
97 the key=val construct. For instance, to remove OSDs 2 and 3,
98 send a PUT request to ``osd/rm?ids=2&ids=3``.
103 Human-readable discovery of supported commands and parameters, along
104 with a small description of each command, is provided when the requested
105 path is incomplete/partially matching. Requesting / will redirect to
106 the value of **restapi base url**, and that path will give a full list
107 of all known commands.
108 For example, requesting ``api/vX.X/mon`` will return the list of API calls for
109 monitors - ``api/vX.X/osd`` will return the list of API calls for OSD and so on.
111 The command set is very similar to the commands
112 supported by the **ceph** tool. One notable exception is that the
113 ``ceph pg <pgid> <command>`` style of commands is supported here
114 as ``tell/<pgid>/command?args``.
116 Deployment as WSGI application
117 ==============================
119 When deploying as WSGI application (say, with Apache/mod_wsgi,
120 or nginx/uwsgi, or gunicorn, etc.), use the ``ceph_rest_api.py`` module
121 (``ceph-rest-api`` is a thin layer around this module). The standalone web
122 server is of course not used, so address/port configuration is done in
123 the WSGI server. Use a python .wsgi module or the equivalent to call
124 ``app = generate_app(conf, cluster, clientname, clientid, args)`` where:
126 * conf is as -c/--conf above
127 * cluster is as --cluster above
128 * clientname, -n/--name
129 * clientid, -i/--id, and
130 * args are any other generic Ceph arguments
132 When app is returned, it will have attributes 'ceph_addr' and 'ceph_port'
133 set to what the address and port are in the Ceph configuration;
134 those may be used for the server, or ignored.
136 Any errors reading configuration or connecting to the cluster cause an
137 exception to be raised; see your WSGI server documentation for how to
138 see those messages in case of problem.
143 **ceph-rest-api** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to the Ceph documentation at
144 http://ceph.com/docs for more information.
150 :doc:`ceph <ceph>`\(8)