initial code repo

[stor4nfv.git] / src / ceph / doc / start / quick-rgw.rst

diff --git a/src/ceph/doc/start/quick-rgw.rst b/src/ceph/doc/start/quick-rgw.rst
new file mode 100644 (file)
index 0000000..9f48ac2
--- /dev/null
+++ b/src/ceph/doc/start/quick-rgw.rst
@@ -0,0 +1,101 @@
+===============================
+Ceph Object Gateway Quick Start
+===============================
+
+As of `firefly` (v0.80), Ceph Storage dramatically simplifies installing and
+configuring a Ceph Object Gateway. The Gateway daemon embeds Civetweb, so you
+do not have to install a web server or configure FastCGI. Additionally,
+``ceph-deploy`` can install the gateway package, generate a key, configure a
+data directory and create a gateway instance for you.
+
+.. tip:: Civetweb uses port ``7480`` by default. You must either open port
+   ``7480``, or set the port to a preferred port (e.g., port ``80``) in your Ceph
+   configuration file.
+
+To start a Ceph Object Gateway, follow the steps below:
+
+Installing Ceph Object Gateway
+==============================
+
+#. Execute the pre-installation steps on your ``client-node``. If you intend to
+   use Civetweb's default port ``7480``, you must open it using either
+   ``firewall-cmd`` or ``iptables``. See `Preflight Checklist`_ for more
+   information.
+
+#. From the working directory of your administration server, install the Ceph
+   Object Gateway package on the ``client-node`` node. For example::
+
+    ceph-deploy install --rgw <client-node> [<client-node> ...]
+
+Creating the Ceph Object Gateway Instance
+=========================================
+
+From the working directory of your administration server, create an instance of
+the Ceph Object Gateway on the ``client-node``. For example::
+
+    ceph-deploy rgw create <client-node>
+
+Once the gateway is running, you should be able to access it on port ``7480``.
+(e.g., ``http://client-node:7480``).
+
+Configuring the Ceph Object Gateway Instance
+============================================
+
+#. To change the default port (e.g,. to port ``80``), modify your Ceph
+   configuration file. Add a section entitled ``[client.rgw.<client-node>]``,
+   replacing ``<client-node>`` with the short node name of your Ceph client
+   node (i.e., ``hostname -s``). For example, if your node name is
+   ``client-node``, add a section like this after the ``[global]`` section::
+
+    [client.rgw.client-node]
+    rgw_frontends = "civetweb port=80"
+
+   .. note:: Ensure that you leave no whitespace between ``port=<port-number>``
+      in the ``rgw_frontends`` key/value pair.
+
+   .. important:: If you intend to use port 80, make sure that the Apache
+      server is not running otherwise it will conflict with Civetweb. We recommend
+      to remove Apache in this case.
+
+#. To make the new port setting take effect, restart the Ceph Object Gateway.
+   On Red Hat Enterprise Linux 7 and Fedora, run the following command::
+
+    sudo systemctl restart ceph-radosgw.service
+
+   On Red Hat Enterprise Linux 6 and Ubuntu, run the following command::
+
+    sudo service radosgw restart id=rgw.<short-hostname>
+
+#. Finally, check to ensure that the port you selected is open on the node's
+   firewall (e.g., port ``80``). If it is not open, add the port and reload the
+   firewall configuration. For example::
+
+    sudo firewall-cmd --list-all
+    sudo firewall-cmd --zone=public --add-port 80/tcp --permanent
+    sudo firewall-cmd --reload
+
+   See `Preflight Checklist`_ for more information on configuring firewall with
+   ``firewall-cmd`` or ``iptables``.
+
+   You should be able to make an unauthenticated request, and receive a
+   response. For example, a request with no parameters like this::
+
+    http://<client-node>:80
+
+   Should result in a response like this::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+      <Owner>
+        <ID>anonymous</ID>
+        <DisplayName></DisplayName>
+      </Owner>
+       <Buckets>
+      </Buckets>
+    </ListAllMyBucketsResult>
+
+See the `Configuring Ceph Object Gateway`_ guide for additional administration
+and API details.
+
+.. _Configuring Ceph Object Gateway: ../../radosgw/config-fcgi
+.. _Preflight Checklist: ../quick-start-preflight