List of components that allow proxy configuration

[YetAnotherGerrit]

Not all gems/components that are used in Zammad respect the proxy settings we have in the admin interface, some purely rely on environment variables or configuration files. To make it more predictable for admins, we should include information how to configure a proxy based on the functionality.

Currently, there are 3 methods, I am aware of, and some components of Zammad require a specific method:

• Our settings: https://admin-docs.zammad.org/en/latest/settings/system/network.html
• Environment variables: http_proxy, https_proxy, all_proxy, no_proxy & ES_JAVA_OPTS
• Config file (e.g. /usr/share/elasticsearch/jdk/conf/net.properties)

[ralf401]

I think such a list is pretty hard to maintain => yet another list to keep up to date. What do you think about a general note that some features may not support the usage of a proxy?

It is probably a lot of work if we want to include such a list. At least this is the case if nobody can quickly compile such a list... then we have to check manually, I guess?!

[MrGeneration]

Or all functions that communicate with external services lern how to communicate with proxies - that would remove the need of any list and work 100% as exptected.

[YetAnotherGerrit]

What do you think about a general note that some features may not support the usage of a proxy?

That would leave the user to try and error. And would not at all solve the current issue admins facing.

Or all functions that communicate with external services lern how to communicate with proxies - that would remove the need of any list and work 100% as exptected.

I totally agree, that this would be nice. But we are bound to what the used gems offer. Am I right? @dominikklein

[YetAnotherGerrit]

Additionally we have the problem, that some components allow the usage of a proxy, but only rely on environment variables. This can also only be discovered by try and error.

[ralf401]

Proxy Support

Gems

I fetched the gems from the Gemfile in the root of the Zammad repo. Because there are a lot, I tried to just keep those which might connect to the internet.

• 'doorkeeper'
• 'oauth2'
• 'omniauth-facebook'
• 'omniauth-github'
• 'omniauth-gitlab'
• 'omniauth-google-oauth2'
• 'omniauth-linkedin-oauth2'
• 'omniauth-microsoft-office365'
• 'omniauth_openid_connect'
• 'omniauth-saml'
• 'omniauth-twitter'
• 'omniauth-weibo-oauth2'
• 'koala'
• 'telegram-bot-ruby'
• 'whatsapp_sdk'
• 'net-http'
• 'net-imap'
• 'net-pop'
• 'net-smtp'
• 'messagebird-rest'
• 'twilio-ruby'
• 'clearbit'
• 'net-ldap'
• 'zendesk_api'
• 'autodiscover'
• 'openssl'
• 'byk'
• 'PoParser'
• 'aws-sdk-s3'
• 'elasticsearch''>=8.11''<10.0'

Important

Might be incomplete due to manual deletion because of misunderstanding of the purpose of the gems.

Check

Attempt 1: Investigating Websites and Documentation

My first idea was to check the Ruby gem website. The gem pages mostly have links to their homepage, to their docs and to Github. But it seems there is no straightforward way to figure out if and how a proxy can be configured. The following issues made it rather impossible for me to get relevant information:

• Lots of developer targeted information, often spread of several places for one gem.
• A search for proxy in their Github issues led to either no result or to many results because some posted their gemfile which can include gems like no_proxy_fix or rack-proxy.
• Dependencies between gems.

Attempt 2: Install a Proxy Server and Check

The second idea was to install a proxy server and to check which connections are respecting a proxy setting. While there are some proxy servers which are open source, I noticed that "the proxy server" is a rather big topic because of different types and use cases.

• Heavy network adjustments (and skills) needed to have a proper setup.
• Proxies for different protocols.
• Proxies for different use cases: caching, inspection / firewall, etc.

However, Mitmproxy seems a good candidate for a test setup.

Attempt 3: Ask AI

Tried Mistral but only got a partial answer because of rate limiting.

Tried also Grok and the response at least looks good:

