Configuring Prosody on WSL2 requires resolving the dynamic IP issue inherent to the virtualized network. You must enable port forwarding via .wslconfig and configure Prosody to listen on 0.0.0.0 so Windows clients can connect using a stable hostname rather than a shifting internal address.
Understanding the WSL2 Network Model
WSL2 operates as a lightweight utility VM running inside Hyper-V. By default, it is assigned a private IPv4 address that changes every time the subsystem restarts or your host machine reconnects to the network. This behavior makes direct IP-based connections from Windows clients unreliable because the target address becomes invalid almost immediately after a reboot. To solve this, you cannot rely on querying the current IP address dynamically in your client configurations. Instead, you need a mechanism that maps a consistent local address to the transient WSL2 instance. The standard approach involves configuring Windows to forward traffic from a specific localhost port to the WSL2 internal IP. This process is detailed in our guide on Configuring Port Forwarding with WSL2 and IP Passthrough, which explains how to establish this bridge between the host OS and the guest Linux environment.Configuring .wslconfig for Port Forwarding
The first step is to instruct Windows to forward incoming connections to your Prosody ports. You do this by creating or editing the.wslconfig file in your Windows user profile directory (e.g., C:\Users\YourName\.wslconfig). This file controls global WSL2 settings.
Add the following configuration block to map the standard XMPP ports (5222 for client connections and 5269 for server-to-server) to localhost:
[wsl2]
forwarding=5222:localhost:5222
forwarding=5269:localhost:5269
forwarding=5280:localhost:5280forwarding, not ipPassthrough, which is an invalid key for this context. After saving the file, you must fully shut down and restart WSL2 for these changes to take effect. Use the command wsl --shutdown from PowerShell or Command Prompt, followed by restarting your distribution.
Verify that the ports are listening on localhost within Windows by running netstat -ano | findstr :5222. If the output shows 127.0.0.1:5222 in a LISTENING state, the forwarding rule is active.
Prosody Configuration for External Access
Even with port forwarding enabled, Prosody might still refuse connections if it is only bound to the loopback interface of the WSL2 VM itself. You must explicitly tell Prosody to accept connections from any interface. Edit your main configuration file, typically located at/etc/prosody/prosody.cfg.lua. Look for the interfaces setting. It should be set to listen on all available network interfaces:
interfaces = { "0.0.0.0", "::" }0.0.0.0 ensures that the XMPP daemon accepts packets arriving from the forwarded localhost port on the Windows host.
Additionally, ensure that your virtual host is correctly defined. In the same configuration file, add your domain:
VirtualHost "yourdomain.com"
ssl = {
key = "/path/to/key.pem";
certificate = "/path/to/cert.pem";
}
authentication = "internal_hashed"yourdomain.com with your actual domain or a local testing domain like local.prosody. If you are testing locally without DNS, you will need to handle name resolution separately, which we discuss below.
DNS and Hostname Resolution
Since the IP address is hidden behind the localhost forwarding, Windows clients must resolve your XMPP domain to127.0.0.1. For local development, you can add an entry to the Windows hosts file located at C:\Windows\System32\drivers\etc\hosts:
127.0.0.1 yourdomain.comyourdomain.com and have the traffic automatically routed through the forwarding rules to the WSL2 Prosody instance. This avoids the need for complex DNS server setups during initial configuration.
Firewall and Client Connection
Windows Defender Firewall may block inbound connections even if port forwarding is configured. Ensure that the firewall allows traffic on the forwarded ports. Usually, enabling the "Private Network" profile for WSL-related processes handles this, but you can manually create inbound rules for ports 5222 and 5269 if necessary. Once configured, test the connection using an XMPP client like Gajim or Pidgin. Set the server address toyourdomain.com and the port to 5222. The client should connect successfully because the request hits localhost, passes through the forwarding layer, reaches the WSL2 Prosody instance listening on 0.0.0.0, and is processed normally.
For more advanced networking scenarios involving mirrored network modes, refer to WSL2 and Mirrored Network Mode: A Compatibility Overview for Dev Projects, though standard port forwarding is sufficient for most Prosody deployments.
Frequently Asked Questions
Why does my XMPP client fail to connect despite correct credentials?
The failure is usually due to SSL/TLS certificate mismatches or incorrect host resolution. Ensure that the certificate provided to Prosody matches the domain name exactly. Additionally, verify that your Windows hosts file points the domain to 127.0.0.1, as clients cannot resolve the WSL2 dynamic IP directly.Can I use a static IP instead of port forwarding?
While technically possible by scripting a DHCP reservation, it is highly discouraged. WSL2 IPs change frequently due to its virtualized nature. Port forwarding via.wslconfig is the supported and robust method designed specifically to handle these dynamic changes transparently.
What if I get a connection refused error on port 5222?
Check if Prosody is actually listening on0.0.0.0 inside WSL2 using ss -tlnp | grep 5222. If it only shows 127.0.0.1, update the interfaces setting in prosody.cfg.lua to include 0.0.0.0 and restart the service. Also confirm that Windows Firewall is not blocking the forwarded traffic.
Does this setup work for server-to-server (S2S) connections?
Yes, but you must also forward port 5269 in your.wslconfig file. Other XMPP servers attempting to connect to your domain will hit the public IP of your Windows machine, which then forwards the traffic to the WSL2 instance on port 5269. Ensure your DNS MX records point to your Windows public IP.