diff --git a/docs/server/reverse-proxy/nginx.md b/docs/server/reverse-proxy/nginx.md index bb00b37..2625056 100644 --- a/docs/server/reverse-proxy/nginx.md +++ b/docs/server/reverse-proxy/nginx.md @@ -8,7 +8,9 @@ NGINX is a versatile, high-performance web server that can also function as a re Stalwart supports NGINX, enabling you to leverage NGINX’s capabilities to efficiently manage and route email traffic. By using NGINX as a reverse proxy for Stalwart, you can ensure high availability, scalability, and enhanced security for your email infrastructure. NGINX’s support for the Proxy Protocol further enhances Stalwart’s ability to receive crucial client connection details, such as the client’s IP address and TLS connection status, which are essential for accurate sender authentication and effective security policy enforcement. -## Configuration +You can use nginx to either proxy all protocols (HTTP, SMTP, IMAP and POP) or only HTTP + +## Full Proxy Configuration Ensure that NGINX is built with the `--with-stream` module, as the `stream` module is required to handle TCP traffic. @@ -53,3 +55,58 @@ stream { } } ``` + +## HTTP only Proxy Configuration + +```txt +# /etc/nginx/sites-available/stalwart.conf + +server { + server_name mail.example.org; + + location / { + proxy_pass http://127.0.0.1:8080; # set up http listener port to 8080 in stalwart + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + # Adjust the timeout if necessary + proxy_read_timeout 90; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + + #listen 443 ssl proxy_protocol; # managed by Certbot + listen 443 ssl; # managed by Certbot + ssl_certificate /etc/letsencrypt/live/mail.example.org/fullchain.pem; # managed by Certbot + ssl_certificate_key /etc/letsencrypt/live/mail.example.org/privkey.pem; # managed by Certbot + include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot + ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot + +} +server { + server_name mail.example.org; + return 301 https://$host$request_uri; +} +``` + +To have TLS working both for HTTP and the other protocols handled directly by Stalwart, you will need to copy letsencrypt certificates + +```bash +#!/bin/bash +DOMAIN="mail.example.org" + +cp -f /etc/letsencrypt/live/$DOMAIN/fullchain.pem /opt/stalwart/etc/ssl/cert.pem +cp -f /etc/letsencrypt/live/$DOMAIN/privkey.pem /opt/stalwart/etc/ssl/key.pem +chown stalwart.stalwart /opt/stalwart/etc/ssl/* +``` + +and in Stalwart, create a new TLS certificate + +```txt +server.tls.certificate = "default" +certificate.default.cert = "%{file:/opt/stalwart/etc/ssl/cert.pem}%" +certificate.default.private-key = "%{file:/opt/stalwart/etc/ssl/key.pem}%" +certificate.default.default = true +``` diff --git a/docs/server/reverse-proxy/overview.md b/docs/server/reverse-proxy/overview.md index ba1a5c5..1b4dba5 100644 --- a/docs/server/reverse-proxy/overview.md +++ b/docs/server/reverse-proxy/overview.md @@ -21,3 +21,11 @@ Secondly, enforcing limits on the number of connections or the volume of emails Lastly, knowing whether the connection was encrypted via TLS can help in policy enforcement and logging, ensuring that sensitive data is transmitted securely. This information allows Stalwart to maintain high security standards and enforce policies that may depend on the encryption status of the connection. By leveraging the Proxy Protocol, you enhance the capability of Stalwart to accurately authenticate senders, enforce security policies, and maintain the integrity of your email communications. Configuring a reverse proxy with the Proxy Protocol for Stalwart not only optimizes performance and security but also ensures that the server has all necessary client connection details to function correctly and securely. + +## Ports and base url + +To have Stalwart working smoothly behind a proxy, you will need to adjust: + +1. the listener port(s), ie. remove the https listener and change the http port to 8080 +2. set up your proxy to listen to the ports (http 80, https 443...) and proxy to the new ports defined in Stalwart. Refer to each proxy for how to do it +3. change the Base URL to *'https://' + config_get('server.hostname')* to let Stalwart use the public url (for instance for the JMAP server)