Gem	Supports Proxy?	Configuration Method
doorkeeper	No	N/A - OAuth provider, no outbound HTTP requests.
oauth2	Yes	Uses underlying HTTP client (e.g., Net::HTTP or Faraday). Set HTTP_PROXY environment variable or configure the client instance with proxy options.
omniauth-facebook	Yes	OmniAuth strategies use Faraday or Net::HTTP. Configure Faraday middleware with proxy or set HTTP_PROXY env var.
omniauth-github	Yes	Same as above; see OmniAuth proxy issues resolved via env vars or Faraday config.
omniauth-gitlab	Yes	Same as above.
omniauth-google-oauth2	Yes	Uses Faraday; explicitly configure proxy in Faraday connection options.
omniauth-linkedin-oauth2	Yes	Same as above; relies on OAuth2 gem.
omniauth-microsoft-office365	Yes	Uses OmniAuth/OAuth2; configure via underlying HTTP client.
omniauth_openid_connect	Yes	Same as above.
omniauth-saml	Limited	SAML uses XML over HTTP; configure underlying HTTP client if applicable.
omniauth-twitter	Yes	Same as above.
omniauth-weibo-oauth2	Yes	Same as above.
koala	Yes	Uses Net::HTTP; set HTTP_PROXY env var or configure HTTP object with proxy.
telegram-bot-ruby	Yes	Configure custom API URL to point to a proxy endpoint, e.g., Telegram::Bot::Client.run(token, url: 'https://proxy.example.com').
whatsapp_sdk	Yes	Uses HTTP clients; configure via env vars like HTTP_PROXY or client options (assumed based on standard Ruby HTTP libs).
net-http	Yes	Set ENV['http_proxy'] = 'http://proxy:port' or use Net::HTTP.new(host, port, proxy_address, proxy_port).
net-imap	No (built-in)	No native support; use net-imap-proxy gem for proxying.
net-pop	No (built-in)	No native support; requires custom proxy setup or gems.
net-smtp	No (built-in)	No native HTTP proxy; use net-smtp-proxy gem or subclass for SOCKS/HTTP.
messagebird-rest	Yes	Uses RestClient; configure RestClient with proxy options or env vars.
twilio-ruby	Yes	Uses Faraday; add Faraday proxy middleware to the connection stack.
clearbit	Yes	Pass proxy: { uri: 'http://proxy:port', user: 'user', password: 'pass' } in API calls like Clearbit::Enrichment::Company.find(email, proxy: ...).
net-ldap	No	LDAP over TCP; no HTTP proxy support. Use SOCKS proxy wrappers if needed.
zendesk_api	Yes	Uses Faraday; configure client with http_proxy option in ZendeskAPI::Client init.
autodiscover	Yes	Email autodiscover uses HTTP; configure Net::HTTP with proxy as standard.
openssl	N/A	Cryptographic library; no network connections.
byk	N/A	Unclear gem purpose; no network mentions found.
PoParser	N/A	PO file parser; no network connections.
aws-sdk-s3	Yes	Set HTTP_PROXY env var or configure client with :http_proxy option.
elasticsearch (v8+)	Yes	Configure in client options: Elasticsearch::Client.new(hosts: [...], transport_options: { proxy: 'http://proxy:port' }).

Open Topics / Problems

• The gem list might be incomplete due to manual deletion because of misunderstanding of the purpose of the gems.
• The results from AI should be double checked.
• For documentation purposes and to check if and how a proxy can be configured, a test system has to be deployed.
• At least one developer should have a look at the current state before continuing (to avoid running in the wrong direction).

[ralf401]

@YetAnotherGerrit see comment above for the current state. Let's maybe talk about it next week.

[rolfschmidt]

I would like to see the following areas in the proxy documentation:

1. ENVs to setup a proxy:

export HTTP_PROXY="http://127.0.0.1:8080"
export HTTPS_PROXY="http://127.0.0.1:8080"
export ES_JAVA_OPTS="-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8080"

2. Explanation of the download dependencies:

artifacts.elastic.co - used to install the ingest plugin 
dl.packager.io - to download the os package
geo.zammad.com - used for the geo data
google.com - used to download feast days for the calendar
index.rubygems.org - used to download gems for ruby
registry.npmjs.org - used to download js dependencies

3. Info about the test script to check the connection state of the system:

### Remote:

$ curl -fsSL https://raw.githubusercontent.com/zammad/zammad/refs/heads/stable/contrib/packager.io/test_download_dependencies_connection.sh | sh


### Local:

$ /opt/zammad/contrib/packager.io/test_download_dependencies_connection.sh

For Zammad installation/updates:
  https://artifacts.elastic.co  (required)     ✔ OK
  https://dl.packager.io        (required)     ✔ OK
  https://geo.zammad.com        (optional)     ✔ OK
  https://google.com            (optional)     ✔ OK

For Zammad package (addon) installation/updates:
  https://index.rubygems.org    (required)     ✔ OK
  https://registry.npmjs.org    (required)     ✔ OK

(zammad/zammad#5850)