From: John Wilkins Date: Mon, 5 Aug 2013 20:43:21 +0000 (-0700) Subject: doc: Nomenclature update. Added topic for monitor key caps. Added default pool steps. X-Git-Tag: v0.68~110 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=ea80532d2b3f7edbec056f620d33355d9c687f22;p=ceph.git doc: Nomenclature update. Added topic for monitor key caps. Added default pool steps. Signed-off-by: John Wilkins --- diff --git a/doc/radosgw/config.rst b/doc/radosgw/config.rst index 615a979fb5df..7dd9f9a93dd9 100644 --- a/doc/radosgw/config.rst +++ b/doc/radosgw/config.rst @@ -1,20 +1,20 @@ -=========================== - 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} @@ -24,8 +24,8 @@ For example:: .. 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:: @@ -33,15 +33,21 @@ 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} @@ -50,11 +56,11 @@ Using the exemplary ``ceph.conf`` settings above, you would execute the followin 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 @@ -80,7 +86,7 @@ and settings. Replace the values in brackets. :: .. _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 @@ -126,8 +132,8 @@ log files and to turn off server signatures. :: .. 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``. :: @@ -138,8 +144,8 @@ Disable the default site. :: 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:: @@ -152,49 +158,90 @@ Ensure that you apply execute permissions to ``s3gw.fcgi``. :: 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}" @@ -216,9 +263,9 @@ For example:: "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/ @@ -229,38 +276,40 @@ For details on RADOS Gateway administration, see `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 = -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 = -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. :: @@ -304,32 +353,33 @@ 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} @@ -339,30 +389,32 @@ The following config options are available for Keystone integration:: 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 --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 @@ -375,9 +427,9 @@ Keystone uses for creating the requests to the nss db format, for example:: 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] ... @@ -394,3 +446,7 @@ 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 +.. _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