FreeBSD jail, recovery listener rejects successful wildcard bind

Issue Description

Stalwart 1.0.3 cannot start its HTTP recovery listener during initial setup in a FreeBSD jail with a single IPv4 address and a shared network stack (non-VNET).

When binding to 0.0.0.0, FreeBSD substitutes the jail’s sole IPv4 address. The bind succeeds, but TcpListener::is_bound_to() rejects the socket because the actual IP differs from the requested wildcard address.

Proposed fix:

Allow the actual bound IP to differ when the requested IP is unspecified. Continue requiring exact matches for explicitly requested IP addresses, and retain the existing port checks:

--- a/crates/common/src/network/listen.rs
+++ b/crates/common/src/network/listen.rs
@@ -458,7 +458,7 @@ impl TcpListener {
     }

     fn is_bound_to(&self, local_addr: SocketAddr) -> bool {
-        local_addr.ip() == self.addr.ip()
+        (self.addr.ip().is_unspecified() || local_addr.ip() == self.addr.ip())
             && local_addr.port() != 0
             && (self.addr.port() == 0 || local_addr.port() == self.addr.port())
     }

I rebuilt Stalwart with this patch and confirmed that it resolves the issue.

Expected Behavior

The recovery listener should start successfully after binding to the jail’s IPv4 address, allowing initial setup on port 8080.

Actual Behavior

Stalwart successfully binds the socket but rejects it before calling listen(). The recovery listener remains unavailable.

The error reports that the socket is bound to the jail’s address. This is Stalwart’s own socket, rather than another process occupying port 8080.

Reproduction Steps

  1. Create a non-VNET FreeBSD jail with exactly one IPv4 address and IPv6 disabled.
  2. Install Stalwart 1.0.3.
  3. Start Stalwart without an existing configuration, triggering bootstrap mode.
  4. Stalwart attempts to create an IPv6 recovery listener and falls back to 0.0.0.0:8080.
  5. Observe that the recovery listener fails to start because FreeBSD substituted the jail’s IPv4 address for the wildcard address.

Relevant Log Output

Before applying the patch:

2026-11-07T18:30:12Z WARN Server started in bootstrap mode (server.bootstrap-mode) hostname = "stalwart.lan", details = "No configuration file wa
s found. Port 8080 is open for initial setup.", version = "1.0.3"
2026-11-07T18:30:12Z INFO Application resource updated (resource.application-updated) url = "https://github.com/stalwartlabs/webui/releases/downl
oad/v2/webui.zip", details = "Stalwart Web Interface"
2026-11-07T18:30:12Z WARN Configuration build warning (registry.build-warning) objectType = "NetworkListener", id = 20080258862541, property = (n
ull), reason = "IPv6 unavailable on this host (Protocol not supported (os error 43)); falling back from [::]:8080 to 0.0.0.0:8080"
2026-11-07T18:30:12Z ERROR Network listener error (network.listen-error) listenerId = "http-recovery", localIp = 0.0.0.0, localPort = 8080, tls =
 false, reason = "Refusing to listen on 0.0.0.0:8080: socket is bound to 10.10.10.22:8080"

Successful startup after applying the patch:

2026-11-08T11:52:54Z WARN Server started in bootstrap mode (server.bootstrap-mode) hostname = "stalwart.lan", details = "No configuration file wa
s found. Port 8080 is open for initial setup.", version = "1.0.3"
2026-11-08T11:52:55Z INFO Application resource updated (resource.application-updated) url = "https://github.com/stalwartlabs/webui/releases/downl
oad/v2/webui.zip", details = "Stalwart Web Interface"
2026-11-08T11:52:55Z WARN Configuration build warning (registry.build-warning) objectType = "NetworkListener", id = 20080258862541, property = (n
ull), reason = "IPv6 unavailable on this host (Protocol not supported (os error 43)); falling back from [::]:8080 to 0.0.0.0:8080"
2026-11-08T11:52:55Z INFO Network listener started (network.listen-start) listenerId = "http-recovery", localIp = 0.0.0.0, localPort = 8080, tls 
= false

Stalwart Version

v1.x

Installation Method

Built from source

Database Backend

PostgreSQL

Blob Storage

PostgreSQL

Search Engine

PostgreSQL

Directory Backend

SQL

I have reviewed the documentation and FAQ and confirm that my issue is NOT addressed there.

on

I have searched this support forum (open and closed topics) and confirm this is not a duplicate.

on

I understand that topics in this category are triaged by a bot first but a human reply will follow up. If I’d prefer a human-only reply, I’ll add the no-ai tag to my topic.

on

Your diagnosis matches the source. I haven’t run any of this myself.

In crates/common/src/network/listen.rs, TcpListener::listen() reads local_addr() after the socket is bound. It then calls is_bound_to(), which requires local_addr.ip() == self.addr.ip(). If it doesn’t match, it returns the “Refusing to listen on …: socket is bound to …” error you’re seeing. In a non-VNET FreeBSD jail the kernel replaces 0.0.0.0 with the jail’s only IPv4 address. The bind succeeds, but the strict IP comparison then fails. That is consistent with your log lines (0.0.0.0:8080 requested, 10.10.10.22:8080 actual).

Your proposed change keeps the exact-match requirement for explicit addresses. It also keeps the port checks: the bound port can’t be 0, and it must equal the requested port unless 0 was requested. It only relaxes the IP check when the requested address is unspecified. That looks like a reasonable fix for the jail case. The docs don’t cover this behaviour, so a staff member or maintainer will need to decide whether to take the patch.

Until then, you could run your patched build. I haven’t verified a configuration-only workaround, such as setting an explicit listener address, for the bootstrap recovery listener. I wouldn’t count on one without testing it.

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong.

Your patch was the right fix, and that’s what went in. The check that refuses to call listen() compares the address the socket ended up bound to with the configured one. It was added to catch sockets whose bind had silently failed, but a non-VNET jail rewrites 0.0.0.0 to the jail’s own address, so a perfectly good bind looked like a mismatch. Now, when the configured address is a wildcard (0.0.0.0 or ::), any address the kernel picks is accepted. Explicit addresses still have to match exactly, and the port checks are unchanged.

This applies to every listener on a wildcard address, not just the recovery one on 8080, so your regular listeners will start in the jail too. The fix ships in the next weekly release, and until then your patched build is equivalent.