Skip to main content

Reverse Proxy

A reverse proxy in front of HumHub can be set up in two ways:

  • TLS termination: The proxy handles HTTPS and forwards the requests to HumHub via plain HTTP. HumHub relies on forwarded headers to generate correct HTTPS links, so the proxy must be configured as a trusted host.
  • Encrypted connection to HumHub (recommended): The proxy also connects to HumHub via HTTPS. HumHub generates correct links without forwarded headers. A trusted host entry is only needed to see the real visitor IP.

Proxy Configuration​

The proxy has to keep the original Host header and send the headers X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-For. The defaults differ between proxies, e.g.:

  • Apache: Add ProxyPreserveHost On (ProxyPreserveHost) and RequestHeader set X-Forwarded-Proto https. mod_proxy sends X-Forwarded-Host and X-Forwarded-For, but not X-Forwarded-Proto (X-Forwarded headers).
  • Caddy: Nothing to add, the headers are sent by default (reverse_proxy defaults).
  • nginx: All headers have to be set explicitly, including Host $host (proxy_set_header).
  • Traefik: Nothing to add, the headers are sent by default (services).

Common pitfalls:

  • Under FrankenPHP (e.g. the Docker image), X-Forwarded-Host is required, otherwise URLs end up with :80.
  • Without X-Forwarded-Proto, all URLs including the live updates URL use http://.
  • Live updates (/.well-known/mercure) usually pass the proxy without extra settings. For nginx, disabling response buffering for this location is a sensible precaution (proxy_buffering):
location /.well-known/mercure {
proxy_buffering off;
# Further proxy settings
}

Encrypted connection to HumHub​

It is recommended to encrypt the connection between the proxy and HumHub as well. In addition to the settings above, the proxy has to send the public host name as SNI and verify the certificate of HumHub. Settings for common proxies, e.g.:

  • Apache: SSLProxyEngine on, SSLProxyVerify require and SSLProxyCACertificateFile (SSLProxyVerify). For a CA with an intermediate certificate, SSLProxyVerifyDepth 2 is needed (SSLProxyVerifyDepth).
  • Caddy: Since v2.11, Caddy replaces the Host header with the upstream address for HTTPS upstreams. Restore it with header_up Host {hostport} (reverse_proxy HTTPS). Otherwise HumHub answers with an empty page.
  • nginx: proxy_ssl_server_name on and proxy_ssl_name $host for SNI, proxy_ssl_verify on with proxy_ssl_trusted_certificate for verification (proxy_ssl_verify).
  • Traefik: A serversTransport with serverName and rootCAs (ServersTransport).

Common pitfalls:

  • Missing or wrong SNI fails with tlsv1 alert internal error or tls: internal error.
  • nginx and Apache do not verify the certificate of HumHub by default. Without verification, the encryption only protects against passive eavesdropping. Accept this only if the proxy and HumHub run on the same host.

For the container side (TLS options, internal CA for an encrypted connection from the proxy), see the Docker image documentation.

Trusted Hosts​

The following headers are only accepted from a trusted host:

  • X-Forwarded-For
  • X-Forwarded-Host
  • X-Forwarded-Proto
  • X-Forwarded-Port
  • Front-End-Https
  • X-Rewrite-Url
  • X-Original-Host

Headers sent by any other host are ignored. Without a trusted host entry, HumHub records the proxy address instead of the visitor IP and, with TLS termination, generates links with the wrong protocol or host name.

Configuration​

The trusted hosts can be configured in the web configuration file or with an environment variable:

In protected/config/web.php (in Docker: /data/config/web.php):

<?php
/**
* This file provides to overwrite the default HumHub / Yii configuration by your local Web environments
* @see https://www.yiiframework.com/doc-2.0/guide-concept-configurations.html
* @see https://docs.humhub.org/docs/admin/advanced-configuration
*/
return [
'components' => [
'request' => [
'trustedHosts' => ['192.168.0.0/24'],
],
],
];
Web configuration only

Do not configure the trusted hosts in protected/config/common.php or with the HUMHUB_CONFIG__ prefix. Both also apply to the console application, whose request component has no trustedHosts property. Every yii command (migrations, queue workers, cron jobs) then fails with Setting unknown property: yii\console\Request::trustedHosts. The web frontend keeps working, so the error is easy to miss.

Environment variables are merged after the configuration files. List entries are appended, not replaced, so configure the setting in one place only.

Value format​

The value can be a list or a map:

  • List: ['192.168.0.0/24'] trusts all headers listed above from these addresses.
  • Map: ['10.0.0.1' => ['X-Forwarded-For']] trusts only the given headers from this address.

Addresses are IPv4 or IPv6 addresses in CIDR notation. The entries are checked in order, the first match wins.

You can find more information in the Yii2 documentation: https://www.yiiframework.com/doc/api/2.0/yii-web-request#$trustedHosts-detail

Which address to trust​

Trust the address HumHub sees as the direct peer of the request (REMOTE_ADDR), e.g. 127.0.0.1 if the proxy runs on the same host.

  • Keep the range as narrow as possible. Any trusted peer can spoof the host name used in generated links (e.g. in password reset e-mails) and the visitor IP recorded in sessions and logs.
  • HumHub must not be reachable directly, bypassing the proxy.
  • Under FrankenPHP (e.g. the Docker image), REMOTE_ADDR stays the proxy address even if Caddy is configured with trusted_proxies. That setting only affects Caddy's own access log, HumHub still needs its own trusted hosts entry to see the visitor IP.

HTTPS/SSL Detection​

Typically HumHub detects the currently used protocol (HTTP or HTTPS) and uses this automatically to generate links. With TLS termination at the proxy, this is done using the X-Forwarded-Proto header from a trusted host.

If this detection fails, the generation of HTTPS URLs can be forced in protected/config/web.php. Use this only as a fallback, a correctly configured trusted host is the preferred solution.

<?php

// Enforce HTTPS link generation
$_SERVER['HTTPS'] = 'on';

return [
// Further configuration options
];

Existing Installations​

Check the stored Base URL in Administration > Settings > General after putting an existing installation behind a proxy. Links in e-mails and notifications created by background jobs use this setting, not the current request.

Caching​

If the proxy also acts as a cache, it is important that query parameters are taken into account.

When static files are modified (e.g. during an upgrade), HumHub automatically adds a new query parameter value (cache bust).

The following paths can be cached:

  • /assets/*
  • /themes/*
  • /uploads/*
  • /static/*

Example NGINX caching snippet (incomplete):

location ~ ^/(assets|themes|uploads|static)/.*$ {
add_header X-ECache 1;
add_header X-ECache-Key $host$uri$is_args$args;
add_header X-ECache-Status $upstream_cache_status;

proxy_ignore_headers "Expires";
proxy_ignore_headers "Cache-Control";

proxy_cache_key "$host$uri$is_args$args";
proxy_cache_valid 200 1d;

proxy_pass $target;
}