Add ProxyPass (Reverse proxy) page (#301)

NethServer/dev#5454

administrator-manual/en/proxy_pass.rst

@@ -1,20 +1,31 @@
+.. _proxy_pass-section:
+
 =============
 Reverse proxy
 =============
 
 The :index:`reverse proxy` feature is useful when you want to access internal sites
 from the outside network.
 
-Typical scenario:
+Path and virtual host rules
+===========================
+
+A web client request can be forwarded to another web server transparently,
+according to two types of matching rules:
+
+* Requests matching an URL path, like ``http://mydomain.com/mysite``
+* Requests matching a virtual host name, like ``http://my.secondary-domain.com``
+
+The typical scenario for a **URL path rule** is the following:
 
 * |product| is the firewall of your LAN
 
-* You have a domain http://mydomain.com
+* You have a domain ``http://mydomain.com``
 
-* You would like http://mydomain.com/mysite to forward to the internal server
+* You would like ``http://mydomain.com/mysite`` to forward to the internal server
   (internal IP: 192.168.2.100)
 
-In this scenario create a new record under :guilabel:`Reverse proxy` page. Set
+In this scenario, create a new record under :guilabel:`Reverse proxy > Paths` page. Set
 the :guilabel:`Name` of the item to ``mysite`` and the :guilabel:`Target URL` to
 ``http://192.168.2.100``.
 
@@ -25,6 +36,24 @@ Only clients from certain networks can be allowed to connect, by specifying  a
 comma-separated list of CIDR networks under the :guilabel:`Access from CIDR
 networks`  field.
 
+A **virtual host name rule** can be forward HTTP requests to another web server,
+and is defined in the :guilabel:`Reverse proxy > Virtual hosts` page. For instance:
+
+* |product| is the firewall of your LAN
+
+* You have a domain ``http://my.secondary-domain.com``
+
+* You would like ``http://my.secondary-domain.com`` to be forwarded to the internal web server
+  ``192.168.2.101``, port 9000.
+
+In this scenario, set the :guilabel:`Name` of a new virtual host item to
+``my.secondary-domain.com`` and the :guilabel:`Target URL` to
+``http://192.168.2.101:9000``.
+
+Refer also to :ref:`the UI description of Reverse Proxy <ProxyPassUi-section>`
+for additional information about advanced features, like :guilabel:`Forward HTTP
+"Host" header to target` and :guilabel`Accept invalid SSL certificate from
+target`.
 
 Manual configuration
 ====================
@@ -51,4 +80,4 @@ Create :file:`/etc/httpd/conf.d/myproxypass.conf` file with this content: ::
   </VirtualHost>
 
 
-Please refer to official Apache documentation for more information: http://httpd.apache.org/docs/2.2/mod/mod_proxy.html
+Please refer to official Apache documentation for more information: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html

administrator-manual/en/ui/ProxyPass.rst

@@ -0,0 +1,48 @@
+.. _ProxyPassUi-section:
+
+=============
+Reverse proxy
+=============
+
+This page configures certain paths and virtual host names under Apache to be
+served by forwarding the original web request to another URL. See also
+:ref:`proxy_pass-section`.
+
+
+Create / Edit
+-------------
+
+Name
+    The URL **path name** or the **virtual host name** (an host FQDN). A path name will
+    match URLs like ``http://somehost/<path name>/...``, whilst a virtual host
+    name will match an URL like ``http://<virtual host name>/...``.
+    Matching URLs are forwarded to the :guilabel:`Target URL`.
+
+Access from CIDR networks
+    Restrict the access from the given list of CIDR networks. Elements must be
+    separated with a "," (comma).
+
+SSL/TLS certificate
+    Select a certificate that is compatible with the virtual host name.
+
+Require SSL encrypted connection
+    If enabled, the URL path or virtual host name can be accessed only with an
+    SSL/TLS connection.
+
+Target URL
+    The URL where the original request is forwarded.
+    An URL has the form ``<scheme>://<hostname>:<port>/<path>``.
+
+Accept invalid SSL certificate from target
+    If the :guilabel:`Target URL` has the ``https`` scheme, accept its
+    certificate even if it is not valid.
+
+Forward HTTP "Host" header to target
+    When enabled, this option will pass the HTTP "Host" header line from the
+    incoming request to the proxied host, instead of the "hostname" specified in
+    the :guilabel:`Target URL` field.
+
+Delete
+------
+
+Removes the selected entry.