+++ /dev/null
-============================
- Object Storage Quick Start
-============================
-
-To use this guide, you must have executed the procedures in the `Storage Cluster
-Quick Start`_ guide first. Ensure your :term:`Ceph Storage Cluster` is in an
-``active + clean`` state before working with the :term:`Ceph Object Storage`.
-
-.. note:: Ceph Object Storage is also referred to as RADOS Gateway.
-
-
-Install Apache and FastCGI
-==========================
-
-:term:`Ceph Object Storage` runs on Apache and FastCGI in conjunction with the
-:term:`Ceph Storage Cluster`. Install Apache and FastCGI on the server node. Use
-the following procedure:
-
-#. Install Apache and FastCGI on the server machine. ::
-
- sudo apt-get update && sudo apt-get install apache2 libapache2-mod-fastcgi
-
-#. Enable the URL rewrite modules for Apache and FastCGI. ::
-
- sudo a2enmod rewrite
- sudo a2enmod fastcgi
-
-#. Add a line for the ``ServerName`` in the Apache configuration file
- (e.g., ``/etc/apache2/httpd.conf`` or ``/etc/apache2/apache2.conf``).
- Provide the fully qualified domain name of the server machine
- (e.g., ``hostname -f``). ::
-
- ServerName {fqdn}
-
-#. Restart Apache so that the foregoing changes take effect. ::
-
- sudo service apache2 restart
-
-
-Install Ceph Object Storage
-===========================
-
-Once you have installed and configured Apache and FastCGI, you may install
-the Ceph Object Storage daemon (``radosgw``). ::
-
- sudo apt-get install radosgw
-
-For details on the preceding steps, see `Ceph Object Storage Manual Install`_.
-
-
-Create a Data Directory
-=======================
-
-Create a data directory on the server node for the instance of ``radosgw``.
-
-::
-
- sudo mkdir -p /var/lib/ceph/radosgw/ceph-radosgw.gateway
-
-
-Modify the Ceph Configuration File
-==================================
-
-On the admin node, perform the following steps:
-
-#. Open the Ceph configuration file. ::
-
- vim ceph.conf
-
-#. Add the following settings to the Ceph configuration file::
-
- [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
-
- #Add DNS hostname to enable S3 subdomain calls
- rgw dns name = {hostname}
-
-#. Use ``ceph-deploy`` to push a copy the configuration file from the admin
- node to the server node. ::
-
- ceph-deploy --overwrite-conf config push {hostname}
-
-
-Create a Gateway Configuration File
-===================================
-
-The example configuration file will configure the gateway on the server node to
-operate with the Apache FastCGI module, a rewrite rule for OpenStack Swift, and
-paths for the log files. To add a configuration file for Ceph Object Storage,
-we suggest copying the contents of the example file below to an editor. Then,
-follow the steps below to modify it (on your server node).
-
-.. literalinclude:: rgw.conf
- :language: ini
-
-#. Replace the ``{fqdn}`` entry with the fully-qualified domain name of the
- server 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.
-
-#. Save the contents to the ``/etc/apache2/sites-available`` directory on
- the server machine.
-
-#. Enable the site for ``rgw.conf``. ::
-
- sudo a2ensite rgw.conf
-
-#. Disable the default site. ::
-
- sudo a2dissite default
-
-See `Create rgw.conf`_ for additional details.
-
-
-Add a FastCGI Script
-====================
-
-FastCGI requires a script for the S3-compatible interface. To create the
-script, execute the following procedures on the server node.
-
-#. Go to the ``/var/www`` directory. ::
-
- cd /var/www
-
-#. Open an editor with the file name ``s3gw.fcgi``. ::
-
- sudo vim s3gw.fcgi
-
-#. Copy the following into the editor. ::
-
- #!/bin/sh
- exec /usr/bin/radosgw -c /etc/ceph/ceph.conf -n client.radosgw.gateway
-
-#. Save the file.
-
-#. Change the permissions on the file so that it is executable. ::
-
- sudo chmod +x s3gw.fcgi
-
-
-Generate a Keyring and Key
-==========================
-
-Perform the following steps on the server machine.
-
-#. Ensure the server node is set up with administrator privileges. From
- the admin node, execute the following::
-
- ceph-deploy admin {hostname}
-
-#. Create a keyring for Ceph Object Storage. ::
-
- sudo ceph-authtool --create-keyring /etc/ceph/keyring.radosgw.gateway
- sudo chmod +r /etc/ceph/keyring.radosgw.gateway
-
-#. Create a key for Ceph Object Storage to authenticate with the Ceph Storage
- Cluster. ::
-
- 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
-
-#. Add the key to the Ceph keyring. ::
-
- sudo ceph -k /etc/ceph/ceph.client.admin.keyring auth add client.radosgw.gateway -i /etc/ceph/keyring.radosgw.gateway
-
-
-Enable SSL
-==========
-
-Some REST clients use HTTPS by default. So you should consider enabling SSL
-for Apache on the server machine. ::
-
- sudo a2enmod ssl
-
-Once you enable SSL, you should use a trusted SSL certificate. You can
-generate a non-trusted SSL certificate using the following::
-
- 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
-
-Then, restart Apache. ::
-
- service apache2 restart
-
-
-Add Wildcard to DNS
-===================
-
-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
-``radosgw`` daemon.
-
-.. tip:: The address of the DNS must also be specified in the Ceph
- configuration file with the ``rgw dns name = {hostname}`` setting.
-
-For ``dnsmasq``, consider addding the following ``address`` setting with a dot
-(.) prepended to the host name::
-
- address=/.{hostname-or-fqdn}/{host-ip-address}
- address=/.ceph-node/192.168.0.1
-
-For ``bind``, consider adding the a wildcard to the DNS record::
-
- $TTL 604800
- @ IN SOA ceph-node. root.ceph-node. (
- 2 ; Serial
- 604800 ; Refresh
- 86400 ; Retry
- 2419200 ; Expire
- 604800 ) ; Negative Cache TTL
- ;
- @ IN NS ceph-node.
- @ IN A 192.168.122.113
- * IN CNAME @
-
-Restart your DNS server and ping your server with a subdomain to
-ensure that your Ceph Object Store ``radosgw`` daemon can process
-the subdomain requests. ::
-
- ping mybucket.{fqdn}
- ping mybucket.ceph-node
-
-
-Restart Services
-================
-
-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::
-
- sudo service ceph restart
- sudo service apache2 restart
- sudo /etc/init.d/radosgw start
-
-
-Create a User
-=============
-
-To use the Gateway, you must create a Gateway user. First, create a gateway user
-for the S3-compatible interface; then, create a subuser for the
-Swift-compatible interface.
-
-Gateway (S3) User
------------------
-
-First, create a Gateway user for the S3-compatible interface. ::
-
- sudo radosgw-admin user create --uid="{username}" --display-name="{Display Name}"
-
-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 creates an access_key and secret_key entry for use with any S3
-API-compatible client.
-
-.. 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.
-
-Subuser
--------
-
-Next, create a subuser for the Swift-compatible interface. ::
-
- sudo radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full
-
-.. code-block:: javascript
-
- { "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": []}
-
-::
-
- sudo radosgw-admin key create --subuser=johndoe:swift --key-type=swift --gen-secret
-
-.. code-block:: javascript
-
- { "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 RADOS
-Gateway via the Swift-compatible API.
-
-RGW's ``user:subuser`` tuple maps to the ``tenant:user`` tuple expected by Swift.
-
-.. note:: RGW's Swift authentication service only supports
- built-in Swift authentication (``-V 1.0``) at this point. See
- `RGW Configuration`_ for Keystone integration details.
-
-
-Summary
--------
-
-Once you have completed this Quick Start, you may use the Ceph Object Store
-tutorials. See the `S3-compatible`_ and `Swift-compatible`_ APIs for details.
-
-
-.. _Create rgw.conf: ../../radosgw/config/index.html#create-rgw-conf
-.. _Storage Cluster Quick Start: ../quick-ceph-deploy
-.. _Ceph Object Storage Manual Install: ../../radosgw/manual-install
-.. _RGW Configuration: ../../radosgw/config
-.. _S3-compatible: ../../radosgw/s3
-.. _Swift-compatible: ../../radosgw/swift
projects / ceph.git / commitdiff