From: Casey Bodley <cbodley@redhat.com>
Date: Mon, 22 Jan 2018 19:43:38 +0000 (-0500)
Subject: doc/rgw: add page for http frontend configuration
X-Git-Tag: v13.0.2~410^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F20058%2Fhead;p=ceph.git

doc/rgw: add page for http frontend configuration

Fixes: http://tracker.ceph.com/issues/13523

Signed-off-by: Casey Bodley <cbodley@redhat.com>
---

diff --git a/doc/radosgw/config-ref.rst b/doc/radosgw/config-ref.rst
index ac96193cc9d..45054a9eceb 100644
--- 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
index 00000000000..c3c73b7de8c
--- /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:: Mimic
+
+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 883ad621f98..be10335f259 100644
--- 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>