mtu-warden

mtu-warden is a production-grade Linux MTU controller for WAN and tunnel-heavy servers.

It is designed for operators who need deterministic MTU behavior in real-world anti-DDoS, overlay, and mixed datacenter environments, while staying safe by default: no route mutation, no blind mass-editing, and clear rollback state.

Overview

mtu-warden provides a full operational cycle:

1. Detect interfaces and classify transport/tunnel roles.
2. Recommend safe WAN and per-tunnel MTUs from PMTU probing and overhead models.
3. Apply MTU and MSS clamp changes idempotently.
4. Persist state and rollback exactly what was changed.

Why

MTU failures are often subtle:

• TCP handshakes work but data stalls.
• Some destinations fail while others succeed.
• Tunnel control plane appears healthy while payload traffic fragments or blackholes.

mtu-warden replaces brittle one-off scripts with a repeatable and auditable workflow.

Who Should Use This?

• Operators running anti-DDoS paths where PMTU behavior changes under mitigation
• Teams managing mixed tunnel stacks (WireGuard, GRE, L2TPv3, VXLAN/Geneve, IPIP/SIT, VTI)
• SRE/NetOps teams who need safe idempotent reconciliation and rollback instead of ad-hoc shell scripts
• Providers or self-hosters who want deterministic MTU policy across reboot and interface churn

Features

• Safe default WAN detection via ip route get 1.1.1.1
• Structured interface classification and conservative filtering
• Profile-driven MTU policy for WAN and multiple tunnel families
• tunnel_patterns mapping for custom interface naming (including backhaul layouts)
• PMTU recommendation with bounded binary-search probing and retries
• MSS clamp management with backend autodetect (nftables preferred, iptables fallback)
• Idempotent firewall rule handling (no duplicate clamp rules)
• Conservative firewall ownership: only mtu-warden-managed iptables clamp rules are removed
• Stateful rollback in /var/lib/mtu-warden/state.json
• Systemd oneshot + timer reconciliation for interfaces appearing after boot
• Structured logs with TTY-aware color and plain non-interactive output

Supported Tunnels & Transports

• GRE
• GRETAP
• IP6GRE
• ERSPAN
• L2TPv3 UDP encapsulation
• L2TPv3 IP encapsulation
• WireGuard
• VXLAN
• Geneve
• IPIP
• SIT
• VTI/IPsec
• PPP/PPPoE-style interfaces
• Backhaul patterns via profile-defined tunnel_patterns

Backhaul note: when a backhaul product does not create a dedicated kernel tunnel interface, mtu-warden still manages WAN MTU and MSS clamping safely, and can target additional interfaces through include_patterns and tunnel_patterns.

Install

Supported targets:

• Ubuntu 20.04, 22.04
• Debian 11, 12

Install:

sudo bash scripts/install.sh

Install and enable timer:

sudo bash scripts/install.sh --enable-timer

Install behavior:

• Idempotent and safe to rerun
• Installs/upgrades required dependencies only
• Never runs dist-upgrade or full-upgrade
• Never removes packages
• Preserves existing /etc/mtu-warden configuration
• Installs binary to /usr/local/sbin/mtu-warden
• Installs systemd units, enables timer only when requested

Dependency check:

bash scripts/check-deps.sh

Quick Start

mtu-warden status

mtu-warden detect

mtu-warden recommend --profile parsabr

sudo mtu-warden apply --profile parsabr --yes

Profiles

Built-in profiles:

• parsabr
• generic-iran-antiddos
• hetzner
• ovh
• custom

Runtime overrides:

• Directory: /etc/mtu-warden/profiles.d/*.toml
• Override model: file/profile name matches built-in profile name, fields merge safely

Key profile fields:

• wan_mtu
• Per-tunnel MTUs: gre_mtu, gretap_mtu, ip6gre_mtu, erspan_mtu, l2tp_udp_mtu, l2tp_ip_mtu, wg_mtu, vxlan_mtu, geneve_mtu, ipip_mtu, sit_mtu, vti_mtu, ppp_mtu, backhaul_mtu
• mss_clamp_on
• include_patterns / exclude_patterns
• [tunnel_patterns]
• [overhead_overrides]

Recommend

Read-only recommendation report:

mtu-warden recommend --profile parsabr

JSON output:

mtu-warden recommend --profile parsabr --json

Custom probe targets:

mtu-warden recommend --profile parsabr --ipv4-host 1.1.1.1 --ipv6-host 2606:4700:4700::1111

Apply

Preview changes without mutation:

sudo mtu-warden --dry-run apply --profile parsabr --yes

Apply profile non-interactively:

sudo mtu-warden apply --profile parsabr --yes

Manual one-interface operation:

sudo mtu-warden set --iface wg0 --mtu 1320 --mss-clamp on --yes

Rollback

Rollback the last persisted operation:

sudo mtu-warden rollback --yes

Rollback preview:

sudo mtu-warden --dry-run rollback --yes

Systemd

Shipped units:

• packaging/systemd/mtu-warden.service
• packaging/systemd/mtu-warden.timer

Timer defaults:

• OnBootSec=30
• OnUnitActiveSec=2min

Manual timer control:

sudo systemctl daemon-reload

sudo systemctl enable --now mtu-warden.timer

sudo systemctl status mtu-warden.timer

Troubleshooting

Check current state:

mtu-warden status

Re-run recommendation:

mtu-warden recommend --profile generic-iran-antiddos

Validate interface classification:

mtu-warden detect --profile parsabr

Confirm dependencies:

bash scripts/check-deps.sh

If PMTUD remains unstable:

• Verify ICMP fragmentation-needed handling on upstream path.
• Keep MSS clamp enabled for affected path segments.
• Re-run recommendation after provider or routing-path changes.

Safety Notes

• apply, set, and rollback are mutating commands and should run with root privileges.
• status, detect, and recommend are safe read-oriented operations.
• --dry-run avoids system mutation for mutating commands.
• MTU guardrail is enforced (576..9216).
• Routes are never changed by mtu-warden.

Project Status

mtu-warden is release-ready for v1.0.0 with production-focused defaults, rollback, idempotent firewall management, and timer-based reconciliation.

License

Licensed under GNU GPLv3. See LICENSE.

Maintainer

Maintained by YrustPd.

• GitHub: https://github.com/YrustPd
• Project: https://github.com/YrustPd/mtu-warden

Support / Contact

• Issues: https://github.com/YrustPd/mtu-warden/issues
• Maintainer profile: https://github.com/YrustPd