doc: document the setup of restful and dashboard plugins

Fixes: http://tracker.ceph.com/issues/20239
Signed-off-by: Kefu Chai <kchai@redhat.com>

diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst
new file mode 100644 (file)
index 0000000..7f837f2
--- /dev/null
+++ b/doc/mgr/dashboard.rst
@@ -0,0 +1,15 @@
+dashboard plugin
+================
+
+Dashboard plugin visualizes the statistics of the cluster using a web server
+hosted by ``ceph-mgr``. Like most web applications, dashboard binds to a host
+name and port. Since each ``ceph-mgr`` hosts its own instance of dashboard, we
+need to configure them separately. The hostname and port are stored using the
+configuration key facility. So we can configure them like::
+
+  ceph config-key put mgr/dashboard/$name/server_addr $IP
+  ceph config-key put mgr/dashboard/$name/server_port $PORT
+
+where ``$name`` is the ID of the ceph-mgr who is hosting this dashboard web app.
+If they are not configured, the web app will be bound to ``127.0.0.1:7000``.
+

diff --git a/doc/mgr/index.rst b/doc/mgr/index.rst
index 2f88aa295bc7ccd743c6eb9efdd782593b3f9a5f..38bdec15396f714f8b56789cc6c2e8fc7d79c4f3 100644 (file)
--- a/doc/mgr/index.rst
+++ b/doc/mgr/index.rst
@@ -26,5 +26,7 @@ sensible.
     :maxdepth: 1
 
     Installation and Configuration <administrator>
+    Dashboard <dashboard>
+    RESTful <restful>
     Writing plugins <plugins>
 

diff --git a/doc/mgr/restful.rst b/doc/mgr/restful.rst
new file mode 100644 (file)
index 0000000..846c988
--- /dev/null
+++ b/doc/mgr/restful.rst
@@ -0,0 +1,25 @@
+restful plugin
+==============
+
+RESTful plugin offers the REST API access to the status of the cluster. RESTful
+plugin enables you to secure the API endpoints via SSL. If you don't have a
+security certificate and key already, you need to create them first::
+
+  openssl req -new -nodes -x509 \
+    -subj "/O=IT/CN=ceph-mgr-restful" \
+    -days 3650 -keyout $PKEY -out $CERT -extensions v3_ca
+
+where ``$PKEY`` and ``$CERT`` are the paths to the private key and the
+certificate. And then you need to import the keystore to the cluster using the
+configuration key facility, so RESTful plugin can read them at startup::
+
+  ceph config-key put mgr/restful/$name/crt -i $CERT
+  ceph config-key put mgr/restful/$name/key -i $PKEY
+
+Also, like other web applications, RESTful plugin is bound to the a hostname and
+a port::
+
+  ceph config-key put mgr/restful/$name/server_addr $IP
+  ceph config-key put mgr/restful/$name/server_port $PORT
+
+If not specified, the plugin uses ``127.0.0.1:8003`` by default.