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    Please note, ``Apache 2.4.7`` does not have Unix Domain Socket support in
 186    it and as such it has to be configured with localhost tcp. The Unix Domain
 187    Socket support is available in ``Apache 2.4.9`` and later versions.
 188
 189 #. Generate a key for radosgw to use for authentication with the cluster. ::
 190
 191         ceph-authtool -C -n client.radosgw.gateway --gen-key /etc/ceph/keyring.radosgw.gateway
 192         ceph-authtool -n client.radosgw.gateway --cap mon 'allow rw' --cap osd 'allow rwx' /etc/ceph/keyring.radosgw.gateway
 193
 194 #. Add the key to the auth entries. ::
 195
 196         ceph auth add client.radosgw.gateway --in-file=keyring.radosgw.gateway
 197
 198 #. Start Apache and radosgw.
 199
 200    Debian/Ubuntu::
 201
 202                 sudo /etc/init.d/apache2 start
 203                 sudo /etc/init.d/radosgw start
 204
 205    CentOS/RHEL::
 206
 207                 sudo apachectl start
 208                 sudo /etc/init.d/ceph-radosgw start
 209
 210 Usage Logging
 211 =============
 212
 213 :program:`radosgw` maintains an asynchronous usage log. It accumulates
 214 statistics about user operations and flushes it periodically. The
 215 logs can be accessed and managed through :program:`radosgw-admin`.
 216
 217 The information that is being logged contains total data transfer,
 218 total operations, and total successful operations. The data is being
 219 accounted in an hourly resolution under the bucket owner, unless the
 220 operation was done on the service (e.g., when listing a bucket) in
 221 which case it is accounted under the operating user.
 222
 223 Following is an example configuration::
 224
 225         [client.radosgw.gateway]
 226             rgw enable usage log = true
 227             rgw usage log tick interval = 30
 228             rgw usage log flush threshold = 1024
 229             rgw usage max shards = 32
 230             rgw usage max user shards = 1
 231
 232
 233 The total number of shards determines how many total objects hold the
 234 usage log information. The per-user number of shards specify how many
 235 objects hold usage information for a single user. The tick interval
 236 configures the number of seconds between log flushes, and the flush
 237 threshold specify how many entries can be kept before resorting to
 238 synchronous flush.
 239
 240
 241 Availability
 242 ============
 243
 244 :program:`radosgw` is part of Ceph, a massively scalable, open-source, distributed
 245 storage system. Please refer to the Ceph documentation at https://docs.ceph.com for
 246 more information.
 247
 248
 249 See also
 250 ========
 251
 252 :doc:`ceph <ceph>`\(8)
 253 :doc:`radosgw-admin <radosgw-admin>`\(8)