Stalwart Proxy Blocked After Upgrade: Troubleshooting

Sep 15, 2025 by Square 54 views

Stalwart Proxy IP Blocked Despite Trusted Configuration After Upgrade

Hey guys, are you facing the frustrating issue of Stalwart blocking your reverse proxy IP even when your configuration seems correct? It's a real head-scratcher, and I've been there! Let's dive into this problem and figure out how to fix it. This is a common issue after upgrading to v0.13.x, especially if you're using a reverse proxy like nginx.

The Problem: Stalwart Blocking Trusted IPs

So, what's happening here? You've got Stalwart set up behind a reverse proxy (likely nginx in this case), and everything was working smoothly. You've configured the trusted-networks settings in your config.toml file to allow traffic from your proxy's IP range. You've even probably double-checked this in the UI. But, after upgrading, Stalwart is suddenly blocking your proxy, and you're seeing those pesky "Blocked IP address" errors in the logs. This is usually a big problem, as it can prevent you from accessing your email services.

Let's break down the situation based on the provided information. The user is running a Docker compose setup with Stalwart and nginx. The config.toml file shows the trusted-networks setting for various Stalwart listeners, which should permit traffic from the proxy's IP range (172.16.0.0/12 in this example). The nginx configuration is set up to forward traffic to Stalwart on port 10443, which is the HTTPS port in the Docker setup.

Despite these seemingly correct configurations, Stalwart is blocking the proxy's IP address (172.19.0.1 in the logs) on port 443. The nginx logs confirm this, with errors related to the SSL handshake failing, further indicating the issue. This suggests that something is not communicating correctly between the proxy and Stalwart.

This issue is reproducible when using a reverse proxy with Stalwart. The core problem appears to be that Stalwart is not correctly recognizing the proxy's IP address as trusted, despite the configuration in config.toml and potentially the UI. This leads to Stalwart blocking the proxy's connections, preventing access to the mail server.

Understanding the Configuration

Let's take a closer look at the key parts of the configuration to identify the culprit. Understanding the correct setup is a crucial step in troubleshooting.

First, the config.toml file. It's used to configure the core Stalwart settings. The lines provided in the original question show the configuration of the proxy for different listeners like IMAP TLS, Sieve, SMTP, and Submission. The crucial part here is trusted-networks, where we define the IP ranges that Stalwart should trust. Ensure your reverse proxy's IP address is correctly included within these ranges (in this case, 172.16.0.0/12).

Next, the nginx configuration. This acts as the reverse proxy, forwarding external requests to Stalwart. It's configured to listen on ports 443 (HTTPS) and to forward requests to Stalwart on port 10443. The proxy_pass directive is critical here, as it determines where the requests will be sent. Other important directives like proxy_set_header are used to pass the client's information to the backend server (in this case, Stalwart). Pay close attention to the X-Forwarded-For header; it is critical for passing the client's original IP address. If this header is not properly set, Stalwart might see the proxy's IP as the original IP, leading to blocking.

Finally, your Docker Compose file. This defines how your services (Stalwart and Nginx) are deployed. Verify that the ports are correctly mapped, particularly the HTTPS port (10443 in this case). Ensure that the network settings are also configured to allow communication between the proxy and Stalwart.

By carefully reviewing these three components, you should be able to find any configuration discrepancies.

Troubleshooting Steps & Potential Solutions

Alright, let's get down to fixing this. Here are some things you can try to troubleshoot and potentially solve the problem. I'll try to make this easy for you guys.

