Firewall setup

Overview

When two machines link up, the one being connected to needs its firewall to accept an inbound UDP packet on port 4252. Outbound traffic is allowed by default everywhere, so the sender never needs configuring. If you can only connect in one direction, it's the firewall on the receive side.

Quick path: mousehop firewall

Mousehop ships a subcommand that detects your active firewall and adds the inbound rule for you — the one-command alternative to the manual steps below.

sudo mousehop firewall            # Linux: detect the firewall and add the rule
mousehop firewall                 # Windows: run from an elevated (Administrator) shell
mousehop firewall --dry-run       # print what it would do, change nothing
sudo mousehop firewall --remove   # tear the rule back out

It opens the port Mousehop is actually configured to use (default 4252), so a custom port is handled automatically. What happens depends on what's running:

• UFW and firewalld — adds the rule directly (firewalld on your default zone, then reloads).
• Windows Firewall — adds an inbound UDP rule via netsh advfirewall.
• nftables / iptables — prints the exact rule instead of running it, because the right table/chain is site-specific. Copy it into your ruleset.
• macOS — prints guidance only; the application firewall is per-app and off by default, so a signed Mousehop needs no port rule.

macOS

macOS uses an application-level firewall, not a port-level one. It's off by default on most installs, and Mousehop is signed and notarized, so most users have nothing to do.

First launch

The first time you start Mousehop, macOS may show: "Do you want the application 'Mousehop' to accept incoming network connections?" Click Allow. That's the whole flow.

If you missed the prompt, or your firewall is locked down

1. Open System Settings → Network → Firewall.
2. If Firewall is off, nothing to do — skip this section.
3. If on, click Options….
4. Click + and add Mousehop.app from /Applications.
5. Set the entry to Allow incoming connections.
6. Make sure Block all incoming connections is off — when that toggle is on, macOS ignores per-app allow rules.

You don't need to think about ports on macOS. The application firewall trusts the app, not a specific socket.

Windows

Windows Defender Firewall is on by default and prompts the first time Mousehop tries to listen. Catching that prompt is the fast path.

First launch

You'll see a Windows Security Alert dialog: "Do you want to allow Mousehop to communicate on these networks?" with two checkboxes — Private networks and Public networks. Tick Private at minimum. Only tick Public if you genuinely want Mousehop to work on public wifi (most people don't — see the safety note in the overview above).

If you missed the prompt (via the GUI)

1. Open Windows Security from the Start menu.
2. Go to Firewall & network protection → Allow an app through firewall.
3. Click Change settings, then Allow another app….
4. Browse to Mousehop.exe and add it.
5. Tick Private (and Public if you intend public-network use).

If you missed the prompt (via PowerShell)

Run as Administrator:

New-NetFirewallRule -DisplayName "Mousehop" -Direction Inbound `
  -Protocol UDP -LocalPort 4252 -Action Allow -Profile Private

This works even before Mousehop has been launched — useful for headless installs or imaging.

Linux

Linux is where most people get stuck, because there's no system-level prompt when an app binds a port. What you do depends on which firewall, if any, your distro ships with.

First — check whether you have a firewall at all

Plenty of Linux setups run with no firewall enabled: Arch base installs, NixOS without networking.firewall.enable, many bare server images. Before configuring anything, find out what's running:

sudo ufw status              # Ubuntu, Debian, Mint, Pop!_OS, Omarchy
sudo firewall-cmd --state    # Fedora, RHEL, CentOS Stream, openSUSE
sudo systemctl is-active nftables    # generic / minimal distros

If everything reports inactive / not running, nothing's blocking anything and Mousehop should just work. Skip ahead to Verifying.

UFW (Ubuntu, Debian, Mint, Pop!_OS, Omarchy)

UFW rules can be scoped two ways. Both work; pick whichever fits your situation.

By interface — survives subnet changes

Allow inbound on a specific NIC. The rule sticks to the interface, so changing networks (a new router, a hotel wifi, a different ISP) keeps it working. Mousehop's per-peer fingerprint pinning means the broader exposure isn't actually a security concern — unknown peers can't establish a session even with the port open.

sudo ufw allow in on wlan0 to any port 4252 proto udp comment 'mousehop'
sudo ufw allow in on enp0s31f6 to any port 4252 proto udp comment 'mousehop'

Run ip -br link to see your real interface names — usually something like wlan0 or wlp3s0 for wifi and enp0s31f6 or eth0 for ethernet.

By subnet — most conservative

Allow only from a specific LAN range. Mousehop is unreachable on any other network (café wifi, hotspots, hotel LANs). If you move to a different subnet you re-edit.

sudo ufw allow from 192.168.1.0/24 to any port 4252 proto udp comment 'mousehop'

Either way, verify with sudo ufw status verbose.

firewalld (Fedora, RHEL, CentOS Stream, openSUSE)

firewalld is zone-based. The rule almost certainly belongs in your home or internal zone — not public. Note that mousehop firewall adds the port to your default zone for speed; if your LAN interface is assigned to home or internal instead, use the zone-scoped commands below.

sudo firewall-cmd --get-active-zones        # find which zone your NIC is in
sudo firewall-cmd --zone=home --add-port=4252/udp --permanent
sudo firewall-cmd --reload

To scope by source subnet instead of a zone-wide allow, use a rich rule:

sudo firewall-cmd --zone=home --add-rich-rule='rule family="ipv4" \
  source address="192.168.1.0/24" port port="4252" protocol="udp" accept' \
  --permanent
sudo firewall-cmd --reload

nftables / iptables direct

If you hand-maintain your ruleset, the rule you want is:

# nftables
nft add rule inet filter input udp dport 4252 accept

# iptables
iptables -A INPUT -p udp --dport 4252 -j ACCEPT

Persist however your distro expects — nftables.service, iptables-persistent, NixOS module options, a hand-rolled unit, etc.

A note on mDNS discovery

Mousehop finds peers by hostname on the LAN using multicast DNS (mDNS) on 224.0.0.251:5353/udp. Most firewalls already allow this — UFW permits it in its default before-input chain, firewalld's trusted/home zones include it, and macOS/Windows handle it transparently.

If peers show up in the UI but won't connect, the issue is 4252. If they don't show up at all, you may additionally need to allow inbound 5353/udp on the LAN interface — but try the 4252 rule first, since that's the far more common cause.

Verifying

To confirm a peer can reach you:

• On the receiving machine, sudo ss -tulnp | grep mousehop shows the bound addresses. You should see 4252 on each LAN interface.
• From a sender on the same network, nc -u -zv <receiver-ip> 4252 probes reachability — but DTLS won't respond to a plain UDP probe, so a "succeeded" result only proves the firewall let the packet through, not that Mousehop accepted anything.
• The clearest signal is the UI itself — does the peer appear and authorize? If yes, you're done.

Still stuck? Open an issue with your OS, firewall tool, and the output of the relevant status command.