doc/rgw: add page for http frontend configuration

Fixes: http://tracker.ceph.com/issues/13523
Signed-off-by: Casey Bodley <cbodley@redhat.com>
(cherry picked from commit b592ac44ccad803d13c1dc0ac57764d4e076d0d6)

Conflicts:
        doc/radosgw/frontends.rst - version added to Luminous

diff --git a/doc/radosgw/config-ref.rst b/doc/radosgw/config-ref.rst
index ac96193cc9d0913832804caa5ae58050499d9b2f..45054a9eceb27ad4be56794352e3c4a38b8ad0d3 100644 (file)
--- a/doc/radosgw/config-ref.rst
+++ b/doc/radosgw/config-ref.rst
@@ -13,6 +13,17 @@ specified in the command. Thus variables meant to be applied to all RGW
 instances or all radosgw-admin commands can be put into the ``[global]`` or the
 ``[client]`` section to avoid specifying instance-name.
 
+``rgw frontends``
+
+:Description: Configures the HTTP frontend(s). The configuration for multiple
+              frontends can be provided in a comma-delimited list. Each frontend
+              configuration may include a list of options separated by spaces,
+              where each option is in the form "key=value" or "key". See
+              `HTTP Frontends`_ for more on supported options.
+
+:Type: String
+:Default: ``civetweb port=7480``
+
 ``rgw data``
 
 :Description: Sets the location of the data files for Ceph Object Gateway.
@@ -848,3 +859,4 @@ Barbican Settings
 .. _Rados cluster handles: ../../rados/api/librados-intro/#step-2-configuring-a-cluster-handle
 .. _Barbican: ../barbican
 .. _Encryption: ../encryption
+.. _HTTP Frontends: ../frontends

diff --git a/doc/radosgw/frontends.rst b/doc/radosgw/frontends.rst
new file mode 100644 (file)
index 0000000..cdc5c27
--- /dev/null
+++ b/doc/radosgw/frontends.rst
@@ -0,0 +1,97 @@
+==============
+HTTP Frontends
+==============
+
+.. contents::
+
+The Ceph Object Gateway supports two embedded HTTP frontend libraries
+that can be configured with ``rgw_frontends``.
+
+Beast
+=====
+
+.. versionadded:: Luminous
+
+The ``beast`` frontend uses the Boost.Beast library for HTTP parsing
+and the Boost.Asio library for asynchronous network i/o.
+
+Options
+-------
+
+``port``
+
+:Description: Sets the listening port number.
+
+:Type: Integer
+:Default: ``80``
+
+
+Civetweb
+========
+
+.. versionadded:: Firefly
+
+The ``civetweb`` frontend uses the Civetweb HTTP library, which is a
+fork of Mongoose.
+
+
+Options
+-------
+
+``port``
+
+:Description: Sets the listening port number. For SSL-enabled ports, add an
+              ``s`` suffix like ``443s``. To bind a specific IPv4 or IPv6
+              address, use the form ``address:port``. Multiple endpoints
+              can be separated by ``+`` as in ``127.0.0.1:8000+443s``.
+
+:Type: String
+:Default: ``7480``
+
+
+``num_threads``
+
+:Description: Sets the number of threads spawned by Civetweb to handle
+              incoming HTTP connections. This effectively limits the number
+              of concurrent connections that the frontend can service.
+
+:Type: Integer
+:Default: ``rgw_thread_pool_size``
+
+
+``request_timeout_ms``
+
+:Description: The amount of time in milliseconds that Civetweb will wait
+              for more incoming data before giving up.
+
+:Type: Integer
+:Default: ``30000``
+
+
+``ssl_certificate``
+
+:Description: Path to the SSL certificate file used for SSL-enabled ports.
+
+:Type: String
+:Default: None
+
+
+A complete list of supported options can be found in the `Civetweb User Manual`_.
+
+
+Generic Options
+===============
+
+Some frontend options are generic and supported by all frontends:
+
+``prefix``
+
+:Description: A prefix string that is inserted into the URI of all
+              requests. For example, a swift-only frontend could supply
+              a uri prefix of ``/swift``.
+
+:Type: String
+:Default: None
+
+
+.. _Civetweb User Manual: https://civetweb.github.io/civetweb/UserManual.html

diff --git a/doc/radosgw/index.rst b/doc/radosgw/index.rst
index 657a6f9b92bafe3c324e828ae99a9c36e102c9ee..b28f76e914610a3e1133c43ae939068ec52673ca 100644 (file)
--- a/doc/radosgw/index.rst
+++ b/doc/radosgw/index.rst
@@ -37,6 +37,7 @@ you may write data with one API and retrieve it with the other.
    :maxdepth: 1
 
    Manual Install w/Civetweb <../../install/install-ceph-gateway>
+   HTTP Frontends <frontends>
    Multisite Configuration <multisite>
    Configuring Pools <pools>
    Config Reference <config-ref>