src/ceph/doc/man/8/radosgw.rst

   1 :orphan:
   2
   3 ===============================
   4  radosgw -- rados REST gateway
   5 ===============================
   6
   7 .. program:: radosgw
   8
   9 Synopsis
  10 ========
  11
  12 | **radosgw**
  13
  14
  15 Description
  16 ===========
  17
  18 :program:`radosgw` is an HTTP REST gateway for the RADOS object store, a part
  19 of the Ceph distributed storage system. It is implemented as a FastCGI
  20 module using libfcgi, and can be used in conjunction with any FastCGI
  21 capable web server.
  22
  23
  24 Options
  25 =======
  26
  27 .. option:: -c ceph.conf, --conf=ceph.conf
  28
  29    Use ``ceph.conf`` configuration file instead of the default
  30    ``/etc/ceph/ceph.conf`` to determine monitor addresses during startup.
  31
  32 .. option:: -m monaddress[:port]
  33
  34    Connect to specified monitor (instead of looking through ``ceph.conf``).
  35
  36 .. option:: -i ID, --id ID
  37
  38    Set the ID portion of name for radosgw
  39
  40 .. option:: -n TYPE.ID, --name TYPE.ID
  41
  42    Set the rados user name for the gateway (eg. client.radosgw.gateway)
  43
  44 .. option:: --cluster NAME
  45
  46    Set the cluster name (default: ceph)
  47
  48 .. option:: -d
  49
  50    Run in foreground, log to stderr
  51
  52 .. option:: -f
  53
  54    Run in foreground, log to usual location
  55
  56 .. option:: --rgw-socket-path=path
  57
  58    Specify a unix domain socket path.
  59
  60 .. option:: --rgw-region=region
  61
  62    The region where radosgw runs
  63
  64 .. option:: --rgw-zone=zone
  65
  66    The zone where radosgw runs
  67
  68
  69 Configuration
  70 =============
  71
  72 Earlier RADOS Gateway had to be configured with ``Apache`` and ``mod_fastcgi``.
  73 Now, ``mod_proxy_fcgi`` module is used instead of ``mod_fastcgi``.
  74 ``mod_proxy_fcgi`` works differently than a traditional FastCGI module. This
  75 module requires the service of ``mod_proxy`` which provides support for the
  76 FastCGI protocol. So, to be able to handle FastCGI protocol, both ``mod_proxy``
  77 and ``mod_proxy_fcgi`` have to be present in the server. Unlike ``mod_fastcgi``,
  78 ``mod_proxy_fcgi`` cannot start the application process. Some platforms have
  79 ``fcgistarter`` for that purpose. However, external launching of application
  80 or process management may be available in the FastCGI application framework
  81 in use.
  82
  83 ``Apache`` can be configured in a way that enables ``mod_proxy_fcgi`` to be used
  84 with localhost tcp or through unix domain socket. ``mod_proxy_fcgi`` that doesn't
  85 support unix domain socket such as the ones in Apache 2.2 and earlier versions of
  86 Apache 2.4, needs to be configured for use with localhost tcp. Later versions of
  87 Apache like Apache 2.4.9 or later support unix domain socket and as such they
  88 allow for the configuration with unix domain socket instead of localhost tcp.
  89
  90 The following steps show the configuration in Ceph's configuration file i.e,
  91 ``/etc/ceph/ceph.conf`` and the gateway configuration file i.e,
  92 ``/etc/httpd/conf.d/rgw.conf`` (RPM-based distros) or
  93 ``/etc/apache2/conf-available/rgw.conf`` (Debian-based distros) with localhost
  94 tcp and through unix domain socket:
  95
  96 #. For distros with Apache 2.2 and early versions of Apache 2.4 that use
  97    localhost TCP and do not support Unix Domain Socket, append the following
  98    contents to ``/etc/ceph/ceph.conf``::
  99
 100         [client.radosgw.gateway]
 101         host = {hostname}
 102         keyring = /etc/ceph/ceph.client.radosgw.keyring
 103         rgw socket path = ""
 104         log file = /var/log/ceph/client.radosgw.gateway.log
 105         rgw frontends = fastcgi socket_port=9000 socket_host=0.0.0.0
 106         rgw print continue = false
 107
 108 #. Add the following content in the gateway configuration file:
 109
 110    For Debian/Ubuntu add in ``/etc/apache2/conf-available/rgw.conf``::
 111
 112                 <VirtualHost *:80>
 113                 ServerName localhost
 114                 DocumentRoot /var/www/html
 115
 116                 ErrorLog /var/log/apache2/rgw_error.log
 117                 CustomLog /var/log/apache2/rgw_access.log combined
 118
 119                 # LogLevel debug
 120
 121                 RewriteEngine On
 122
 123                 RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
 124
 125                 SetEnv proxy-nokeepalive 1
 126
 127                 ProxyPass / fcgi://localhost:9000/
 128
 129                 </VirtualHost>
 130
 131    For CentOS/RHEL add in ``/etc/httpd/conf.d/rgw.conf``::
 132
 133                 <VirtualHost *:80>
 134                 ServerName localhost
 135                 DocumentRoot /var/www/html
 136
 137                 ErrorLog /var/log/httpd/rgw_error.log
 138                 CustomLog /var/log/httpd/rgw_access.log combined
 139
 140                 # LogLevel debug
 141
 142                 RewriteEngine On
 143
 144                 RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
 145
 146                 SetEnv proxy-nokeepalive 1
 147
 148                 ProxyPass / fcgi://localhost:9000/
 149
 150                 </VirtualHost>
 151
 152 #. For distros with Apache 2.4.9 or later that support Unix Domain Socket,
 153    append the following configuration to ``/etc/ceph/ceph.conf``::
 154
 155         [client.radosgw.gateway]
 156         host = {hostname}
 157         keyring = /etc/ceph/ceph.client.radosgw.keyring
 158         rgw socket path = /var/run/ceph/ceph.radosgw.gateway.fastcgi.sock
 159         log file = /var/log/ceph/client.radosgw.gateway.log
 160         rgw print continue = false
 161
 162 #. Add the following content in the gateway configuration file:
 163
 164    For CentOS/RHEL add in ``/etc/httpd/conf.d/rgw.conf``::
 165
 166                 <VirtualHost *:80>
 167                 ServerName localhost
 168                 DocumentRoot /var/www/html
 169
 170                 ErrorLog /var/log/httpd/rgw_error.log
 171                 CustomLog /var/log/httpd/rgw_access.log combined
 172
 173                 # LogLevel debug
 174
 175                 RewriteEngine On
 176
 177                 RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
 178
 179                 SetEnv proxy-nokeepalive 1
 180
 181                 ProxyPass / unix:///var/run/ceph/ceph.radosgw.gateway.fastcgi.sock|fcgi://localhost:9000/
 182
 183                 </VirtualHost>
 184
 185    The latest version of Ubuntu i.e, 14.04 ships with ``Apache 2.4.7`` that
 186    does not have Unix Domain Socket support in it and as such it has to be
 187    configured with localhost tcp. The Unix Domain Socket support is available in
 188    ``Apache 2.4.9`` and later versions. A bug has been filed to backport the UDS
 189    support to ``Apache 2.4.7`` for ``Ubuntu 14.04``.
 190    See: https://bugs.launchpad.net/ubuntu/+source/apache2/+bug/1411030
 191
 192 #. Generate a key for radosgw to use for authentication with the cluster. ::
 193
 194         ceph-authtool -C -n client.radosgw.gateway --gen-key /etc/ceph/keyring.radosgw.gateway
 195         ceph-authtool -n client.radosgw.gateway --cap mon 'allow rw' --cap osd 'allow rwx' /etc/ceph/keyring.radosgw.gateway
 196
 197 #. Add the key to the auth entries. ::
 198
 199         ceph auth add client.radosgw.gateway --in-file=keyring.radosgw.gateway
 200
 201 #. Start Apache and radosgw.
 202
 203    Debian/Ubuntu::
 204
 205                 sudo /etc/init.d/apache2 start
 206                 sudo /etc/init.d/radosgw start
 207
 208    CentOS/RHEL::
 209
 210                 sudo apachectl start
 211                 sudo /etc/init.d/ceph-radosgw start
 212
 213 Usage Logging
 214 =============
 215
 216 :program:`radosgw` maintains an asynchronous usage log. It accumulates
 217 statistics about user operations and flushes it periodically. The
 218 logs can be accessed and managed through :program:`radosgw-admin`.
 219
 220 The information that is being logged contains total data transfer,
 221 total operations, and total successful operations. The data is being
 222 accounted in an hourly resolution under the bucket owner, unless the
 223 operation was done on the service (e.g., when listing a bucket) in
 224 which case it is accounted under the operating user.
 225
 226 Following is an example configuration::
 227
 228         [client.radosgw.gateway]
 229             rgw enable usage log = true
 230             rgw usage log tick interval = 30
 231             rgw usage log flush threshold = 1024
 232             rgw usage max shards = 32
 233             rgw usage max user shards = 1
 234
 235
 236 The total number of shards determines how many total objects hold the
 237 usage log information. The per-user number of shards specify how many
 238 objects hold usage information for a single user. The tick interval
 239 configures the number of seconds between log flushes, and the flush
 240 threshold specify how many entries can be kept before resorting to
 241 synchronous flush.
 242
 243
 244 Availability
 245 ============
 246
 247 :program:`radosgw` is part of Ceph, a massively scalable, open-source, distributed
 248 storage system. Please refer to the Ceph documentation at http://ceph.com/docs for
 249 more information.
 250
 251
 252 See also
 253 ========
 254
 255 :doc:`ceph <ceph>`\(8)
 256 :doc:`radosgw-admin <radosgw-admin>`\(8)