diff --git a/appendix/proxy.rst b/appendix/proxy.rst index dc83bd0b..f6a3cd87 100644 --- a/appendix/proxy.rst +++ b/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 `. + +.. 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