From d5ba6ef065fab21978d1715290cd28965dc8ae05 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Wed, 29 Apr 2026 10:19:42 +0200 Subject: [PATCH 1/3] First attempt --- appendix/proxy.rst | 103 +++++++++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 32 deletions(-) diff --git a/appendix/proxy.rst b/appendix/proxy.rst index dc83bd0b..a9ce521f 100644 --- a/appendix/proxy.rst +++ b/appendix/proxy.rst @@ -1,39 +1,82 @@ 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 ---------------- +In addition to the proxy configuration via environment variables, Zammad also +includes a proxy configuration via GUI which you can find in the +:admin-docs:`system settings section of the admin docs `. +Make sure to avoid a conflicting configuration. + +Important Information +^^^^^^^^^^^^^^^^^^^^^ + +- Use the environment variables configuration to cover connections for used + Ruby gems. +- Use the UI configuration in Zammad to cover connections from Zammad itself. +- If in doubt, set both accordingly. +- There are parts in Zammad which disregard any proxy configuration: + + - WhatsApp + - Massenversand + - Zendesk Migrator + +Variables +^^^^^^^^^ 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 example values so they fit your environment. + +HTTP_PROXY + Variable for HTTP traffic. Set it to the address of your proxy server, + including the port. Example: + + .. code-block:: sh + + export HTTP_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 -.. code-block:: sh + export HTTPS_PROXY="http://127.0.0.1:8080" - export HTTP_PROXY="http://127.0.0.1:8080" +NO_PROXY + Variable for addresses that should be accessed directly and without proxy. + It supports wildcards as well. Provide a comma separated list of addresses. + Example: -.. code-block:: sh + .. code-block:: sh - export HTTPS_PROXY="http://127.0.0.1:8080" + export NO_PROXY="localhost,127.0.0.1,.example.com" -.. code-block:: sh +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: - export ES_JAVA_OPTS="-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8080" + .. 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 + +External Connections +-------------------- Download Dependencies ---------------------- +^^^^^^^^^^^^^^^^^^^^^ During installation and operation of Zammad, some connections to online services are required. Depending on your installation method and Zammad configuration, @@ -53,24 +96,20 @@ configuration): "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: +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. -Remote: - -.. 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 From cb034ca0b993fd047b30806f507c97170a48ccb5 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Wed, 29 Apr 2026 13:24:00 +0200 Subject: [PATCH 2/3] Tweaks and changes after coordination --- appendix/proxy.rst | 39 ++++++++++++++------------------------- 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/appendix/proxy.rst b/appendix/proxy.rst index a9ce521f..e68b11d5 100644 --- a/appendix/proxy.rst +++ b/appendix/proxy.rst @@ -4,29 +4,22 @@ Proxy and Connections Proxy ----- -In addition to the proxy configuration via environment variables, Zammad also -includes a proxy configuration via GUI which you can find in the -:admin-docs:`system settings section of the admin docs `. -Make sure to avoid a conflicting configuration. +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 `. -Important Information -^^^^^^^^^^^^^^^^^^^^^ +.. csv-table:: Proxy configuration comparison + :header: "", "GUI configuration", "Environment variable" + :widths: 40, 30, 30 -- Use the environment variables configuration to cover connections for used - Ruby gems. -- Use the UI configuration in Zammad to cover connections from Zammad itself. -- If in doubt, set both accordingly. -- There are parts in Zammad which disregard any proxy configuration: - - - WhatsApp - - Massenversand - - Zendesk Migrator - -Variables -^^^^^^^^^ + "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. -Adjust the example values so they fit your environment. +Adjust the values according to your environment. HTTP_PROXY Variable for HTTP traffic. Set it to the address of your proxy server, @@ -46,7 +39,8 @@ HTTPS_PROXY NO_PROXY Variable for addresses that should be accessed directly and without proxy. - It supports wildcards as well. Provide a comma separated list of addresses. + Expects a comma separated list of addresses and supports wildcards. Make sure + to include loopback addresses to exclude them from being routed via proxy. Example: .. code-block:: sh @@ -75,9 +69,6 @@ ES_JAVA_OPTS External Connections -------------------- -Download Dependencies -^^^^^^^^^^^^^^^^^^^^^ - During installation and operation of Zammad, some connections to online services are required. Depending on your installation method and Zammad configuration, a connection to the following services is made (maybe also helpful for firewall @@ -95,8 +86,6 @@ 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. It tries to connect to the services mentioned above and shows the From b6baa8b35731b1ea98cf700ec123856e1e1f650b Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Thu, 30 Apr 2026 14:27:15 +0200 Subject: [PATCH 3/3] Explained . wildcard with an example --- appendix/proxy.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/appendix/proxy.rst b/appendix/proxy.rst index e68b11d5..f6a3cd87 100644 --- a/appendix/proxy.rst +++ b/appendix/proxy.rst @@ -39,8 +39,10 @@ HTTPS_PROXY NO_PROXY Variable for addresses that should be accessed directly and without proxy. - Expects a comma separated list of addresses and supports wildcards. Make sure - to include loopback addresses to exclude them from being routed via 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