.. index:: RADOS Gateway, radosgw ========================================= 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.]`` 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. :: FastCgiExternalServer /var/www/radosgw.fcgi -socket /tmp/radosgw.sock Then, create a virtual host configuration as follows: :: ServerName radosgw.example.com ServerAlias rgw.example.com ServerAdmin webmaster@example.com DocumentRoot /var/www RewriteEngine On RewriteRule ^/(.*) /radosgw.fcgi?%{QUERY_STRING} [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L] Options +ExecCGI AllowOverride All SetHandler fastcgi-script Order allow,deny Allow from all AuthBasicAuthoritative Off AllowEncodedSlashes On ServerSignature Off 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).