From 1310af2336fd10382b8563d13e808f8030c2efb2 Mon Sep 17 00:00:00 2001 From: John Wilkins Date: Mon, 14 Apr 2014 09:18:07 -0700 Subject: [PATCH] doc: Reworked the simple configuration guide to be more generic. Changes include removing keystone and putting it into a separate document, removing user config and putting it into an admin guide, and creating separate config examples for CentOS/RHEL and Debian/Ubuntu. Needs clarification on chown/chmod. Signed-off-by: John Wilkins --- doc/radosgw/config.rst | 600 ++++++++++++++++++----------------------- 1 file changed, 260 insertions(+), 340 deletions(-) diff --git a/doc/radosgw/config.rst b/doc/radosgw/config.rst index 4d54e761bcf79..2a7fbe036d1d3 100644 --- a/doc/radosgw/config.rst +++ b/doc/radosgw/config.rst @@ -2,463 +2,383 @@ Configuring Ceph Object Gateway ================================= -Before you can start using the :term:`Ceph Object Gateway`, you must modify your -Ceph configuration file to include a section for the Ceph Object Gateway. You -must also create an ``rgw.conf`` file in the ``/etc/apache2/sites-enabled`` -directory. The ``rgw.conf`` file configures Apache to interact with FastCGI. +Configuring a Ceph Object Gateway requires a running Ceph Storage Cluster, +and an Apache web server with the FastCGI module. +The Ceph Object Gateway is a client of the Ceph Storage Cluster. As a +Ceph Storage Cluster client, it requires: -Add a Gateway Configuration to Ceph -=================================== +- A name for the gateway instance +- A storage cluster user name with appropriate permissions and a keyring +- Pools to store its data +- A data directory for the gateway instance +- An instance entry in the Ceph Configuration file +- A configuration file for the web server to interact with FastCGI -Add the Ceph Object Gateway configuration to your Ceph Configuration file. The -Ceph Object Gateway configuration requires you to specify the host name where -you installed the Ceph Object Gateway daemon, a keyring (for use with cephx), -the socket path and a log file. For example:: +For this configuration guide, we will use the instance name ``gateway``. - [client.radosgw.gateway] - host = {host-name} - keyring = /etc/ceph/keyring.radosgw.gateway - rgw socket path = /tmp/radosgw.sock - log file = /var/log/ceph/radosgw.log +Create a User and Keyring +========================= -.. note:: ``host`` must be your machine hostname, not FQDN. +Each instance must have a user name and key to communicate with a Ceph Storage +Cluster. In the following steps, we use an admin node to create a keyring. +Then, we create a client user name and key. Next, we add the +keys to the Ceph Storage Cluster. Finally, we distribute the key ring to +the node containing the gateway instance. -Redeploy Ceph Configuration -=========================== +.. topic:: Monitor Key CAPS -If you deploy Ceph with ``mkcephfs``, manually redeploy ``ceph.conf`` to the -hosts in your cluster. For example:: + When you provide CAPS to the key, you MUST provide read capability. + However, you have the option of providing write capability for the monitor. + This is an important choice. If you provide write capability to the key, + the Ceph Object Gateway will have the ability to create pools automatically; + however, it will create pools with either the default number of placement + groups (not ideal) or the number of placement groups you specified in your + Ceph configuration file. If you allow the Ceph Object Gateway to create + pools automatically, ensure that you have reasonable defaults for the number + of placement groups first. See `Pool Configuration`_ for details. - cd /etc/ceph - ssh {host-name} sudo tee /etc/ceph/ceph.conf < ceph.conf -If you used ``ceph-deploy``, push a new copy to the hosts in your cluster. -For example:: +See the `Cephx Guide`_ for additional details on Ceph authentication. - ceph-deploy config push {host-name [host-name]...} +#. Create a keyring for the gateway. :: + sudo ceph-authtool --create-keyring /etc/ceph/ceph.client.radosgw.keyring + sudo chmod +r /etc/ceph/ceph.client.radosgw.keyring + -Create Data Directory -===================== +#. Generate a Ceph Object Gateway user name and key for each instance. For + exemplary purposes, we will use the name ``gateway`` after ``client.radosgw``:: -Deployment scripts may not create the default Ceph Object Gateway data -directory. Create data directories for each instance of a ``radosgw`` daemon -(if you haven't done so already). The ``host`` variables in the Ceph -configuration file determine which host runs each instance of a ``radosgw`` -daemon. The typical form specifies the ``radosgw`` daemon, the cluster name and -the daemon ID. :: + sudo ceph-authtool /etc/ceph/ceph.client.radosgw.keyring -n client.radosgw.gateway --gen-key - sudo mkdir -p /var/lib/ceph/radosgw/{$cluster}-{$id} -Using the exemplary ``ceph.conf`` settings above, you would execute the following:: +#. Add capabilities to the key. See `Configuration Reference - Pools`_ for details + on the effect of write permissions for the monitor and creating pools. :: - sudo mkdir -p /var/lib/ceph/radosgw/ceph-radosgw.gateway + sudo ceph-authtool -n client.radosgw.gateway --cap osd 'allow rwx' --cap mon 'allow rw' /etc/ceph/ceph.client.radosgw.keyring -Create a Gateway Configuration -============================== +#. Once you have created a keyring and key to enable the Ceph Object Gateway + with access to the Ceph Storage Cluster, add the key as an entry to your + Ceph Storage Cluster. For example:: -Create an ``rgw.conf`` file under the ``/etc/apache2/sites-available`` directory -on the host where you installed the Ceph Object Gateway. + sudo ceph -k /etc/ceph/ceph.client.admin.keyring auth add client.radosgw.gateway -i /etc/ceph/ceph.client.radosgw.keyring -We recommend deploying FastCGI as an external server, because allowing -Apache to manage FastCGI sometimes introduces high latency. To manage FastCGI -as an external server, use the ``FastCgiExternalServer`` directive. -See `FastCgiExternalServer`_ for details on this directive. -See `Module mod_fastcgi`_ for general details. :: - FastCgiExternalServer /var/www/s3gw.fcgi -socket /tmp/radosgw.sock +#. Distribute the keyring to the node with the gateway instance. :: -.. _Module mod_fastcgi: http://www.fastcgi.com/drupal/node/25 -.. _FastCgiExternalServer: http://www.fastcgi.com/drupal/node/25#FastCgiExternalServer + sudo scp /etc/ceph/ceph.client.radosgw.keyring ceph@{hostname}:/home/ceph + ssh {hostname} + sudo mv ceph.client.radosgw.keyring /etc/ceph/ceph.client.radosgw.keyring -Once you have configured FastCGI as an external server, you must -create the virtual host configuration within your ``rgw.conf`` file. See -`Apache Virtual Host documentation`_ for details on ```` format -and settings. Replace the values in brackets. :: - - ServerName {fqdn} - ServerAdmin {email.address} - DocumentRoot /var/www - -.. _Apache Virtual Host documentation: http://httpd.apache.org/docs/2.2/vhosts/ +Create Pools +============ -Ceph Object Gateway requires a rewrite rule for the Amazon S3-compatible interface. -It's required for passing in the ``HTTP_AUTHORIZATION env`` for S3, which is -filtered out by Apache. The rewrite rule is not necessary for the OpenStack -Swift-compatible interface. Turn on the rewrite engine and add the following -rewrite rule to your Virtual Host configuration. :: +Ceph Object Gateways require Ceph Storage Cluster pools to store specific +gateway data. If the user you created has permissions, the gateway +will create the pools automatically. However, you should ensure that you have +set an appropriate default number of placement groups per pool into your Ceph +configuration file. - RewriteEngine On - RewriteRule ^/([a-zA-Z0-9-_.]*)([/]?.*) /s3gw.fcgi?page=$1¶ms=$2&%{QUERY_STRING} [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L] - -Since the ```` is running ``mod_fastcgi.c``, you must include a -section in your ```` configuration for the ``mod_fastcgi.c`` module. +When configuring a gateway with the default region and zone, the naming +convention for pools typically omits region and zone naming, but you can use any +naming convention you prefer. For example: -:: - - ... - - - Options +ExecCGI - AllowOverride All - SetHandler fastcgi-script - Order allow,deny - Allow from all - AuthBasicAuthoritative Off - - - ... - - -See ` Directive`_ for additional details. +- ``.rgw.root`` +- ``.domain.rgw`` +- ``.rgw.root`` +- ``.rgw.control`` +- ``.rgw.gc`` +- ``.rgw.buckets.index`` +- ``.rgw.buckets`` +- ``.log`` +- ``.intent-log`` +- ``.usage`` +- ``.users`` +- ``.users.email`` +- ``.users.swift`` +- ``.users.uid`` -.. _ Directive: http://httpd.apache.org/docs/2.2/mod/core.html#ifmodule - -You should configure Apache to allow encoded slashes, provide paths for -log files and to turn off server signatures. :: - - - ... - AllowEncodedSlashes On - ErrorLog /var/log/apache2/error.log - CustomLog /var/log/apache2/access.log combined - ServerSignature Off - - -.. important:: If you are using CentOS or similar, make sure that ``FastCgiWrapper`` is turned off in ``/etc/httpd/conf.d/fastcgi.conf``. -Finally, if you enabled SSL, make sure that you set the port to your SSL port -(usually 443) and your configuration file includes the following:: +See `Configuration Reference - Pools`_ for details on the default pools for +gateways. See `Pools`_ for details on creating pools. Execute the following +to create a pool:: - SSLEngine on - SSLCertificateFile /etc/apache2/ssl/apache.crt - SSLCertificateKeyFile /etc/apache2/ssl/apache.key - SetEnv SERVER_PORT_SECURE 443 + ceph osd pool create {poolname} {pg-num} {pgp-num} -Enable the Configuration -======================== +.. tip:: When adding a large number of pools, it may take some time for your + cluster to return to a ``active + clean`` state. -Enable the site for ``rgw.conf``. :: +When you have completed this step, execute the following to ensure that +you have created all of the foregoing pools:: - sudo a2ensite rgw.conf + rados lspools -Disable the default site. :: - sudo a2dissite default - +Create Data Directory +===================== -Add a Ceph Object Gateway Script -================================ +Deployment scripts may not create the default Ceph Object Gateway data +directory. Create data directories for each instance of a ``radosgw`` daemon +(if they don't exist). The ``host`` variables in the Ceph +configuration file determine which host runs each instance of a ``radosgw`` +daemon. The typical form specifies the ``radosgw`` daemon, the cluster name and +the daemon ID. :: -Add a ``s3gw.fcgi`` file (use the same name referenced in the first line -of ``rgw.conf``) to ``/var/www``. The contents of the file should include:: + sudo mkdir -p /var/lib/ceph/radosgw/{$cluster}-{$id} - #!/bin/sh - exec /usr/bin/radosgw -c /etc/ceph/ceph.conf -n client.radosgw.gateway - -Ensure that you apply execute permissions to ``s3gw.fcgi``. :: +Using the exemplary ``ceph.conf`` settings above, you would execute the following:: - sudo chmod +x s3gw.fcgi + sudo mkdir -p /var/lib/ceph/radosgw/ceph-radosgw.gateway -Generate a Keyring and Key for the Gateway -========================================== -You must create a keyring for the Ceph Object Gateway. For example:: +Add a Gateway Configuration to Ceph +=================================== - sudo ceph-authtool --create-keyring /etc/ceph/keyring.radosgw.gateway - sudo chmod +r /etc/ceph/keyring.radosgw.gateway - +Add the Ceph Object Gateway configuration to your Ceph Configuration file. The +Ceph Object Gateway configuration requires you to identify the Ceph Object +Gateway instance. Then, you must specify the host name where you installed the +Ceph Object Gateway daemon, a keyring (for use with cephx), the socket path and +a log file. For example:: -.. topic:: Monitor Key CAPS + [client.radosgw.{instance-name}] + host = {host-name} + keyring = /etc/ceph/ceph.client.radosgw.keyring + rgw socket path = /var/run/ceph/client.radosgw.{instance-name}.asok + log file = /var/log/ceph/client.radosgw.{instance-name}.log - When you provide CAPS to the monitor key, you MUST provide read capability. - However, you have the option of providing write capability. This is an - important choice. If you provide write capability to the monitor key, - the Ceph Object Gateway will have the ability to create pools automatically; - however, it will create pools with either the default number of placement - groups (not ideal) or the number of placement groups you specified in your - Ceph configuration file. If you allow the Ceph Object Gateway to create - pools automatically, ensure that you have reasonable defaults for the number - of placement groups first. See `Pool Configuration`_ for details. +The ``[client.radosgw.*]`` portion of the gateway instance identifies this portion +of the Ceph configuration file as configuring a Ceph Storage Cluster client where the client type is +a Ceph Object Gateway (i.e., ``radosgw``). The instance name follows. For example:: -Generate a key so that the Ceph Object Gateway can identify a user name and authenticate -the user with the cluster. Then, add capabilities to the key. For example:: + [client.radosgw.gateway] + host = ceph-gateway + keyring = /etc/ceph/ceph.client.radosgw.keyring + rgw socket path = /var/run/ceph/client.radosgw.gateway.asok + log file = /var/log/ceph/client.radosgw.gateway.log - sudo ceph-authtool /etc/ceph/keyring.radosgw.gateway -n client.radosgw.gateway --gen-key - sudo ceph-authtool -n client.radosgw.gateway --cap osd 'allow rwx' --cap mon 'allow rw' /etc/ceph/keyring.radosgw.gateway - +.. note:: ``host`` must be your machine hostname, not the FQDN. -See the `Cephx Guide`_ for additional details on Ceph authentication. -Add to Ceph Keyring Entries -=========================== +Configuring Operations Logging +------------------------------ -Once you have created a keyring and key for the Ceph Object Gateway to access -the Ceph Storage Cluster, add it as an entry in the Ceph keyring. For example:: +In early releases of Ceph, the Ceph Object Gateway will log every successful +operation in the Ceph Object Gateway backend by default. This means that every +request, whether it is a read request or a write request will generate a gateway +operation that writes data. This does not come without cost, and may affect +overall performance. Turning off logging completely can be done by adding the +following config option to the Ceph configuration file:: - sudo ceph -k /etc/ceph/ceph.client.admin.keyring auth add client.radosgw.gateway -i /etc/ceph/keyring.radosgw.gateway - + rgw enable ops log = false -Create Default Pools -==================== +Another way to reduce the logging load is to send operations logging data to a UNIX domain +socket, instead of writing it to the Ceph Object Gateway backend:: -If the key that provides Ceph Object Gateway with access to the Ceph Storage -Cluster does not have write capability to the Ceph Monitor, you must create the -default pools manually. The default pools for the Ceph Object Gateway include: + rgw ops log rados = false + rgw enable ops log = true + rgw ops log socket path = -- ``.rgw`` -- ``.rgw.control`` -- ``.rgw.gc`` -- ``.log`` -- ``.intent-log`` -- ``.usage`` -- ``.users`` -- ``.users.email`` -- ``.users.swift`` -- ``.users.uid`` +When specifying a UNIX domain socket, it is also possible to specify the maximum amount +of memory that will be used to keep the data backlog:: + rgw ops log data backlog = -See `Pools`_ for details on creating pools. +Any backlogged data in excess to the specified size will be lost, so the socket +needs to be read constantly. -Restart Services and Start the Gateway -====================================== +Enabling Subdomain S3 Calls +--------------------------- -To ensure that all components have reloaded their configurations, we recommend -restarting your ``ceph`` and ``apache`` services. Then, start up the -``radosgw`` service. For example:: +To use a Ceph Object Gateway with subdomain S3 calls (e.g., +``http://bucketname.hostname``), you must add the Ceph Object Gateway DNS name +under the ``[client.radosgw.gateway]`` section of your Ceph configuration file:: - sudo service ceph restart - sudo service apache2 restart - sudo /etc/init.d/radosgw start + [client.radosgw.gateway] + ... + rgw dns name = {hostname} -.. note:: The service name on RPM based distribution is ceph-radosgw. +You should also consider installing `Dnsmasq`_ on your client machine(s) when +using ``http://{bucketname}.{hostname}`` syntax. The ``dnsmasq.conf`` file +should include the following settings:: -See `Operating a Cluster`_ for details. Some versions of Ceph use different -methods for starting and stopping clusters. + address=/{hostname}/{host-ip-address} + listen-address={client-loopback-ip} +Then, add the ``{client-loopback-ip}`` IP address as the first DNS nameserver +on client the machine(s). -Create a Gateway User -===================== -To use the REST interfaces, first create an initial Ceph Object Gateway user. -The Ceph Object Gateway user is not the same user as the -``client.rados.gateway`` user, which identifies the Ceph Object Gateway as a -user of the Ceph Storage Cluster. The Ceph Object Gateway user is a user of the -Ceph Object Gateway. :: - sudo radosgw-admin user create --uid="{username}" --display-name="{Display Name}" +Redeploy Ceph Configuration +--------------------------- -For example:: - - radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com - -.. code-block:: javascript - - { "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": []} - -Creating a user also creates an ``access_key`` and ``secret_key`` entry for use -with any S3 API-compatible client. For details on Ceph Object Gateway -administration, see `radosgw-admin`_. - -.. _radosgw-admin: ../../man/8/radosgw-admin/ - -.. important:: Check the key output. Sometimes ``radosgw-admin`` - generates a key with an escape (``\``) character, and some clients - do not know how to handle escape characters. Remedies include - removing the escape character (``\``), encapsulating the string - in quotes, or simply regenerating the key and ensuring that it - does not have an escape character. +To use ``ceph-deploy`` to push a new copy of the configuration file to the hosts +in your cluster, execute the following:: -Configuring Operations Logging -============================== + ceph-deploy config push {host-name [host-name]...} -By default, Ceph Object Gateway will log every successful operation in the Ceph -Object Gateway backend. This means that every request, whether it is a read -request or a write request will generate a gateway operation that writes data. -This does not come without cost, and may affect overall performance. Turning off -logging completely can be done by adding the following config option to the Ceph -configuration file:: - rgw enable ops log = false +Add a Ceph Object Gateway Script +================================ -Another way to reduce the logging load is to send operations logging data to a UNIX domain -socket, instead of writing it to the Ceph Object Gateway backend:: +Add a ``s3gw.fcgi`` file (use the same name referenced in the first line +of ``rgw.conf``). For Debian/Ubuntu distributions, save the file to the +``/var/www`` directory. For CentOS/RHEL distributions, save the file to the +``/var/www/html`` directory. Assuming a cluster named ``ceph`` (default), +and the user created in previous steps, the contents of the file should include:: - rgw ops log rados = false - rgw enable ops log = true - rgw ops log socket path = + #!/bin/sh + exec /usr/bin/radosgw -c /etc/ceph/ceph.conf -n client.radosgw.gateway + +Ensure that you apply execute permissions to ``s3gw.fcgi``. :: -When specifying a UNIX domain socket, it is also possible to specify the maximum amount -of memory that will be used to keep the data backlog:: + sudo chmod +x s3gw.fcgi - rgw ops log data backlog = -Any backlogged data in excess to the specified size will be lost, so the socket -needs to be read constantly. +Create a Gateway Configuration +============================== -Enabling Swift Access -===================== +On the host where you installed the Ceph Object Gateway, create an ``rgw.conf`` +file. For Debian/Ubuntu systems, place the file in the +``/etc/apache2/sites-available`` directory. For CentOS/RHEL systems, place the +file in the ``/etc/httpd/conf.d`` directory. -Allowing access to the object store with Swift (OpenStack Object Storage) -compatible clients requires an additional step; namely, the creation of a -subuser and a Swift access key. +We recommend deploying FastCGI as an external server, because allowing Apache to +manage FastCGI sometimes introduces high latency. To manage FastCGI as an +external server, use the ``FastCgiExternalServer`` directive. See +`FastCgiExternalServer`_ for details on this directive. See `Module +mod_fastcgi`_ for general details. See `Apache Virtual Host documentation`_ for +details on ```` format and settings. See ` Directive`_ +for additional details. -:: +Ceph Object Gateway requires a rewrite rule for the Amazon S3-compatible +interface. It's required for passing in the ``HTTP_AUTHORIZATION env`` for S3, +which is filtered out by Apache. The rewrite rule is not necessary for the +OpenStack Swift-compatible interface. - sudo radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full +You should configure Apache to allow encoded slashes, provide paths for log +files and to turn off server signatures. See below for an exemplary embodiment +of a gateway configuration for Debian/Ubuntu and CentOS/RHEL. -.. code-block:: javascript +.. rubric:: Debian/Ubuntu - { "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": []} -:: +.. literalinclude:: rgw-debian.conf + :language: ini - sudo radosgw-admin key create --subuser=johndoe:swift --key-type=swift --gen-secret -.. code-block:: javascript +.. rubric:: CentOS/RHEL - { "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"}]} -This step enables you to use any Swift client to connect to and use the Ceph -Object Gateway via the Swift-compatible API. As an example, you might use the -``swift`` command-line client utility that ships with the OpenStack Object -Storage packages. -:: +.. literalinclude:: rgw-centos.conf + :language: ini - 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 -Ceph Object Gateway's ``user:subuser`` tuple maps to the ``tenant:user`` tuple expected by Swift. +#. Replace the ``/{path}/{socket-name}`` entry with path to the socket and + the socket name. For example, + ``/var/run/ceph/client.radosgw.gateway.sock``. Ensure that you use the + same path and socket name in your ``ceph.conf`` entry. -.. note:: Ceph Object Gateway's Swift authentication service only supports - built-in Swift authentication (``-V 1.0``). To make the gateway authenticate - users via OpenStack Identity Service (Keystone), see below. +#. Replace the ``{fqdn}`` entry with the fully-qualified domain name of the + server. + +#. Replace the ``{email.address}`` entry with the email address for the + server administrator. + +#. Add a ``ServerAlias`` if you wish to use S3-style subdomains + (of course you do). +#. Save the configuration to a file (e.g., ``rgw.conf``). -Integrating with OpenStack Keystone -=================================== +Finally, if you enabled SSL, make sure that you set the port to your SSL port +(usually 443) and your configuration file includes the following:: -It is possible to integrate the Ceph Object Gateway with Keystone, the OpenStack -identity service. This sets up the gateway to accept Keystone as the users -authority. A user that Keystone authorizes to access the gateway will also be -automatically created on the Ceph Object Gateway (if didn't exist beforehand). A -token that Keystone validates will be considered as valid by the gateway. + SSLEngine on + SSLCertificateFile /etc/apache2/ssl/apache.crt + SSLCertificateKeyFile /etc/apache2/ssl/apache.key + SetEnv SERVER_PORT_SECURE 443 -The following configuration options are available for Keystone integration:: - [client.radosgw.gateway] - rgw keystone url = {keystone server url:keystone server admin port} - rgw keystone admin token = {keystone admin token} - rgw keystone accepted roles = {accepted user roles} - rgw keystone token cache size = {number of tokens to cache} - rgw keystone revocation interval = {number of seconds before checking revoked tickets} - rgw s3 auth use keystone = true - nss db path = {path to nss db} +.. _Module mod_fastcgi: http://www.fastcgi.com/drupal/node/25 +.. _FastCgiExternalServer: http://www.fastcgi.com/drupal/node/25#FastCgiExternalServer +.. _Apache Virtual Host documentation: http://httpd.apache.org/docs/2.2/vhosts/ +.. _ Directive: http://httpd.apache.org/docs/2.2/mod/core.html#ifmodule + + +.. important:: If you are using CentOS, RHEL or a similar distribution, make + sure that ``FastCgiWrapper`` is turned ``off`` in + ``/etc/httpd/conf.d/fastcgi.conf``. It is usually ``on`` by default. + +For Debian/Ubuntu distributions, enable the site for ``rgw.conf``. :: + + sudo a2ensite rgw.conf + +Disable the default site. :: + + sudo a2dissite default + -A Ceph Object Gateway user is mapped into a Keystone ``tenant``. A Keystone user -has different roles assigned to it on possibly more than a single tenant. When -the Ceph Object Gateway gets the ticket, it looks at the tenant, and the user -roles that are assigned to that ticket, and accepts/rejects the request -according to the ``rgw keystone accepted roles`` configurable. +Adjust Path Ownership/Permissions +================================= -Keystone itself needs to be configured to point to the Ceph Object Gateway as an -object-storage endpoint:: +.. todo:: Need clarification for CentOS/RHEL for ``/var/run/ceph``, + ``/var/log/httpd`` or ``/var/log/apache2`` and any other relevant + directory permissions, or group/user ownership. - keystone service-create --name swift --type object-store - keystone endpoint-create --service-id --publicurl http://radosgw.example.com/swift/v1 \ - --internalurl http://radosgw.example.com/swift/v1 --adminurl http://radosgw.example.com/swift/v1 +Restart Services and Start the Gateway +====================================== +To ensure that all components have reloaded their configurations, we recommend +restarting your ``ceph`` and ``apache`` services. Then, start up the +``radosgw`` service. For example:: -The keystone URL is the Keystone admin RESTful API URL. The admin token is the -token that is configured internally in Keystone for admin requests. + sudo service ceph restart + sudo service apache2 restart + sudo /etc/init.d/radosgw start -The Ceph Object Gateway will query Keystone periodically for a list of revoked -tokens. These requests are encoded and signed. Also, Keystone may be configured -to provide self-signed tokens, which are also encoded and signed. The gateway -needs to be able to decode and verify these signed messages, and the process -requires that the gateway be set up appropriately. Currently, the Ceph Object -Gateway will only be able to perform the procedure if it was compiled with -``--with-nss``. Configuring the Ceph Object Gateway to work with Keystone also -requires converting the OpenSSL certificates that Keystone uses for creating the -requests to the nss db format, for example:: +.. note:: The service name on RPM based distribution is ceph-radosgw. - mkdir /var/ceph/nss +See `Operating a Cluster`_ for details. Some versions of Ceph use different +methods for starting and stopping clusters. - openssl x509 -in /etc/keystone/ssl/certs/ca.pem -pubkey | \ - certutil -d /var/ceph/nss -A -n ca -t "TCu,Cu,Tuw" - openssl x509 -in /etc/keystone/ssl/certs/signing_cert.pem -pubkey | \ - certutil -A -d /var/ceph/nss -n signing_cert -t "P,P,P" +Once the service is up and running, you can make an anonymous GET request to see +if the gateway returns a response. A simple HTTP request to the domain name +should return the following: +.. code-block:: xml -Enabling Subdomain S3 Calls -=========================== + + + anonymous + + + + -To use a Ceph Object Gateway with subdomain S3 calls (e.g., -``http://bucketname.hostname``), you must add the Ceph Object Gateway DNS name -under the ``[client.radosgw.gateway]`` section of your Ceph configuration file:: - [client.radosgw.gateway] - ... - rgw dns name = {hostname} +Using The Gateway +================= -You should also consider installing `Dnsmasq`_ on your client machine(s) when -using ``http://{bucketname}.{hostname}`` syntax. The ``dnsmasq.conf`` file -should include the following settings:: +To use the REST interfaces, first create an initial Ceph Object Gateway user for +the S3 interface. Then, create a subuser for the swift interface. See the `Admin +Guide`_ for details. - address=/{hostname}/{host-ip-address} - listen-address={client-loopback-ip} -Then, add the ``{client-loopback-ip}`` IP address as the first DNS nameserver -on client the machine(s). .. _Dnsmasq: https://help.ubuntu.com/community/Dnsmasq +.. _Configuration Reference - Pools: ../config-ref#pools .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/ .. _Pools: ../../rados/operations/pools .. _Cephx Guide: ../../rados/operations/authentication/#cephx-guide .. _Operating a Cluster: ../../rados/rados/operations/operating +.. _Admin Guide: ../admin -- 2.39.5