ceph/doc/mgr/restful.rst

   1 restful plugin
   2 ==============
   3
   4 RESTful plugin offers the REST API access to the status of the cluster
   5 over an SSL-secured connection.
   6
   7 Enabling
   8 --------
   9
  10 The *restful* module is enabled with::
  11
  12   ceph mgr module enable restful
  13
  14 You will also need to configure an SSL certificate below before the
  15 API endpoint is available.  By default the module will accept HTTPS
  16 requests on port ``8003`` on all IPv4 and IPv6 addresses on the host.
  17
  18 Securing
  19 --------
  20
  21 All connections to *restful* are secured with SSL.  You can generate a
  22 self-signed certificate with the command::
  23
  24   ceph restful create-self-signed-cert
  25
  26 Note that with a self-signed certificate most clients will need a flag
  27 to allow a connection and/or suppress warning messages.  For example,
  28 if the ``ceph-mgr`` daemon is on the same host,::
  29
  30   curl -k https://localhost:8003/
  31
  32 To properly secure a deployment, a certificate that is signed by the
  33 organization's certificate authority should be used.  For example, a key pair
  34 can be generated with a command similar to::
  35
  36   openssl req -new -nodes -x509 \
  37     -subj "/O=IT/CN=ceph-mgr-restful" \
  38     -days 3650 -keyout restful.key -out restful.crt -extensions v3_ca
  39
  40 The ``restful.crt`` should then be signed by your organization's CA
  41 (certificate authority).  Once that is done, you can set it with::
  42
  43   ceph config-key set mgr/restful/$name/crt -i restful.crt
  44   ceph config-key set mgr/restful/$name/key -i restful.key
  45
  46 where ``$name`` is the name of the ``ceph-mgr`` instance (usually the
  47 hostname). If all manager instances are to share the same certificate,
  48 you can leave off the ``$name`` portion::
  49
  50   ceph config-key set mgr/restful/crt -i restful.crt
  51   ceph config-key set mgr/restful/key -i restful.key
  52
  53
  54 Configuring IP and port
  55 -----------------------
  56
  57 Like any other RESTful API endpoint, *restful* binds to an IP and
  58 port.  By default, the currently active ``ceph-mgr`` daemon will bind
  59 to port 8003 and any available IPv4 or IPv6 address on the host.
  60
  61 Since each ``ceph-mgr`` hosts its own instance of *restful*, it may
  62 also be necessary to configure them separately. The IP and port
  63 can be changed via the configuration key facility::
  64
  65   ceph config-key set mgr/restful/$name/server_addr $IP
  66   ceph config-key set mgr/restful/$name/server_port $PORT
  67
  68 where ``$name`` is the ID of the ceph-mgr daemon (usually the hostname).
  69
  70 These settings can also be configured cluster-wide and not manager
  71 specific.  For example,::
  72
  73   ceph config-key set mgr/restful/server_addr $IP
  74   ceph config-key set mgr/restful/server_port $PORT
  75
  76 If the port is not configured, *restful* will bind to port ``8003``.
  77 If the address it not configured, the *restful* will bind to ``::``,
  78 which corresponds to all available IPv4 and IPv6 addresses.
  79
  80 Load balancer
  81 -------------
  82
  83 Please note that *restful* will *only* start on the manager which
  84 is active at that moment. Query the Ceph cluster status to see which
  85 manager is active (e.g., ``ceph mgr dump``).  In order to make the
  86 API available via a consistent URL regardless of which manager
  87 daemon is currently active, you may want to set up a load balancer
  88 front-end to direct traffic to whichever manager endpoint is
  89 available.
  90
  91 Available methods
  92 -----------------
  93
  94 You can navigate to the ``/doc`` endpoint for full list of available
  95 endpoints and HTTP methods implemented for each endpoint.
  96
  97 For example, if you want to use the PATCH method of the ``/osd/<id>``
  98 endpoint to set the state ``up`` of the OSD id ``1``, you can use the
  99 following curl command::
 100
 101   echo -En '{"up": true}' | curl --request PATCH --data @- --silent --insecure --user <user> 'https://<ceph-mgr>:<port>/osd/1'
 102
 103 or you can use python to do so::
 104
 105   $ python
 106   >> import requests
 107   >> result = requests.patch(
 108          'https://<ceph-mgr>:<port>/osd/1',
 109          json={"up": True},
 110          auth=("<user>", "<password>")
 111      )
 112   >> print result.json()
 113
 114 Some of the other endpoints implemented in the *restful* module include
 115
 116 * ``/config/cluster``: **GET**
 117 * ``/config/osd``: **GET**, **PATCH**
 118 * ``/crush/rule``: **GET**
 119 * ``/mon``: **GET**
 120 * ``/osd``: **GET**
 121 * ``/pool``: **GET**, **POST**
 122 * ``/pool/<arg>``: **DELETE**, **GET**, **PATCH**
 123 * ``/request``: **DELETE**, **GET**, **POST**
 124 * ``/request/<arg>``: **DELETE**, **GET**
 125 * ``/server``: **GET**
 126
 127 The ``/request`` endpoint
 128 -------------------------
 129
 130 You can use the ``/request`` endpoint to poll the state of a request
 131 you scheduled with any **DELETE**, **POST** or **PATCH** method. These
 132 methods are by default asynchronous since it may take longer for them
 133 to finish execution. You can modify this behaviour by appending
 134 ``?wait=1`` to the request url. The returned request will then always
 135 be completed.
 136
 137 The **POST** method of the ``/request`` method provides a passthrough
 138 for the ceph mon commands as defined in ``src/mon/MonCommands.h``.
 139 Let's consider the following command::
 140
 141   COMMAND("osd ls " \
 142           "name=epoch,type=CephInt,range=0,req=false", \
 143           "show all OSD ids", "osd", "r", "cli,rest")
 144
 145 The **prefix** is **osd ls**. The optional argument's name is **epoch**
 146 and it is of type ``CephInt``, i.e. ``integer``. This means that you
 147 need to do the following **POST** request to schedule the command::
 148
 149   $ python
 150   >> import requests
 151   >> result = requests.post(
 152          'https://<ceph-mgr>:<port>/request',
 153          json={'prefix': 'osd ls', 'epoch': 0},
 154          auth=("<user>", "<password>")
 155      )
 156   >> print result.json()