]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | :orphan: |
2 | ||
3 | ===================================================== | |
4 | ceph-rest-api -- ceph RESTlike administration server | |
5 | ===================================================== | |
6 | ||
7 | .. program:: ceph-rest-api | |
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | | **ceph-rest-api** [ -c *conffile* ] [--cluster *clustername* ] [ -n *name* ] [-i *id* ] | |
13 | ||
14 | ||
15 | Description | |
16 | =========== | |
17 | ||
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. | |
22 | ||
23 | Options | |
24 | ======= | |
25 | ||
26 | .. option:: -c/--conf conffile | |
27 | ||
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 | |
31 | for in this order: | |
32 | ||
33 | * $CEPH_CONF | |
34 | * /etc/ceph/${cluster}.conf | |
35 | * ~/.ceph/${cluster}.conf | |
36 | * ${cluster}.conf (in the current directory) | |
37 | ||
38 | so you can also pass this option in the environment as CEPH_CONF. | |
39 | ||
40 | .. option:: --cluster clustername | |
41 | ||
42 | set *clustername* for use in the $cluster metavariable, for | |
43 | locating the ceph.conf file. The default is 'ceph'. | |
44 | ||
45 | .. option:: -n/--name name | |
46 | ||
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 | |
c07f9fc5 | 50 | to the cluster (the entity name appearing in 'ceph auth ls' output, |
7c673cae FG |
51 | for example). The default is 'client.restapi'. |
52 | ||
53 | .. option:: -i/--id id | |
54 | ||
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. | |
58 | ||
59 | Also, global Ceph options are supported. | |
60 | ||
61 | ||
62 | Configuration parameters | |
63 | ======================== | |
64 | ||
65 | Supported configuration parameters include: | |
66 | ||
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) | |
72 | ||
73 | Configuration parameters are searched in the standard order: | |
74 | first in the section named '<clientname>', then 'client', then 'global'. | |
75 | ||
76 | <clientname> is either supplied by -n/--name, "client.<id>" where | |
77 | <id> is supplied by -i/--id, or 'client.restapi' if neither option | |
78 | is present. | |
79 | ||
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 | |
82 | WSGI web server. | |
83 | ||
84 | Commands | |
85 | ======== | |
86 | ||
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 | |
90 | are returned. | |
91 | ||
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``. | |
99 | ||
100 | Discovery | |
101 | ========= | |
102 | ||
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. | |
110 | ||
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``. | |
115 | ||
116 | Deployment as WSGI application | |
117 | ============================== | |
118 | ||
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: | |
125 | ||
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 | |
131 | ||
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. | |
135 | ||
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. | |
139 | ||
140 | Availability | |
141 | ============ | |
142 | ||
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. | |
145 | ||
146 | ||
147 | See also | |
148 | ======== | |
149 | ||
150 | :doc:`ceph <ceph>`\(8) |