From baea14ee5719f3fc52ceb10cc6688ad2cb4193d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emilio=20L=C3=B3pez?= Date: Wed, 17 Nov 2021 22:31:09 -0300 Subject: [PATCH] docs: Clarify use of `loadbalancer.ips` when using a reverse proxy. When Zulip is run behind one or more reverse proxies, you must configure `loadbalancer.ips` so that Zulip respects the client IP addresses found in the `X-Forwarded-For` header. This is not immediately clear from the documentation, so this commit makes it more clear and augments the existing examples to showcase this need. Fixes: #19073 --- docs/production/deployment.md | 45 ++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/docs/production/deployment.md b/docs/production/deployment.md index 0016266c3e..2af164e508 100644 --- a/docs/production/deployment.md +++ b/docs/production/deployment.md @@ -306,6 +306,33 @@ HTTP as follows: 1. Finally, restart the Zulip server, using `/home/zulip/deployments/current/scripts/restart-server`. +#### Configuring Zulip to trust proxies + +Before placing Zulip behind a reverse proxy, it needs to be configured to trust +the client IP addresses that the proxy reports. This is important to have +accurate IP addresses in server logs, as well as in notification emails which +are sent to end users. + +1. Determine the IP addresses of all reverse proxies you are setting up, as seen + from the Zulip host. Depending on your network setup, these may not be the + same as the public IP addresses of the reverse proxies. + +1. Add the following block to `/etc/zulip/zulip.conf`. + + ```ini + [loadbalancer] + # Use the IP addresses you determined above, separated by commas. + ips = 192.168.0.100 + ``` + +1. Reconfigure Zulip with these settings. As root, run + `/home/zulip/deployments/current/scripts/zulip-puppet-apply`. This will + adjust Zulip's `nginx` configuration file to accept the `X-Forwarded-For` + header when it is sent from one of the reverse proxy IPs. + +1. Finally, restart the Zulip server, using + `/home/zulip/deployments/current/scripts/restart-server`. + ### nginx configuration For `nginx` configuration, there's two things you need to set up: @@ -342,6 +369,10 @@ Don't forget to update `server_name`, `ssl_certificate`, `ssl_certificate_key` and `proxy_pass` with the appropriate values for your installation. +On the Zulip side, you will need to add the `nginx` server IP as a trusted +reverse proxy. Follow the instructions to [configure Zulip to trust +proxies](#configuring-zulip-to-trust-proxies). + [nginx-proxy-longpolling-config]: https://github.com/zulip/zulip/blob/main/puppet/zulip/files/nginx/zulip-include-common/proxy_longpolling [standalone.pp]: https://github.com/zulip/zulip/blob/main/puppet/zulip/manifests/profile/standalone.pp [zulipchat-puppet]: https://github.com/zulip/zulip/tree/main/puppet/zulip_ops/manifests @@ -364,7 +395,11 @@ make the following changes in two configuration files. 3. Restart your Zulip server with `/home/zulip/deployments/current/scripts/restart-server`. -4. Create an Apache2 virtual host configuration file, similar to the +4. Follow the instructions to [configure Zulip to trust + proxies](#configuring-zulip-to-trust-proxies). For this example, the reverse + proxy IP would be `127.0.0.1`. + +5. Create an Apache2 virtual host configuration file, similar to the following. Place it the appropriate path for your Apache2 installation and enable it (E.g. if you use Debian or Ubuntu, then place it in `/etc/apache2/sites-available/zulip.example.com.conf` @@ -422,7 +457,9 @@ backend zulip Since this configuration uses the `http` mode, you will also need to [configure Zulip to allow HTTP](#configuring-zulip-to-allow-http) as -described above. +described above. Additionally, you will need to [add the the HAProxy server IP +address as a trusted load balancer](#configuring-zulip-to-trust-proxies) +to have Zulip respect the addresses in `X-Forwarded-For` headers. ### Other proxies @@ -431,7 +468,9 @@ things you need to be careful about when configuring it: 1. Configure your reverse proxy (or proxies) to correctly maintain the `X-Forwarded-For` HTTP header, which is supposed to contain the series - of IP addresses the request was forwarded through. You can verify + of IP addresses the request was forwarded through. Additionally, + [configure Zulip to respect the addresses sent by your reverse + proxies](#configuring-zulip-to-trust-proxies). You can verify your work by looking at `/var/log/zulip/server.log` and checking it has the actual IP addresses of clients, not the IP address of the proxy server.