doc: explain how to configure Ceph for radosgw

* explain creating auth creds for radosgw
* explain Apache config for radosgw
* explain starting daemons for radosgw
* explain creating users for radosgw
* explain creating subusers for radosgw
* explain using swift client against radosgw
* Explain user:subuser to tenant:user mapping in Swift

Signed-off-by: Florian Haas <florian@hastexo.com>

diff --git a/doc/ops/radosgw.rst b/doc/ops/radosgw.rst
index 50fcf38e1bee8cfa0e67d1695760b0f24b792472..7c1c2f852b237e31bfeb838a99f6f6fff8463421 100644 (file)
--- a/doc/ops/radosgw.rst
+++ b/doc/ops/radosgw.rst
@@ -3,3 +3,226 @@
 =========================================
  Radosgw installation and administration
 =========================================
+
+RADOS Gateway (radosgw or rgw) provides a RESTful API to the object
+store. It interfaces with a web server via FastCGI, and with RADOS via
+libradospp.
+
+Configuring Ceph for RADOS Gateway
+----------------------------------
+
+In order for a host to act as a RADOS gateway, you must add a
+``[client.radosgw.<name>]`` section to your Ceph configuration file
+(typically ``/etc/ceph/ceph.conf``):
+
+::
+
+  [client.radosgw.gateway]
+    host = gateway
+    rgw socket path = /tmp/radosgw.sock
+
+``host`` is the name of the host running radosgw. ``keyring`` points
+to the keyring file for Cephx authentication. ``rgw socket path`` is
+the location of the UNIX socket which radosgw binds to.
+
+If your Ceph cluster has Cephx authentication enabled (highly
+recommended) you also need to add the following option to tell radosgw
+where it finds its authentication key:
+
+::
+
+  [client.radosgw.gateway]
+    keyring = /etc/ceph/keyring.radosgw.gateway
+
+
+Creating authentication credentials
+-----------------------------------
+
+To allow radosgw to sucessfully authenticate with the Ceph cluster,
+use the ``ceph-authtool`` command to create a key and set its
+capabilities:
+
+::
+
+  ceph-authtool -C -n client.radosgw.gateway \
+    --gen-key /etc/ceph/keyring.radosgw.gateway
+  ceph-authtool -n client.radosgw.gateway \
+    --cap mon 'allow r' --cap osd 'allow rwx' --cap mds 'allow' \
+    /etc/ceph/keyring.radosgw.gateway
+
+Finally, add this key to the authentication entries:
+
+::
+
+  ceph auth add client.radosgw.gateway \
+    --in-file=/etc/ceph/keyring.radosgw.gateway
+
+
+Configuring the web server for radosgw
+--------------------------------------
+
+
+The radosgw FastCGI wrapper
+---------------------------
+
+A wrapper script, customarily named ``radosgw.cgi`` needs to go into
+your preferred location -- typically your web server root directory.
+
+::
+
+  #!/bin/sh
+  exec /usr/bin/radosgw -c /etc/ceph/ceph.conf -n client.radosgw.gateway
+
+
+The ``-c`` option may be omitted if your Ceph configuration file
+resides in its default location ((``/etc/ceph/ceph.conf``)). The
+``-n`` option identifies the ``client`` section in the configuration
+file that radosgw should parse -- if omitted, this would default to
+``client.admin``.
+
+Configuring Apache for radosgw
+------------------------------
+
+The recommended way of deploying radosgw is with Apache and
+``mod_fastcgi``. Ensure that both ``mod_fastcgi`` and ``mod_rewrite``
+are enabled in your Apache configuration. Set the
+``FastCGIExternalServer`` option to point to the radosgw FastCGI
+wrapper.
+
+::
+
+  <IfModule mod_fastcgi.c>
+    FastCgiExternalServer /var/www/radosgw.fcgi -socket /tmp/radosgw.sock
+  </IfModule>
+
+
+Then, create a virtual host configuration as follows:
+
+::
+
+  <VirtualHost *:80>
+    ServerName rgw.example1.com
+    ServerAlias rgw
+    ServerAdmin webmaster@example1.com
+    DocumentRoot /var/www
+
+    <IfModule mod_rewrite.c>
+      RewriteEngine On
+      RewriteRule ^/([a-zA-Z0-9-_.]*)([/]?.*) /radosgw.fcgi?page=$1&params=$2&%{QUERY_STRING} [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
+    </IfModule>
+
+    <IfModule mod_fastcgi.c>
+      <Directory /var/www>
+        Options +ExecCGI
+        AllowOverride All
+        SetHandler fastcgi-script
+        Order allow,deny
+        Allow from all
+        AuthBasicAuthoritative Off
+      </Directory>
+    </IfModule>
+
+    AllowEncodedSlashes On
+    ServerSignature Off
+  </VirtualHost>
+
+
+Starting the daemons
+--------------------
+
+For the gateway to become operational, start both the radosgw daemon
+and your web server:
+
+::
+
+  service radosgw start
+  service apache start
+
+
+Creating users
+--------------
+
+In order to be able to use the RESTful API, create a user with the
+``radosgw-admin`` utility:
+
+::
+
+  $ radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com
+  { "user_id": "johndoe",
+    "rados_uid": 0,
+    "display_name": "John Doe",
+    "email": "john@example.com",
+    "suspended": 0,
+    "subusers": [],
+    "keys": [
+      { "user": "johndoe",
+        "access_key": "QFAMEDSJP5DEKJO0DDXY",
+        "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}],
+    "swift_keys": []}
+
+Note that creating a user also creates an ``access_key`` and
+``secret_key`` entry for use with any S3 API-compatible client.
+
+
+Enabling Swift access
+---------------------
+
+Allowing access to the object store with Swift (OpenStack Object
+Storage) compatible clients requires an additional step, the creation
+of a subuser and a Swift access key.
+
+::
+
+  # radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full
+  { "user_id": "johndoe",
+    "rados_uid": 0,
+    "display_name": "John Doe",
+    "email": "john@example.com",
+    "suspended": 0,
+    "subusers": [
+      { "id": "johndoe:swift",
+        "permissions": "full-control"}],
+    "keys": [
+      { "user": "johndoe",
+        "access_key": "QFAMEDSJP5DEKJO0DDXY",
+        "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}],
+    "swift_keys": []}
+
+  # radosgw-admin key create --subuser=johndoe:swift --key-type=swift
+  { "user_id": "johndoe",
+    "rados_uid": 0,
+    "display_name": "John Doe",
+    "email": "john@example.com",
+    "suspended": 0,
+    "subusers": [
+       { "id": "johndoe:swift",
+         "permissions": "full-control"}],
+    "keys": [
+      { "user": "johndoe",
+        "access_key": "QFAMEDSJP5DEKJO0DDXY",
+        "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}],
+    "swift_keys": [
+      { "user": "johndoe:swift",
+        "secret_key": "E9T2rUZNu2gxUjcwUBO8n\/Ev4KX6\/GprEuH4qhu1"}]}
+
+With this configuration, you are able to use any Swift client to
+connect to and use radosgw. As an example, you might use the ``swift``
+command-line client utility that ships with the OpenStack Object
+Storage packages.
+
+::
+
+  $ swift -V 1.0 -A http://radosgw.example.com/auth \
+    -U johndoe:swift -K E9T2rUZNu2gxUjcwUBO8n\/Ev4KX6\/GprEuH4qhu1 \
+    post test
+  $ swift -V 1.0 -A http://radosgw.example.com/auth \
+    -U johndoe:swift -K E9T2rUZNu2gxUjcwUBO8n\/Ev4KX6\/GprEuH4qhu1 \
+    upload test myfile
+
+Note that the radosgw ``user:subuser`` tuple maps to the
+``tenant:user`` tuple expected by Swift.
+
+Note also that the radosgw Swift authentication service only supports
+built-in Swift authentication (``-V 1.0``) at this point. There is
+currently no way to make radosgw authenticate users via OpenStack
+Identity Service (Keystone).