-===========================
- Configuring RADOS Gateway
-===========================
+=================================
+ Configuring Ceph Object Gateway
+=================================
-Before you can start RADOS Gateway, you must modify your ``ceph.conf`` file
-to include a section for RADOS 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.
+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.
-Add a RADOS GW Configuration to ``ceph.conf``
-=============================================
+Add a Gateway Configuration to Ceph
+===================================
-Add the RADOS Gateway configuration to your ``ceph.conf`` file. The RADOS
-Gateway configuration requires you to specify the host name where you installed
-RADOS Gateway, a keyring (for use with cephx), the socket path and a log file.
-For example::
+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::
[client.radosgw.gateway]
host = {host-name}
.. note:: ``host`` must be your machine hostname, not FQDN.
-Deploy ``ceph.conf``
-====================
+Redeploy Ceph Configuration
+===========================
If you deploy Ceph with ``mkcephfs``, manually redeploy ``ceph.conf`` to the
hosts in your cluster. For example::
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::
+
+ ceph-deploy config push {host-name [host-name]...}
+
Create Data Directory
=====================
-The ``mkcephfs`` deployment script may not create the default RGW 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.conf`` file
-determine which host runs each instance of a ``radosgw`` daemon. The typical form
-specifes the daemon ``radosgw``, the cluster name and the daemon ID. ::
+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 mkdir -p /var/lib/ceph/radosgw/{$cluster}-{$id}
sudo mkdir -p /var/lib/ceph/radosgw/ceph-radosgw.gateway
-Create ``rgw.conf``
-===================
+Create a Gateway Configuration
+==============================
-Create an ``rgw.conf`` file on the host where you installed RADOS Gateway
-under the ``/etc/apache2/sites-available`` directory.
+Create an ``rgw.conf`` file under the ``/etc/apache2/sites-available`` directory
+on the host where you installed the Ceph Object Gateway.
We recommend deploying FastCGI as an external server, because allowing
Apache to manage FastCGI sometimes introduces high latency. To manage FastCGI
.. _Apache Virtual Host documentation: http://httpd.apache.org/docs/2.2/vhosts/
-RADOS Gateway requires a rewrite rule for the Amazon S3-compatible interface.
+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
.. important:: If you are using CentOS or similar, make sure that ``FastCgiWrapper`` is turned off in ``/etc/httpd/conf.d/fastcgi.conf``.
-Enable the RADOS Gateway Configuration
-======================================
+Enable the Configuration
+========================
Enable the site for ``rgw.conf``. ::
sudo a2dissite default
-Add a RADOS GW Script
-=====================
+Add a Ceph Object Gateway Script
+================================
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 chmod +x s3gw.fcgi
-Generate a Keyring and Key for RADOS Gateway
-============================================
+Generate a Keyring and Key for the Gateway
+==========================================
-You must create a keyring for the RADOS Gateway. For example::
+You must create a keyring for the Ceph Object Gateway. For example::
sudo ceph-authtool --create-keyring /etc/ceph/keyring.radosgw.gateway
sudo chmod +r /etc/ceph/keyring.radosgw.gateway
-Generate a key so that RADOS Gateway can identify a user name and authenticate
+
+.. topic:: Monitor Key CAPS
+
+ 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.
+
+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::
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
+See the `Cephx Guide`_ for additional details on Ceph authentication.
+
Add to Ceph Keyring Entries
===========================
-Once you have created a keyring and key for RADOS GW, add it as an entry in
-the Ceph keyring. For example::
+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::
sudo ceph -k /etc/ceph/ceph.client.admin.keyring auth add client.radosgw.gateway -i /etc/ceph/keyring.radosgw.gateway
-Restart Services and Start the RADOS Gateway
-============================================
+Create Default Pools
+====================
+
+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``
+- ``.rgw.control``
+- ``.rgw.gc``
+- ``.log``
+- ``.intent-log``
+- ``.usage``
+- ``.users``
+- ``.users.email``
+- ``.users.swift``
+- ``.users.uid``
+
-To ensure that all components have reloaded their configurations,
-we recommend restarting your ``ceph`` and ``apaches`` services. Then,
-start up the ``radosgw`` service. For example::
+See `Pools`_ for details on creating pools.
+
+
+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::
sudo service ceph restart
sudo service apache2 restart
sudo /etc/init.d/radosgw start
+See `Operating a Cluster`_ for details. Some versions of Ceph use different
+methods for starting and stopping clusters.
-Create a RADOS Gateway User
-===========================
-To use the REST interfaces, first create an initial RADOS Gateway user.
-The RADOS Gateway user is not the same user as the ``client.rados.gateway``
-user, which identifies the RADOS Gateway as a user of the RADOS cluster.
-The RADOS Gateway user is a user of the RADOS Gateway. ::
+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}"
"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 RADOS Gateway administration, see `radosgw-admin`_.
+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/
in quotes, or simply regenerating the key and ensuring that it
does not have an escape character.
-Configuring the Operations Logging
-==================================
+Configuring Operations Logging
+==============================
-By default, the RADOS Gateway will log every successful operation in the RADOS backend.
-This means that every request, whether it is a read request or a write request will
-generate a RADOS 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 ceph.conf::
+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
-Another way to reduce the logging load is to send operations logging data to a unix domain
-socket, instead of writing it to the RADOS backend::
+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::
rgw ops log rados = false
rgw enable ops log = true
rgw ops log socket path = <path to socket>
-When specifying a unix domain socket, it is also possible to specify the maximum amount
+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 = <size in bytes>
-Any backlogged data in excess to the specified size will be lost, so socket needs to be
-constantly read.
+Any backlogged data in excess to the specified size will be lost, so the socket
+needs to be read constantly.
+
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.
+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.
::
{ "user": "johndoe:swift",
"secret_key": "E9T2rUZNu2gxUjcwUBO8n\/Ev4KX6\/GprEuH4qhu1"}]}
-This step enables you to use any Swift client to connect to and use RADOS
-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.
+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.
::
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
-RGW's ``user:subuser`` tuple maps to the ``tenant:user`` tuple expected by Swift.
+Ceph Object Gateway's ``user:subuser`` tuple maps to the ``tenant:user`` tuple expected by Swift.
+
+.. 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.
-.. note:: RGW's Swift authentication service only supports built-in Swift
- authentication (``-V 1.0``). To make RGW authenticate users via OpenStack
- Identity Service (Keystone), see below.
Integrating with OpenStack Keystone
===================================
-It is possible to integrate RGW with Keystone, the OpenStack identity service.
-This sets up RGW to accept Keystone as the users authority. A user that Keystone
-authorizes to access RGW will also be automatically created on RGW (if didn't
-exist beforehand). A token that Keystone validates will be considered as valid
-by RGW.
+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.
-The following config options are available for Keystone integration::
+The following configuration options are available for Keystone integration::
[client.radosgw.gateway]
rgw keystone url = {keystone server url:keystone server admin port}
rgw keystone revocation interval = {number of seconds before checking revoked tickets}
nss db path = {path to nss db}
-An RGW user is mapped into a Keystone ``tenant``. A Keystone user has different
-roles assigned to it on possibly more than a single tenant. When RGW 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.
+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.
-Keystone itself needs to be configured to point to RGW as an object-storage
-endpoint::
+Keystone itself needs to be configured to point to the Ceph Object Gateway as an
+object-storage endpoint::
keystone service-create --name swift --type-object store
keystone endpoint-create --service-id <id> --publicurl http://radosgw.example.com/swift/v1 \
--internalurl http://radosgw.example.com/swift/v1 --adminurl http://radosgw.example.com/swift/v1
-The keystone url is the Keystone admin RESTful api url. The admin token is the
+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.
-RGW 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. RGW needs to be able to
-decode and verify these signed messages, and it requires it to be set up
-appropriately. Currently, RGW will be able to do it only if it was compiled with
-``--with-nss``. It also requires converting the OpenSSL certificates that
-Keystone uses for creating the requests to the nss db format, for example::
+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::
mkdir /var/ceph/nss
Enabling Subdomain S3 Calls
===========================
-To use RADOS Gateway with subdomain S3 calls (e.g.,
-``http://bucketname.hostname``), you must add the RADOS Gateway DNS name under
-the ``[client.radosgw.gateway]`` section of your Ceph configuration file::
+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]
...
on client the machine(s).
.. _Dnsmasq: https://help.ubuntu.com/community/Dnsmasq
+.. _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
\ No newline at end of file
projects / ceph.git / commitdiff