Double-Check the Trusted Networks: This is the first and most important step. Go back to your config.toml file and the Stalwart UI (if you can access it) and make sure the IP range of your reverse proxy is correctly listed under server.listener.imaptls.proxy.trusted-networks, server.listener.sieve.proxy.trusted-networks, server.listener.smtp.proxy.trusted-networks, server.listener.submission.proxy.trusted-networks, and server.listener.submissions.proxy.trusted-networks. Ensure there are no typos and that the network mask is correct (e.g., /12).
Verify the Proxy Headers in Nginx: The proxy_set_header directives in your nginx configuration are crucial. Double-check that you have these lines in your nginx configuration:
```
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;
```
These headers pass the client's original IP address to Stalwart. Without these, Stalwart will see the proxy's IP address, potentially leading to the block.
Examine the Nginx Logs: Look closely at your nginx logs for any clues. Errors related to SSL handshakes, connection resets, or timeouts might point to issues with the proxy configuration or certificate setup.
Check Stalwart Logs: Try to get into the Stalwart logs and check the logging level. Increase the log level to debug or trace to get more detailed information about why the IP is being blocked. (You may need to adjust the logging level temporarily, and remember to set it back after troubleshooting).
Docker Network Configuration: Ensure your Docker network is correctly set up, and your containers can communicate with each other. Double-check your Docker Compose file and verify that the network settings and port mappings are correct.
Restart Services: After making any configuration changes, restart both nginx and the Stalwart container to apply the changes. I know it sounds obvious, but it's easy to forget!
Database Inspection (Advanced): Since Stalwart uses a database (RocksDB in this case), it's possible that IP blocking rules might be stored there. If the above steps don't work, you might need to access the database directly (if you're comfortable with this) to check for any incorrect IP block rules. However, this is an advanced step, and proceed with caution.
Consult the Stalwart Documentation and Community: The Stalwart documentation and community forums (if they exist) are excellent resources. There might be known issues or specific configuration recommendations for using Stalwart with reverse proxies. Search for similar issues and see how others have solved them.
Check for Conflicting Configurations: Review your overall setup. Are there any other firewalls or security measures that might be interfering with the traffic? Make sure everything is configured to allow the proxy to communicate with Stalwart.

Root Cause Analysis

Based on the information, the main reason for this is a configuration problem, not necessarily a bug. The fact that it worked on 0.12.x and broke on 0.13.x suggests that there might be some changes in how Stalwart handles proxy IP addresses in the newer version. Here's a breakdown of the root cause:

Incorrect Proxy Header: The nginx configuration might not be correctly passing the original client IP address to Stalwart through the X-Forwarded-For header. This could be a misconfiguration in the proxy_set_header directives.
Mismatched Trusted Networks: There could be an issue with the IP range configured in the trusted-networks settings. A typo, an incorrect network mask, or an outdated IP address could cause Stalwart to reject the proxy's connections.
Stalwart Version Changes: The newer version of Stalwart (0.13.x) might have altered its behavior regarding proxy IP handling. There might be changes in how Stalwart verifies the proxy's IP addresses, which can affect configurations that previously worked.
Network Issues: Although less likely, there could be underlying network issues (firewall rules, routing problems) preventing the proxy from communicating with Stalwart.
UI Override: If the configuration was modified in the UI and those settings have not been correctly applied or have been overwritten, it could be an issue. Always ensure the settings in the UI match the intended configuration in config.toml.

Getting Back in the UI After Getting Blocked

This is one of the tricky parts, as you've noticed: getting back into the UI when you're blocked. Here are some ideas:

Temporary Direct Access: If possible, temporarily bypass the reverse proxy to access the Stalwart UI directly. You could temporarily expose port 8080 (or whatever port your UI is on) directly from the Stalwart container. Be sure to secure it if you do this, and only for troubleshooting.
CLI Configuration: If you can't access the UI, try using the command-line interface (CLI) to modify the settings. This depends on whether Stalwart has a CLI available, and you'll need to look up the specific commands for managing trusted networks.
Docker Compose Override: You could try temporarily modifying your Docker Compose file to allow access from your current IP address. This is a quick fix to get in, but remember to remove it afterward.

Additional Tips and Considerations

Here are some extra tips to help you solve this issue. These are very useful to remember.

Test Thoroughly: After making any changes, test your configuration from different locations and devices. Make sure you can access all the Stalwart services (IMAP, SMTP, etc.) through the proxy.
Monitor Logs: Continuously monitor the nginx and Stalwart logs. This will help you identify any ongoing issues and see if the changes you made have resolved the problem.
Security Best Practices: Always follow security best practices, such as using strong passwords, enabling two-factor authentication (2FA), and keeping your software up to date.
Backup Your Configuration: Make regular backups of your config.toml file and any other important configuration files. This is good practice for any system administration.
Understand the Impact: Make sure you understand the impact of any changes you make. Test your configuration thoroughly before applying it to a production environment.

I hope this helps you all! Good luck, and let me know how it goes. If you have any further questions, don't hesitate to ask!