Fixes #831 - Add no_proxy variable and adjust proxy configuration

appendix/proxy.rst

@@ -1,39 +1,75 @@
 Proxy and Connections
-======================
+=====================
 
-If you want to route Zammad's traffic over a proxy, you can find information
-about it on this page.
+Proxy
+-----
 
-Proxy Variables
----------------
+This section covers the proxy configuration via environment variables. As an
+alternative, the proxy configuration is also possible via Zammad UI. You can
+find more information about that in the
+:admin-docs:`network section of the admin documentation </settings/system/network.html>`.
+
+.. csv-table:: Proxy configuration comparison
+   :header: "", "GUI configuration", "Environment variable"
+   :widths: 40, 30, 30
+
+   "Host OS access required",                   "No",  "Yes"
+   "Automatically excluded loopback addresses", "Yes", "No"
+   "Configuration check",                       "Yes", "Manually via test script"
+   "Exceptions",                                "Yes", "No"
 
 The following environment variables can be used to configure proxy settings.
-Set it the way you want and adjust the values to your use case:
+Adjust the values according to your environment.
 
-.. code-block:: sh
+HTTP_PROXY
+   Variable for HTTP traffic. Set it to the address of your proxy server,
+   including the port. Example:
 
-   export HTTP_PROXY="http://127.0.0.1:8080"
+   .. code-block:: sh
 
-.. code-block:: sh
+      export HTTP_PROXY="http://127.0.0.1:8080"
 
-   export HTTPS_PROXY="http://127.0.0.1:8080"
+HTTPS_PROXY
+   Variable for HTTPS traffic. Set it to the address of your proxy server,
+   including the port. Example:
+
+   .. code-block:: sh
+
+      export HTTPS_PROXY="http://127.0.0.1:8080"
+
+NO_PROXY
+   Variable for addresses that should be accessed directly and without proxy.
+   Expects a comma separated list of addresses and supports wildcards. Use
+   a leading ``.`` as wildcard for subdomains, e.g. ``.example.com`` would match
+   example.com and all of its subdomains. Make sure to include loopback addresses
+   to exclude them from being routed via proxy.
+   Example:
+
+   .. code-block:: sh
 
-.. code-block:: sh
+      export NO_PROXY="localhost,127.0.0.1,.example.com"
 
-   export ES_JAVA_OPTS="-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8080"
+ES_JAVA_OPTS
+   Variable for setting a proxy for Elasticsearch. By default, Elasticsearch
+   does not communicate to external systems during the operation. However,
+   there can be cases where this is needed, for example when downloading the
+   ingest plugin for Elasticsearch versions below 8. Example:
+
+   .. code-block:: sh
+
+      export ES_JAVA_OPTS="-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8080"
 
 .. hint::
    Depending on your environment, you might want to use the lower case variants
-   of the variables as well. If in doubt, set both variants, e.g. like that:
+   of the variables as well. If in doubt, set both variants by additionally
+   specifying them with the values of the upper case variants, for example:
 
    .. code-block:: sh
 
       export http_proxy=$HTTP_PROXY
-      export https_proxy=$HTTPS_PROXY
-      export es_java_opts=$ES_JAVA_OPTS
 
-Download Dependencies
----------------------
+External Connections
+--------------------
 
 During installation and operation of Zammad, some connections to online services
 are required. Depending on your installation method and Zammad configuration,
@@ -52,25 +88,19 @@ configuration):
    "index.rubygems.org",    "Download of gems for ruby"
    "registry.npmjs.org",    "Download of js dependencies"
 
-Test Script
------------
-
-You can use a script to check the connection state of your system. Run it either
-by fetching it from the Zammad repository or by executing the local version on
-your Zammad machine:
 
-Remote:
+You can use a script to check the connection state of your system.
+It tries to connect to the services mentioned above and shows the
+result. If every connection was successful, it displays a checkmark for each
+contacted service. Run it either by fetching it from the Zammad repository or
+by executing the local version on your Zammad machine.
 
-.. code-block:: sh
-
-   curl -fsSL https://raw.githubusercontent.com/zammad/zammad/refs/heads/stable/contrib/packager.io/test_download_dependencies_connection.sh | sh
-
-Local:
+Fetch script from remote
+   .. code-block:: sh
 
-.. code-block:: sh
+      curl -fsSL https://raw.githubusercontent.com/zammad/zammad/refs/heads/stable/contrib/packager.io/test_download_dependencies_connection.sh | sh
 
-   /opt/zammad/contrib/packager.io/test_download_dependencies_connection.sh
+Use local script
+   .. code-block:: sh
 
-This script will try to connect to the services mentioned above and show the
-results. If everything is fine, you should see a checkmark for each contacted
-service.
+      /opt/zammad/contrib/packager.io/test_download_dependencies_connection.sh