src/ceph/doc/man/8/ceph-rest-api.rst

   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
  50     to the cluster (the entity name appearing in 'ceph auth ls' output,
  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)