From f66f9d73ecedae2eb1797a8317c4dc3bd754721b Mon Sep 17 00:00:00 2001 From: =?utf8?q?Barbora=20An=C4=8Dincov=C3=A1?= Date: Tue, 3 Nov 2015 16:37:07 +0100 Subject: [PATCH] doc: Port changes from downstream (install-ceph-gateway) Signed-of-by: Bara Ancincova --- doc/install/install-ceph-gateway.rst | 495 +++++++++++++++-------- doc/install/install-ceph-gateway_old.rst | 255 ++++++++++++ 2 files changed, 585 insertions(+), 165 deletions(-) create mode 100644 doc/install/install-ceph-gateway_old.rst diff --git a/doc/install/install-ceph-gateway.rst b/doc/install/install-ceph-gateway.rst index ded9f35d643..214ea692bad 100644 --- a/doc/install/install-ceph-gateway.rst +++ b/doc/install/install-ceph-gateway.rst @@ -1,255 +1,420 @@ -============================= - Install Ceph Object Gateway -============================= +=========================== +Install Ceph Object Gateway +=========================== -.. note:: To run the Ceph object gateway service, you should have a running - Ceph cluster, the gateway host should have access to storage and public - networks, and SELinux should be in permissive mode in rpm-based distros. +As of `firefly` (v0.80), Ceph Object Gateway is runnig on Civetweb (embedded into the ``ceph-radosgw`` daemon) instead of Apache and FastCGI. Using Civetweb simplifies the Ceph Object Gateway installation and configuration. -The :term:`Ceph Object Gateway` daemon runs on Apache and FastCGI. +.. note:: To run the Ceph Object Gateway service, you should have a running Ceph storage cluster, and the gateway host should have access to the public network. -To run a :term:`Ceph Object Storage` service, you must install Apache and -Ceph Object Gateway daemon on the host that is going to provide the gateway -service, i.e, the ``gateway host``. If you plan to run a Ceph Object Storage -service with a federated architecture (multiple regions and zones), you must -also install the synchronization agent. +.. note:: In version 0.80, the Ceph Object Gateway does not support SSL. You may setup a reverse proxy server with SSL to dispatch HTTPS requests as HTTP requests to CivetWeb. -.. note:: Previous versions of Ceph shipped with ``mod_fastcgi``. The current - version ships with ``mod_proxy_fcgi`` instead. +Execute the Pre-Installation Procedure +-------------------------------------- -In distros that ship Apache 2.4 (such as RHEL 7, CentOS 7 or Ubuntu 14.04 -``Trusty``), ``mod_proxy_fcgi`` is already present. When you install the -``httpd`` package with ``yum`` or the ``apache2`` package with ``apt-get``, -``mod_proxy_fcgi`` becomes available for use on your server. +Refer to the Red Hat Ceph Storage Installation Guide, and execute the pre-installation procedures on your Ceph Object Gateway node. Specifically, you should disable ``requiretty`` on your Ceph Deploy user, set SELinux to ``Permissive`` and set up a Ceph Deploy user with password-less ``sudo``. For Ceph Object Gateways, you will need to open the port that Civetweb will use in production. -In distros that ship Apache 2.2 (such as RHEL 6, CentOS 6 or Ubuntu 12.04 -``Precise``), ``mod_proxy_fcgi`` comes as a separate package. In -**RHEL 6/CentOS 6**, it is available in ``EPEL 6`` repo and can be installed with -``yum install mod_proxy_fcgi``. For **Ubuntu 12.04**, a backport for -``mod_proxy_fcgi`` is in progress and a bug has been filed for the same. -See: `ceph radosgw needs mod-proxy-fcgi for apache 2.2`_ +.. note:: Civetweb runs on port ``7480`` by default. +Install Ceph Object Gateway +--------------------------- -Install Apache -============== +From the working directory of your administration server, install the Ceph Object Gateway package on the Ceph Object Gateway node. For example:: -To install Apache on the ``gateway host``, execute the following: + ceph-deploy install --rgw [ ...] -On Debian-based distros, run:: +The ``ceph-common`` package is a dependency, so ``ceph-deploy`` will install this too. The ``ceph`` CLI tools are intended for administrators. To make your Ceph Object Gateway node an administrator node, execute the following from the working directory of your administration server:: - sudo apt-get install apache2 + ceph-deploy admin -On RPM-based distros, run:: +Create a Gateway Instance +------------------------- - sudo yum install httpd +From the working directory of your administration server, create an instance of the Ceph Object Gateway on the Ceph Object Gateway. For example:: + ceph-deploy rgw create -Configure Apache -================ +Once the gateway is running, you should be able to access it on port ``7480`` with an unauthenticated request like this:: -Make the following changes in Apache's configuration on the ``gateway host``: + http://client-node:7480 -Debian-based distros --------------------- +If the gateway instance is working properly, you should receive a response like this:: -#. Add a line for the ``ServerName`` in ``/etc/apache2/apache2.conf``. Provide - the fully qualified domain name of the server machine - (e.g., ``hostname -f``):: + + + + anonymous + + + + + - ServerName {fqdn} +If at any point you run into trouble and you want to start over, execute the following to purge the configuration:: -#. Load ``mod_proxy_fcgi`` module. + ceph-deploy purge [] + ceph-deploy purgedata [] - Execute:: +If you execute ``purge``, you must re-install Ceph. - sudo a2enmod proxy_fcgi +Change the Default Port +----------------------- -#. Start Apache service:: +Civetweb runs on port ``7480`` by default. To change the default port (e.g,. to port ``80``), modify your Ceph configuration file in the working directory of your administration server. Add a section entitled ``[client.rgw.]``, replacing ```` with the short node name of your Ceph Object Gateway node (i.e., ``hostname -s``). - sudo service apache2 start +.. note:: In version 0.94, the Ceph Object Gateway does not support SSL. You may setup a reverse proxy web server with SSL to dispatch HTTPS requests as HTTP requests to CivetWeb. -RPM-based distros ------------------ - -#. Open the ``httpd.conf`` file:: - - sudo vim /etc/httpd/conf/httpd.conf - -#. Uncomment ``#ServerName`` in the file and add the name of your server. Provide - the fully qualified domain name of the server machine - (e.g., ``hostname -f``):: +For example, if your node name is ``gateway-node1``, add a section like this after the ``[global]`` section:: - ServerName {fqdn} + [client.rgw.gateway-node1] + rgw_frontends = "civetweb port=80" -#. Update ``/etc/httpd/conf/httpd.conf`` to load ``mod_proxy_fcgi`` module. Add - the following to the file:: +.. note:: Ensure that you leave no whitespace between ``port=`` in the ``rgw_frontends`` key/value pair. The ``[client.rgw.gateway-node1]`` heading 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., ``rgw``), and the name of the instance is ``gateway-node1``. - - LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so - +Push the updated configuration file to your Ceph Object Gateway node +(and other Ceph nodes):: -#. Edit the line ``Listen 80`` in ``/etc/httpd/conf/httpd.conf`` with the public - IP address of the host that you are configuring as a gateway server. Write - ``Listen {IP ADDRESS}:80`` in place of ``Listen 80``. + ceph-deploy --overwrite-conf config push [] -#. Start httpd service +To make the new port setting take effect, restart the Ceph Object +Gateway:: - Execute:: + sudo systemctl restart ceph-radosgw.service - sudo service httpd start +Finally, check to ensure that the port you selected is open on the node's firewall (e.g., port ``80``). If it is not open, add the port and reload the firewall configuration. For example:: - Or:: + sudo firewall-cmd --list-all + sudo firewall-cmd --zone=public --add-port 80/tcp --permanent + sudo firewall-cmd --reload - sudo systemctl start httpd +Migrating from Apache to Civetweb +--------------------------------- +If you're running the Ceph Object Gateway on Apache and FastCGI with Ceph Storage v0.80 or above, you're already running Civetweb--it starts with the ``ceph-radosgw`` daemon and it's running on port 7480 by default so that it doesn't conflict with your Apache and FastCGI installation and other commonly used web service ports. Migrating to use Civetweb basically involves removing your Apache installation. Then, you must remove Apache and FastCGI settings from your Ceph configuration file and reset ``rgw_frontends`` to Civetweb. -Enable SSL -========== +Referring back to the description for installing a Ceph Object Gateway with ``ceph-deploy``, notice that the configuration file only has one setting ``rgw_frontends`` (and that's assuming you elected to change the default port). The ``ceph-deploy`` utility generates the data directory and the keyring for you--placing the keyring in ``/var/lib/ceph/radosgw/{rgw-intance}``. The daemon looks in default locations, whereas you may have specified different settings in your Ceph configuration file. Since you already have keys and a data directory, you will want to maintain those paths in your Ceph configuration file if you used something other than default paths. -Some REST clients use HTTPS by default. So you should consider enabling SSL -for Apache. Use the following procedures to enable SSL. +A typical Ceph Object Gateway configuration file for an Apache-based deployment looks something like this:: -.. note:: You can use self-certified certificates. Some client - APIs check for a trusted certificate authority. You may need to obtain - a SSL certificate from a trusted authority to use those client APIs. + [client.radosgw.gateway-node1] + host = {hostname} + keyring = /etc/ceph/ceph.client.radosgw.keyring + rgw socket path = "" + log file = /var/log/radosgw/client.radosgw.gateway-node1.log + rgw frontends = fastcgi socket\_port=9000 socket\_host=0.0.0.0 + rgw print continue = false +To modify it for use with Civetweb, simply remove the Apache-specific settings such as ``rgw_socket_path`` and ``rgw_print_continue``. Then, change the ``rgw_frontends`` setting to reflect Civetweb rather than the Apache FastCGI front end and specify the port number you intend to use. For example:: -Debian-based distros --------------------- + [client.radosgw.gateway-node1] + host = {hostname} + keyring = /etc/ceph/ceph.client.radosgw.keyring + log file = /var/log/radosgw/client.radosgw.gateway-node1.log + rgw_frontends = civetweb port=80 -To enable SSL on Debian-based distros, execute the following steps: +Finally, restart the Ceph Object Gateway:: -#. Ensure that you have installed the dependencies:: + sudo systemctl restart ceph-radosgw.service - sudo apt-get install openssl ssl-cert +If you used a port number that is not open, you will also need to open that port on your firewall. -#. Enable the SSL module:: +Configure Bucket Sharding +------------------------- - sudo a2enmod ssl +A Ceph Object Gateway stores bucket index data in the ``index_pool``, which defaults to ``.rgw.buckets.index``. Sometimes users like to put many objects (hundreds of thousands to millions of objects) in a single bucket. If you do not use the gateway administration interface to set quotas for the maximum number of objects per bucket, the bucket index can suffer significant performance degradation when users place large numbers of objects into a bucket. -#. Generate a certificate:: +In Ceph 0.94, you may shard bucket indices to help prevent performance bottlenecks when you allow a high number of objects per bucket. The ``rgw_override_bucket_index_max_shards`` setting allows you to set a maximum number of shards per bucket. The default value is ``0``, which means bucket index sharding is off by default. - sudo mkdir /etc/apache2/ssl - sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt +To turn bucket index sharding on, set ``rgw_override_bucket_index_max_shards`` to a value greater than ``0``. -#. Restart Apache:: +For simple configurations, you may add ``rgw_override_bucket_index_max_shards`` to your Ceph configuration file. Add it under ``[global]`` to create a system-wide value. You can also set it for each instance in your Ceph configuration file. - sudo service apache2 restart +Once you have changed your bucket sharding configuration in your Ceph configuration file, restart your gateway:: + sudo systemctl restart ceph-radosgw.service -See the `Ubuntu Server Guide`_ for additional details. - - -RPM-based distros ------------------ +For federated configurations, each zone may have a different ``index_pool`` setting for failover. To make the value consistent for a region's zones, you may set ``rgw_override_bucket_index_max_shards`` in a gateway's region configuration. For example:: -To enable SSL on RPM-based distros, execute the following steps: + radosgw-admin region get > region.json -#. Ensure that you have installed the dependencies:: +Open the ``region.json`` file and edit the ``bucket_index_max_shards`` setting for each named zone. Save the ``region.json`` file and reset the region. For example:: - sudo yum install mod_ssl openssl + radosgw-admin region set < region.json -#. Generate private key:: +Once you've updated your region, update the region map. For example:: - openssl genrsa -out ca.key 2048 + radosgw-admin regionmap update --name client.rgw.ceph-client -#. Generate CSR:: +Where ``client.rgw.ceph-client`` is the name of the gateway user. - openssl req -new -key ca.key -out ca.csr +.. note:: Mapping the index pool (for each zone, if applicable) to a CRUSH ruleset of SSD-based OSDs may also help with bucket index performance. -#. Generate a certificate:: +Add Wildcard to DNS +------------------- - openssl x509 -req -days 365 -in ca.csr -signkey ca.key -out ca.crt +To use Ceph with S3-style subdomains (e.g., bucket-name.domain-name.com), you need to add a wildcard to the DNS record of the DNS server you use with the ``ceph-radosgw`` daemon. -#. Copy the files to appropriate locations:: +The address of the DNS must also be specified in the Ceph configuration file with the ``rgw dns name = {hostname}`` setting. - sudo cp ca.crt /etc/pki/tls/certs - sudo cp ca.key /etc/pki/tls/private/ca.key - sudo cp ca.csr /etc/pki/tls/private/ca.csr +For ``dnsmasq``, add the following address setting with a dot (.) prepended to the host name:: -#. Update the Apache SSL configuration file ``/etc/httpd/conf.d/ssl.conf``. + address=/.{hostname-or-fqdn}/{host-ip-address} - Give the correct location of ``SSLCertificateFile``:: +For example:: - SSLCertificateFile /etc/pki/tls/certs/ca.crt + address=/.gateway-node1/192.168.122.75 - Give the correct location of ``SSLCertificateKeyFile``:: - SSLCertificateKeyFile /etc/pki/tls/private/ca.key +For ``bind``, add a wildcard to the DNS record. For example:: - Save the changes. + $TTL 604800 + @ IN SOA gateway-node1. root.gateway-node1. ( + 2 ; Serial + 604800 ; Refresh + 86400 ; Retry + 2419200 ; Expire + 604800 ) ; Negative Cache TTL + ; + @ IN NS gateway-node1. + @ IN A 192.168.122.113 + * IN CNAME @ -#. Restart Apache. +Restart your DNS server and ping your server with a subdomain to ensure that your ``ceph-radosgw`` daemon can process the subdomain requests:: - Execute:: + ping mybucket.{hostname} - sudo service httpd restart +For example:: - Or:: + ping mybucket.gateway-node1 - sudo systemctl restart httpd +Add Debugging (if needed) +------------------------- -See `Setting up an SSL secured Webserver with CentOS`_ for additional details. +Once you finish the setup procedure, if you encounter issues with your configuration, you can add debugging to the ``[global]`` section of your Ceph configuration file and restart the gateway(s) to help troubleshoot any configuration issues. For example:: + [global] + #append the following in the global section. + debug ms = 1 + debug rgw = 20 -Install Ceph Object Gateway Daemon -================================== - -Ceph Object Storage services use the Ceph Object Gateway daemon (``radosgw``) -to enable the gateway. For federated architectures, the synchronization -agent (``radosgw-agent``) provides data and metadata synchronization between -zones and regions. - - -Debian-based distros --------------------- - -To install the Ceph Object Gateway daemon on the `gateway host`, execute the -following:: +Using The Gateway +----------------- - sudo apt-get install radosgw - +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. You then need to verify if the created users are able to access the gateway. + +Create a radosgw user for S3 access +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A ``radosgw`` user needs to be created and granted access. The command ``man radosgw-admin`` will provide information on additional command options. + +To create the user, execute the following on the ``gateway host``:: + + sudo radosgw-admin user create --uid="testuser" --display-name="First User" + +The output of the command will be something like the following:: + + { + "user_id": "testuser", + "display_name": "First User", + "email": "", + "suspended": 0, + "max_buckets": 1000, + "auid": 0, + "subusers": [], + "keys": [{ + "user": "testuser", + "access_key": "I0PJDPCIYZ665MW88W9R", + "secret_key": "dxaXZ8U90SXydYzyS5ivamEP20hkLSUViiaR+ZDA" + }], + "swift_keys": [], + "caps": [], + "op_mask": "read, write, delete", + "default_placement": "", + "placement_tags": [], + "bucket_quota": { + "enabled": false, + "max_size_kb": -1, + "max_objects": -1 + }, + "user_quota": { + "enabled": false, + "max_size_kb": -1, + "max_objects": -1 + }, + "temp_url_keys": [] + } + +.. note:: The values of ``keys->access_key`` and ``keys->secret_key`` are needed for access validation. + +.. important:: Check the key output. Sometimes ``radosgw-admin`` generates a JSON escape character ``\`` in ``access_key`` or ``secret_key`` and some clients do not know how to handle JSON escape characters. Remedies include removing the JSON escape character ``\``, encapsulating the string in quotes, regenerating the key and ensuring that it does not have a JSON escape character or specify the key and secret manually. Also, if ``radosgw-admin`` generates a JSON escape character ``\`` and a forward slash ``/`` together in a key, like ``\/``, only remove the JSON escape character ``\``. Do not remove the forward slash ``/`` as it is a valid character in the key. + +Create a Swift user +^^^^^^^^^^^^^^^^^^^ + +A Swift subuser needs to be created if this kind of access is needed. Creating a Swift user is a two step process. The first step is to create the user. The second is to create the secret key. + +Execute the following steps on the ``gateway host``: + +Create the Swift user:: + + sudo radosgw-admin subuser create --uid=testuser --subuser=testuser:swift --access=full + +The output will be something like the following:: + + { + "user_id": "testuser", + "display_name": "First User", + "email": "", + "suspended": 0, + "max_buckets": 1000, + "auid": 0, + "subusers": [{ + "id": "testuser:swift", + "permissions": "full-control" + }], + "keys": [{ + "user": "testuser:swift", + "access_key": "3Y1LNW4Q6X0Y53A52DET", + "secret_key": "" + }, { + "user": "testuser", + "access_key": "I0PJDPCIYZ665MW88W9R", + "secret_key": "dxaXZ8U90SXydYzyS5ivamEP20hkLSUViiaR+ZDA" + }], + "swift_keys": [], + "caps": [], + "op_mask": "read, write, delete", + "default_placement": "", + "placement_tags": [], + "bucket_quota": { + "enabled": false, + "max_size_kb": -1, + "max_objects": -1 + }, + "user_quota": { + "enabled": false, + "max_size_kb": -1, + "max_objects": -1 + }, + "temp_url_keys": [] + } + +Create the secret key:: + + sudo radosgw-admin key create --subuser=testuser:swift --key-type=swift --gen-secret + +The output will be something like the following:: + + { + "user_id": "testuser", + "display_name": "First User", + "email": "", + "suspended": 0, + "max_buckets": 1000, + "auid": 0, + "subusers": [{ + "id": "testuser:swift", + "permissions": "full-control" + }], + "keys": [{ + "user": "testuser:swift", + "access_key": "3Y1LNW4Q6X0Y53A52DET", + "secret_key": "" + }, { + "user": "testuser", + "access_key": "I0PJDPCIYZ665MW88W9R", + "secret_key": "dxaXZ8U90SXydYzyS5ivamEP20hkLSUViiaR+ZDA" + }], + "swift_keys": [{ + "user": "testuser:swift", + "secret_key": "244+fz2gSqoHwR3lYtSbIyomyPHf3i7rgSJrF\/IA" + }], + "caps": [], + "op_mask": "read, write, delete", + "default_placement": "", + "placement_tags": [], + "bucket_quota": { + "enabled": false, + "max_size_kb": -1, + "max_objects": -1 + }, + "user_quota": { + "enabled": false, + "max_size_kb": -1, + "max_objects": -1 + }, + "temp_url_keys": [] + } + +Access Verification +^^^^^^^^^^^^^^^^^^^ + +Test S3 access +"""""""""""""" + +You need to write and run a Python test script for verifying S3 access. The S3 access test script will connect to the ``radosgw``, create a new bucket and list all buckets. The values for ``aws_access_key_id`` and ``aws_secret_access_key`` are taken from the values of ``access_key`` and ``secret_key`` returned by the ``radosgw_admin`` command. + +Execute the following steps: + +#. You will need to install the ``python-boto`` package:: + + sudo yum install python-boto + +#. Create the Python script:: + + vi s3test.py + +#. Add the following contents to the file:: + + import boto + import boto.s3.connection + + access_key = 'I0PJDPCIYZ665MW88W9R' + secret_key = 'dxaXZ8U90SXydYzyS5ivamEP20hkLSUViiaR+ZDA' + conn = boto.connect_s3( + aws_access_key_id = access_key, + aws_secret_access_key = secret_key, + host = '{hostname}', port = {port}, + is_secure=False, calling_format = boto.s3.connection.OrdinaryCallingFormat(), ) + + bucket = conn.create_bucket('my-new-bucket') + for bucket in conn.get_all_buckets(): + print "{name}".format( + name = bucket.name, + created = bucket.creation_date, + ) + + Replace ``{hostname}`` with the hostname of the host where you have configured the gateway service i.e, the ``gateway host``. Replace {port} with the port number you are using with Civetweb. + +#. Run the script:: + + python s3test.py -To install the Ceph Object Gateway synchronization agent, execute the -following:: - - sudo apt-get install radosgw-agent + The output will be something like the following:: + my-new-bucket 2015-02-16T17:09:10.000Z -RPM-based distros ------------------ +Test swift access +""""""""""""""""" -To install the Ceph Object Gateway daemon on the ``gateway host``, execute the -following:: +Swift access can be verified via the ``swift`` command line client. The command ``man swift`` will provide more information on available command line options. - sudo yum install ceph-radosgw +To install ``swift`` client, execute the following:: + sudo yum install python-setuptools + sudo easy_install pip + sudo pip install --upgrade setuptools + sudo pip install --upgrade python-swiftclient -To install the Ceph Object Gateway synchronization agent, execute the -following:: +To test swift access, execute the following:: - sudo yum install radosgw-agent - - -Configure The Gateway -===================== + swift -A http://{IP ADDRESS}:{port}/auth/1.0 -U testuser:swift -K '{swift_secret_key}' list -Once you have installed the Ceph Object Gateway packages, the next step is -to configure your Ceph Object Gateway. There are two approaches: +Replace ``{IP ADDRESS}`` with the public IP address of the gateway server and ``{swift_secret_key}`` with its value from the output of ``radosgw-admin key create`` command executed for the ``swift`` user. Replace {port} with the port number you are using with Civetweb (e.g., ``7480`` is the default). If you don't replace the port, it will default to port ``80``. -- **Simple:** A `simple`_ Ceph Object Gateway configuration implies that you - are running a Ceph Object Storage service in a single data center. So you can - configure the Ceph Object Gateway without regard to regions and zones. +For example:: -- **Federated:** A `federated`_ Ceph Object Gateway configuration implies that - you are running a Ceph Object Storage service in a geographically distributed - manner for fault tolerance and failover. This involves configuring your - Ceph Object Gateway instances with regions and zones. + swift -A http://10.19.143.116:7480/auth/1.0 -U testuser:swift -K '244+fz2gSqoHwR3lYtSbIyomyPHf3i7rgSJrF/IA' list -Choose the approach that best reflects your cluster. +The output should be:: -.. _ceph radosgw needs mod-proxy-fcgi for apache 2.2: https://bugs.launchpad.net/precise-backports/+bug/1422417 -.. _Ubuntu Server Guide: https://help.ubuntu.com/12.04/serverguide/httpd.html -.. _Setting up an SSL secured Webserver with CentOS: http://wiki.centos.org/HowTos/Https -.. _simple: ../../radosgw/config -.. _federated: ../../radosgw/federated-config + my-new-bucket diff --git a/doc/install/install-ceph-gateway_old.rst b/doc/install/install-ceph-gateway_old.rst new file mode 100644 index 00000000000..ded9f35d643 --- /dev/null +++ b/doc/install/install-ceph-gateway_old.rst @@ -0,0 +1,255 @@ +============================= + Install Ceph Object Gateway +============================= + +.. note:: To run the Ceph object gateway service, you should have a running + Ceph cluster, the gateway host should have access to storage and public + networks, and SELinux should be in permissive mode in rpm-based distros. + +The :term:`Ceph Object Gateway` daemon runs on Apache and FastCGI. + +To run a :term:`Ceph Object Storage` service, you must install Apache and +Ceph Object Gateway daemon on the host that is going to provide the gateway +service, i.e, the ``gateway host``. If you plan to run a Ceph Object Storage +service with a federated architecture (multiple regions and zones), you must +also install the synchronization agent. + +.. note:: Previous versions of Ceph shipped with ``mod_fastcgi``. The current + version ships with ``mod_proxy_fcgi`` instead. + +In distros that ship Apache 2.4 (such as RHEL 7, CentOS 7 or Ubuntu 14.04 +``Trusty``), ``mod_proxy_fcgi`` is already present. When you install the +``httpd`` package with ``yum`` or the ``apache2`` package with ``apt-get``, +``mod_proxy_fcgi`` becomes available for use on your server. + +In distros that ship Apache 2.2 (such as RHEL 6, CentOS 6 or Ubuntu 12.04 +``Precise``), ``mod_proxy_fcgi`` comes as a separate package. In +**RHEL 6/CentOS 6**, it is available in ``EPEL 6`` repo and can be installed with +``yum install mod_proxy_fcgi``. For **Ubuntu 12.04**, a backport for +``mod_proxy_fcgi`` is in progress and a bug has been filed for the same. +See: `ceph radosgw needs mod-proxy-fcgi for apache 2.2`_ + + +Install Apache +============== + +To install Apache on the ``gateway host``, execute the following: + +On Debian-based distros, run:: + + sudo apt-get install apache2 + +On RPM-based distros, run:: + + sudo yum install httpd + + +Configure Apache +================ + +Make the following changes in Apache's configuration on the ``gateway host``: + +Debian-based distros +-------------------- + +#. Add a line for the ``ServerName`` in ``/etc/apache2/apache2.conf``. Provide + the fully qualified domain name of the server machine + (e.g., ``hostname -f``):: + + ServerName {fqdn} + +#. Load ``mod_proxy_fcgi`` module. + + Execute:: + + sudo a2enmod proxy_fcgi + +#. Start Apache service:: + + sudo service apache2 start + +RPM-based distros +----------------- + +#. Open the ``httpd.conf`` file:: + + sudo vim /etc/httpd/conf/httpd.conf + +#. Uncomment ``#ServerName`` in the file and add the name of your server. Provide + the fully qualified domain name of the server machine + (e.g., ``hostname -f``):: + + ServerName {fqdn} + +#. Update ``/etc/httpd/conf/httpd.conf`` to load ``mod_proxy_fcgi`` module. Add + the following to the file:: + + + LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so + + +#. Edit the line ``Listen 80`` in ``/etc/httpd/conf/httpd.conf`` with the public + IP address of the host that you are configuring as a gateway server. Write + ``Listen {IP ADDRESS}:80`` in place of ``Listen 80``. + +#. Start httpd service + + Execute:: + + sudo service httpd start + + Or:: + + sudo systemctl start httpd + + +Enable SSL +========== + +Some REST clients use HTTPS by default. So you should consider enabling SSL +for Apache. Use the following procedures to enable SSL. + +.. note:: You can use self-certified certificates. Some client + APIs check for a trusted certificate authority. You may need to obtain + a SSL certificate from a trusted authority to use those client APIs. + + +Debian-based distros +-------------------- + +To enable SSL on Debian-based distros, execute the following steps: + +#. Ensure that you have installed the dependencies:: + + sudo apt-get install openssl ssl-cert + +#. Enable the SSL module:: + + sudo a2enmod ssl + +#. Generate a certificate:: + + sudo mkdir /etc/apache2/ssl + sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt + +#. Restart Apache:: + + sudo service apache2 restart + + +See the `Ubuntu Server Guide`_ for additional details. + + +RPM-based distros +----------------- + +To enable SSL on RPM-based distros, execute the following steps: + +#. Ensure that you have installed the dependencies:: + + sudo yum install mod_ssl openssl + +#. Generate private key:: + + openssl genrsa -out ca.key 2048 + +#. Generate CSR:: + + openssl req -new -key ca.key -out ca.csr + +#. Generate a certificate:: + + openssl x509 -req -days 365 -in ca.csr -signkey ca.key -out ca.crt + +#. Copy the files to appropriate locations:: + + sudo cp ca.crt /etc/pki/tls/certs + sudo cp ca.key /etc/pki/tls/private/ca.key + sudo cp ca.csr /etc/pki/tls/private/ca.csr + +#. Update the Apache SSL configuration file ``/etc/httpd/conf.d/ssl.conf``. + + Give the correct location of ``SSLCertificateFile``:: + + SSLCertificateFile /etc/pki/tls/certs/ca.crt + + Give the correct location of ``SSLCertificateKeyFile``:: + + SSLCertificateKeyFile /etc/pki/tls/private/ca.key + + Save the changes. + +#. Restart Apache. + + Execute:: + + sudo service httpd restart + + Or:: + + sudo systemctl restart httpd + +See `Setting up an SSL secured Webserver with CentOS`_ for additional details. + + +Install Ceph Object Gateway Daemon +================================== + +Ceph Object Storage services use the Ceph Object Gateway daemon (``radosgw``) +to enable the gateway. For federated architectures, the synchronization +agent (``radosgw-agent``) provides data and metadata synchronization between +zones and regions. + + +Debian-based distros +-------------------- + +To install the Ceph Object Gateway daemon on the `gateway host`, execute the +following:: + + sudo apt-get install radosgw + + +To install the Ceph Object Gateway synchronization agent, execute the +following:: + + sudo apt-get install radosgw-agent + + +RPM-based distros +----------------- + +To install the Ceph Object Gateway daemon on the ``gateway host``, execute the +following:: + + sudo yum install ceph-radosgw + + +To install the Ceph Object Gateway synchronization agent, execute the +following:: + + sudo yum install radosgw-agent + + +Configure The Gateway +===================== + +Once you have installed the Ceph Object Gateway packages, the next step is +to configure your Ceph Object Gateway. There are two approaches: + +- **Simple:** A `simple`_ Ceph Object Gateway configuration implies that you + are running a Ceph Object Storage service in a single data center. So you can + configure the Ceph Object Gateway without regard to regions and zones. + +- **Federated:** A `federated`_ Ceph Object Gateway configuration implies that + you are running a Ceph Object Storage service in a geographically distributed + manner for fault tolerance and failover. This involves configuring your + Ceph Object Gateway instances with regions and zones. + +Choose the approach that best reflects your cluster. + +.. _ceph radosgw needs mod-proxy-fcgi for apache 2.2: https://bugs.launchpad.net/precise-backports/+bug/1422417 +.. _Ubuntu Server Guide: https://help.ubuntu.com/12.04/serverguide/httpd.html +.. _Setting up an SSL secured Webserver with CentOS: http://wiki.centos.org/HowTos/Https +.. _simple: ../../radosgw/config +.. _federated: ../../radosgw/federated-config -- 2.47.3