ceph/doc/radosgw/frontends.rst

   1 .. _rgw_frontends:
   2
   3 ==============
   4 HTTP Frontends
   5 ==============
   6
   7 .. contents::
   8
   9 The Ceph Object Gateway supports two embedded HTTP frontend libraries
  10 that can be configured with ``rgw_frontends``. See `Config Reference`_
  11 for details about the syntax.
  12
  13 Beast
  14 =====
  15
  16 .. versionadded:: Mimic
  17
  18 The ``beast`` frontend uses the Boost.Beast library for HTTP parsing
  19 and the Boost.Asio library for asynchronous network i/o.
  20
  21 Options
  22 -------
  23
  24 ``port`` and ``ssl_port``
  25
  26 :Description: Sets the ipv4 & ipv6 listening port number. Can be specified multiple
  27               times as in ``port=80 port=8000``.
  28 :Type: Integer
  29 :Default: ``80``
  30
  31
  32 ``endpoint`` and ``ssl_endpoint``
  33
  34 :Description: Sets the listening address in the form ``address[:port]``, where
  35               the address is an IPv4 address string in dotted decimal form, or
  36               an IPv6 address in hexadecimal notation surrounded by square
  37               brackets. Specifying a IPv6 endpoint would listen to v6 only. The
  38               optional port defaults to 80 for ``endpoint`` and 443 for
  39               ``ssl_endpoint``. Can be specified multiple times as in
  40               ``endpoint=[::1] endpoint=192.168.0.100:8000``.
  41
  42 :Type: Integer
  43 :Default: None
  44
  45
  46 ``ssl_certificate``
  47
  48 :Description: Path to the SSL certificate file used for SSL-enabled endpoints.
  49               If path is prefixed with ``config://``, the certificate will be
  50               pulled from the ceph monitor ``config-key`` database.
  51
  52 :Type: String
  53 :Default: None
  54
  55
  56 ``ssl_private_key``
  57
  58 :Description: Optional path to the private key file used for SSL-enabled
  59               endpoints. If one is not given, the ``ssl_certificate`` file
  60               is used as the private key.
  61               If path is prefixed with ``config://``, the certificate will be
  62               pulled from the ceph monitor ``config-key`` database.
  63
  64 :Type: String
  65 :Default: None
  66
  67 ``tcp_nodelay``
  68
  69 :Description: If set the socket option will disable Nagle's algorithm on
  70               the connection which means that packets will be sent as soon
  71               as possible instead of waiting for a full buffer or timeout to occur.
  72
  73               ``1`` Disable Nagel's algorithm for all sockets.
  74
  75               ``0`` Keep the default: Nagel's algorithm enabled.
  76
  77 :Type: Integer (0 or 1)
  78 :Default: 0
  79
  80 ``max_connection_backlog``
  81
  82 :Description: Optional value to define the maximum size for the queue of
  83               connections waiting to be accepted. If not configured, the value
  84               from ``boost::asio::socket_base::max_connections`` will be used.
  85
  86 :Type: Integer
  87 :Default: None
  88
  89 ``request_timeout_ms``
  90
  91 :Description: The amount of time in milliseconds that Beast will wait
  92               for more incoming data or outgoing data before giving up.
  93               Setting this value to 0 will disable timeout.
  94
  95 :Type: Integer
  96 :Default: ``65000``
  97
  98
  99 Civetweb
 100 ========
 101
 102 .. versionadded:: Firefly
 103
 104 The ``civetweb`` frontend uses the Civetweb HTTP library, which is a
 105 fork of Mongoose.
 106
 107
 108 Options
 109 -------
 110
 111 ``port``
 112
 113 :Description: Sets the listening port number. For SSL-enabled ports, add an
 114               ``s`` suffix like ``443s``. To bind a specific IPv4 or IPv6
 115               address, use the form ``address:port``. Multiple endpoints
 116               can either be separated by ``+`` as in ``127.0.0.1:8000+443s``,
 117               or by providing multiple options as in ``port=8000 port=443s``.
 118
 119 :Type: String
 120 :Default: ``7480``
 121
 122
 123 ``num_threads``
 124
 125 :Description: Sets the number of threads spawned by Civetweb to handle
 126               incoming HTTP connections. This effectively limits the number
 127               of concurrent connections that the frontend can service.
 128
 129 :Type: Integer
 130 :Default: ``rgw_thread_pool_size``
 131
 132
 133 ``request_timeout_ms``
 134
 135 :Description: The amount of time in milliseconds that Civetweb will wait
 136               for more incoming data before giving up.
 137
 138 :Type: Integer
 139 :Default: ``30000``
 140
 141
 142 ``ssl_certificate``
 143
 144 :Description: Path to the SSL certificate file used for SSL-enabled ports.
 145
 146 :Type: String
 147 :Default: None
 148
 149 ``access_log_file``
 150
 151 :Description: Path to a file for access logs. Either full path, or relative
 152                           to the current working directory. If absent (default), then
 153                           accesses are not logged.
 154
 155 :Type: String
 156 :Default: ``EMPTY``
 157
 158
 159 ``error_log_file``
 160
 161 :Description: Path to a file for error logs. Either full path, or relative
 162                           to the current working directory. If absent (default), then
 163                           errors are not logged.
 164
 165 :Type: String
 166 :Default: ``EMPTY``
 167
 168
 169 The following is an example of the ``/etc/ceph/ceph.conf`` file with some of these options set: ::
 170
 171  [client.rgw.gateway-node1]
 172  rgw_frontends = civetweb request_timeout_ms=30000 error_log_file=/var/log/radosgw/civetweb.error.log access_log_file=/var/log/radosgw/civetweb.access.log
 173
 174 A complete list of supported options can be found in the `Civetweb User Manual`_.
 175
 176
 177 Generic Options
 178 ===============
 179
 180 Some frontend options are generic and supported by all frontends:
 181
 182 ``prefix``
 183
 184 :Description: A prefix string that is inserted into the URI of all
 185               requests. For example, a swift-only frontend could supply
 186               a uri prefix of ``/swift``.
 187
 188 :Type: String
 189 :Default: None
 190
 191
 192 .. _Civetweb User Manual: https://civetweb.github.io/civetweb/UserManual.html
 193 .. _Config Reference: ../config-ref