src/ceph/doc/start/quick-rgw.rst

   1 ===============================
   2 Ceph Object Gateway Quick Start
   3 ===============================
   4
   5 As of `firefly` (v0.80), Ceph Storage dramatically simplifies installing and
   6 configuring a Ceph Object Gateway. The Gateway daemon embeds Civetweb, so you
   7 do not have to install a web server or configure FastCGI. Additionally,
   8 ``ceph-deploy`` can install the gateway package, generate a key, configure a
   9 data directory and create a gateway instance for you.
  10
  11 .. tip:: Civetweb uses port ``7480`` by default. You must either open port
  12    ``7480``, or set the port to a preferred port (e.g., port ``80``) in your Ceph
  13    configuration file.
  14
  15 To start a Ceph Object Gateway, follow the steps below:
  16
  17 Installing Ceph Object Gateway
  18 ==============================
  19
  20 #. Execute the pre-installation steps on your ``client-node``. If you intend to
  21    use Civetweb's default port ``7480``, you must open it using either
  22    ``firewall-cmd`` or ``iptables``. See `Preflight Checklist`_ for more
  23    information.
  24
  25 #. From the working directory of your administration server, install the Ceph
  26    Object Gateway package on the ``client-node`` node. For example::
  27
  28     ceph-deploy install --rgw <client-node> [<client-node> ...]
  29
  30 Creating the Ceph Object Gateway Instance
  31 =========================================
  32
  33 From the working directory of your administration server, create an instance of
  34 the Ceph Object Gateway on the ``client-node``. For example::
  35
  36     ceph-deploy rgw create <client-node>
  37
  38 Once the gateway is running, you should be able to access it on port ``7480``.
  39 (e.g., ``http://client-node:7480``).
  40
  41 Configuring the Ceph Object Gateway Instance
  42 ============================================
  43
  44 #. To change the default port (e.g,. to port ``80``), modify your Ceph
  45    configuration file. Add a section entitled ``[client.rgw.<client-node>]``,
  46    replacing ``<client-node>`` with the short node name of your Ceph client
  47    node (i.e., ``hostname -s``). For example, if your node name is
  48    ``client-node``, add a section like this after the ``[global]`` section::
  49
  50     [client.rgw.client-node]
  51     rgw_frontends = "civetweb port=80"
  52
  53    .. note:: Ensure that you leave no whitespace between ``port=<port-number>``
  54       in the ``rgw_frontends`` key/value pair.
  55
  56    .. important:: If you intend to use port 80, make sure that the Apache
  57       server is not running otherwise it will conflict with Civetweb. We recommend
  58       to remove Apache in this case.
  59
  60 #. To make the new port setting take effect, restart the Ceph Object Gateway.
  61    On Red Hat Enterprise Linux 7 and Fedora, run the following command::
  62
  63     sudo systemctl restart ceph-radosgw.service
  64
  65    On Red Hat Enterprise Linux 6 and Ubuntu, run the following command::
  66
  67     sudo service radosgw restart id=rgw.<short-hostname>
  68
  69 #. Finally, check to ensure that the port you selected is open on the node's
  70    firewall (e.g., port ``80``). If it is not open, add the port and reload the
  71    firewall configuration. For example::
  72
  73     sudo firewall-cmd --list-all
  74     sudo firewall-cmd --zone=public --add-port 80/tcp --permanent
  75     sudo firewall-cmd --reload
  76
  77    See `Preflight Checklist`_ for more information on configuring firewall with
  78    ``firewall-cmd`` or ``iptables``.
  79
  80    You should be able to make an unauthenticated request, and receive a
  81    response. For example, a request with no parameters like this::
  82
  83     http://<client-node>:80
  84
  85    Should result in a response like this::
  86
  87     <?xml version="1.0" encoding="UTF-8"?>
  88     <ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  89       <Owner>
  90         <ID>anonymous</ID>
  91         <DisplayName></DisplayName>
  92       </Owner>
  93         <Buckets>
  94       </Buckets>
  95     </ListAllMyBucketsResult>
  96
  97 See the `Configuring Ceph Object Gateway`_ guide for additional administration
  98 and API details.
  99
 100 .. _Configuring Ceph Object Gateway: ../../radosgw/config-fcgi
 101 .. _Preflight Checklist: ../quick-start-preflight