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-region=region
  57
  58    The region where radosgw runs
  59
  60 .. option:: --rgw-zone=zone
  61
  62    The zone where radosgw runs
  63
  64
  65 Configuration
  66 =============
  67
  68 Earlier RADOS Gateway had to be configured with ``Apache`` and ``mod_fastcgi``.
  69 Now, ``mod_proxy_fcgi`` module is used instead of ``mod_fastcgi``.
  70 ``mod_proxy_fcgi`` works differently than a traditional FastCGI module. This
  71 module requires the service of ``mod_proxy`` which provides support for the
  72 FastCGI protocol. So, to be able to handle FastCGI protocol, both ``mod_proxy``
  73 and ``mod_proxy_fcgi`` have to be present in the server. Unlike ``mod_fastcgi``,
  74 ``mod_proxy_fcgi`` cannot start the application process. Some platforms have
  75 ``fcgistarter`` for that purpose. However, external launching of application
  76 or process management may be available in the FastCGI application framework
  77 in use.
  78
  79 ``Apache`` must be configured in a way that enables ``mod_proxy_fcgi`` to be
  80 used with localhost tcp.
  81
  82 The following steps show the configuration in Ceph's configuration file i.e,
  83 ``/etc/ceph/ceph.conf`` and the gateway configuration file i.e,
  84 ``/etc/httpd/conf.d/rgw.conf`` (RPM-based distros) or
  85 ``/etc/apache2/conf-available/rgw.conf`` (Debian-based distros) with localhost
  86 tcp:
  87
  88 #. For distros with Apache 2.2 and early versions of Apache 2.4 that use
  89    localhost TCP, append the following contents to ``/etc/ceph/ceph.conf``::
  90
  91         [client.radosgw.gateway]
  92         host = {hostname}
  93         keyring = /etc/ceph/ceph.client.radosgw.keyring
  94         log_file = /var/log/ceph/client.radosgw.gateway.log
  95         rgw_frontends = fastcgi socket_port=9000 socket_host=0.0.0.0
  96         rgw_print_continue = false
  97
  98 #. Add the following content in the gateway configuration file:
  99
 100    For Debian/Ubuntu add in ``/etc/apache2/conf-available/rgw.conf``::
 101
 102                 <VirtualHost *:80>
 103                 ServerName localhost
 104                 DocumentRoot /var/www/html
 105
 106                 ErrorLog /var/log/apache2/rgw_error.log
 107                 CustomLog /var/log/apache2/rgw_access.log combined
 108
 109                 # LogLevel debug
 110
 111                 RewriteEngine On
 112
 113                 RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
 114
 115                 SetEnv proxy-nokeepalive 1
 116
 117                 ProxyPass / fcgi://localhost:9000/
 118
 119                 </VirtualHost>
 120
 121    For CentOS/RHEL add in ``/etc/httpd/conf.d/rgw.conf``::
 122
 123                 <VirtualHost *:80>
 124                 ServerName localhost
 125                 DocumentRoot /var/www/html
 126
 127                 ErrorLog /var/log/httpd/rgw_error.log
 128                 CustomLog /var/log/httpd/rgw_access.log combined
 129
 130                 # LogLevel debug
 131
 132                 RewriteEngine On
 133
 134                 RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
 135
 136                 SetEnv proxy-nokeepalive 1
 137
 138                 ProxyPass / fcgi://localhost:9000/
 139
 140                 </VirtualHost>
 141
 142 #. Add the following content in the gateway configuration file:
 143
 144    For CentOS/RHEL add in ``/etc/httpd/conf.d/rgw.conf``::
 145
 146                 <VirtualHost *:80>
 147                 ServerName localhost
 148                 DocumentRoot /var/www/html
 149
 150                 ErrorLog /var/log/httpd/rgw_error.log
 151                 CustomLog /var/log/httpd/rgw_access.log combined
 152
 153                 # LogLevel debug
 154
 155                 RewriteEngine On
 156
 157                 RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
 158
 159                 SetEnv proxy-nokeepalive 1
 160
 161                 ProxyPass / unix:///var/run/ceph/ceph.radosgw.gateway.fastcgi.sock|fcgi://localhost:9000/
 162
 163                 </VirtualHost>
 164
 165 #. Generate a key for radosgw to use for authentication with the cluster. ::
 166
 167         ceph-authtool -C -n client.radosgw.gateway --gen-key /etc/ceph/keyring.radosgw.gateway
 168         ceph-authtool -n client.radosgw.gateway --cap mon 'allow rw' --cap osd 'allow rwx' /etc/ceph/keyring.radosgw.gateway
 169
 170 #. Add the key to the auth entries. ::
 171
 172         ceph auth add client.radosgw.gateway --in-file=keyring.radosgw.gateway
 173
 174 #. Start Apache and radosgw.
 175
 176    Debian/Ubuntu::
 177
 178                 sudo /etc/init.d/apache2 start
 179                 sudo /etc/init.d/radosgw start
 180
 181    CentOS/RHEL::
 182
 183                 sudo apachectl start
 184                 sudo /etc/init.d/ceph-radosgw start
 185
 186 Usage Logging
 187 =============
 188
 189 :program:`radosgw` maintains an asynchronous usage log. It accumulates
 190 statistics about user operations and flushes it periodically. The
 191 logs can be accessed and managed through :program:`radosgw-admin`.
 192
 193 The information that is being logged contains total data transfer,
 194 total operations, and total successful operations. The data is being
 195 accounted in an hourly resolution under the bucket owner, unless the
 196 operation was done on the service (e.g., when listing a bucket) in
 197 which case it is accounted under the operating user.
 198
 199 Following is an example configuration::
 200
 201         [client.radosgw.gateway]
 202             rgw enable usage log = true
 203             rgw usage log tick interval = 30
 204             rgw usage log flush threshold = 1024
 205             rgw usage max shards = 32
 206             rgw usage max user shards = 1
 207
 208
 209 The total number of shards determines how many total objects hold the
 210 usage log information. The per-user number of shards specify how many
 211 objects hold usage information for a single user. The tick interval
 212 configures the number of seconds between log flushes, and the flush
 213 threshold specify how many entries can be kept before resorting to
 214 synchronous flush.
 215
 216
 217 Availability
 218 ============
 219
 220 :program:`radosgw` is part of Ceph, a massively scalable, open-source, distributed
 221 storage system. Please refer to the Ceph documentation at https://docs.ceph.com for
 222 more information.
 223
 224
 225 See also
 226 ========
 227
 228 :doc:`ceph <ceph>`\(8)
 229 :doc:`radosgw-admin <radosgw-admin>`\(8)