1CEPH-REST-API(8) Ceph CEPH-REST-API(8)
2
6 ceph-rest-api - ceph RESTlike administration server
7
9 ceph-rest-api [ -c conffile ] [--cluster clustername ] [ -n name ] [-i id ]
10
13 ceph-rest-api is a WSGI application that can run as a standalone web
14 service or run under a web server that supports WSGI. It provides much
15 of the functionality of the ceph command-line tool through an
16 HTTP-accessible interface.
17
19 -c/--conf conffile
20 names the ceph.conf file to use for configuration. If -c is not
21 specified, the default depends on the state of the --cluster
22 option (default 'ceph'; see below). The configuration file is
23 searched for in this order:
24 · $CEPH_CONF
26 · /etc/ceph/${cluster}.conf
28 · ~/.ceph/${cluster}.conf
30 · ${cluster}.conf (in the current directory)
32 so you can also pass this option in the environment as
34 CEPH_CONF.
35 --cluster clustername
37 set clustername for use in the $cluster metavariable, for locat‐
38 ing the ceph.conf file. The default is 'ceph'.
39 -n/--name name
41 specifies the client 'name', which is used to find the
42 client-specific configuration options in the config file, and
43 also is the name used for authentication when connecting to the
44 cluster (the entity name appearing in 'ceph auth ls' output, for
45 example). The default is 'client.restapi'.
46 -i/--id id
48 specifies the client 'id', which will form the clientname as
49 'client.<id>' if clientname is not set. If -n/-name is set,
50 that takes precedence.
51 Also, global Ceph options are supported.
53
55 Supported configuration parameters include:
56 · keyring the keyring file holding the key for 'clientname'
58 · public addr ip:port to listen on (default 0.0.0.0:5000)
60 · log file (usual Ceph default)
62 · restapi base url the base URL to answer requests on (default
64 /api/v0.1)
65 · restapi log level critical, error, warning, info, debug (default
67 warning)
68 Configuration parameters are searched in the standard order: first in
70 the section named '<clientname>', then 'client', then 'global'.
71 <clientname> is either supplied by -n/--name, "client.<id>" where <id>
73 is supplied by -i/--id, or 'client.restapi' if neither option is
74 present.
75 A single-threaded server will run on public addr if the ceph-rest-api
77 executed directly; otherwise, configuration is specified by the enclos‐
78 ing WSGI web server.
79
81 Commands are submitted with HTTP GET requests (for commands that pri‐
82 marily return data) or PUT (for commands that affect cluster state).
83 HEAD and OPTIONS are also supported. Standard HTTP status codes are
84 returned.
85 For commands that return bulk data, the request can include Accept:
87 application/json or Accept: application/xml to select the desired
88 structured output, or you may use a .json or .xml addition to the
89 requested PATH. Parameters are supplied as query parameters in the
90 request; for parameters that take more than one value, repeat the
91 key=val construct. For instance, to remove OSDs 2 and 3, send a PUT
92 request to osd/rm?ids=2&ids=3.
93
95 Human-readable discovery of supported commands and parameters, along
96 with a small description of each command, is provided when the
97 requested path is incomplete/partially matching. Requesting / will re‐
98 direct to the value of restapi base url, and that path will give a
99 full list of all known commands. For example, requesting api/vX.X/mon
100 will return the list of API calls for monitors - api/vX.X/osd will
101 return the list of API calls for OSD and so on.
102 The command set is very similar to the commands supported by the ceph
104 tool. One notable exception is that the ceph pg <pgid> <command> style
105 of commands is supported here as tell/<pgid>/command?args.
106
108 When deploying as WSGI application (say, with Apache/mod_wsgi, or
109 nginx/uwsgi, or gunicorn, etc.), use the ceph_rest_api.py module
110 (ceph-rest-api is a thin layer around this module). The standalone web
111 server is of course not used, so address/port configuration is done in
112 the WSGI server. Use a python .wsgi module or the equivalent to call
113 app = generate_app(conf, cluster, clientname, clientid, args) where:
114 · conf is as -c/--conf above
116 · cluster is as --cluster above
118 · clientname, -n/--name
120 · clientid, -i/--id, and
122 · args are any other generic Ceph arguments
124 When app is returned, it will have attributes 'ceph_addr' and
126 'ceph_port' set to what the address and port are in the Ceph configura‐
127 tion; those may be used for the server, or ignored.
128 Any errors reading configuration or connecting to the cluster cause an
130 exception to be raised; see your WSGI server documentation for how to
131 see those messages in case of problem.
132
134 ceph-rest-api is part of Ceph, a massively scalable, open-source, dis‐
135 tributed storage system. Please refer to the Ceph documentation at
136 http://ceph.com/docs for more information.
137
139 ceph(8)
140
142 2010-2014, Inktank Storage, Inc. and contributors. Licensed under Cre‐
143 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
144dev Apr 14, 2019 CEPH-REST-API(8)