docs(readme): add polished installation, usage, automation examples and author info
https://chatgpt.com/share/697112b2-0410-800f-93ff-9372b603d43f
This commit is contained in:
175
README.md
175
README.md
@@ -1,34 +1,181 @@
|
||||
# automtu
|
||||
# 🚀 automtu — Automatic Path MTU Detection for Linux & WireGuard
|
||||
|
||||
[](https://github.com/sponsors/kevinveenbirkenbach) [](https://www.patreon.com/c/kevinveenbirkenbach) [](https://buymeacoffee.com/kevinveenbirkenbach) [](https://s.veen.world/paypaldonate)
|
||||
|
||||
Auto-detect your egress interface, optionally probe Path MTU (PMTU) using DF-ping,
|
||||
compute a WireGuard MTU, and apply MTU settings.
|
||||
**automtu** is a small but powerful CLI tool that automatically detects your egress interface, probes the Path MTU (PMTU), computes a safe MTU for WireGuard, and optionally applies it — or simply prints it for automation tools like **Ansible**.
|
||||
|
||||
## Install (editable)
|
||||
Perfect for:
|
||||
|
||||
* Docker-in-Docker (DiD)
|
||||
* WireGuard tunnels
|
||||
* Cloud VPS setups
|
||||
* CI runners
|
||||
* NAT / overlay networks
|
||||
|
||||
No more TLS handshake timeouts. No more guessing MTU values.
|
||||
Just reliable networking. ✅
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
* 🔍 Auto-detects your egress interface (`eth0`, `ens3`, etc.)
|
||||
* 📡 Probes Path MTU using DF-ping (`ping -M do`)
|
||||
* 🧮 Computes a safe WireGuard MTU (`effective_mtu - overhead`)
|
||||
* 🔐 Supports WireGuard peer auto-discovery
|
||||
* ⚙️ Optional automatic MTU application
|
||||
* 🤖 Machine-readable output for Ansible / CI
|
||||
* 📦 JSON output for automation pipelines
|
||||
* 🧪 Fully unit-tested
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Option 1 — Install via pip (recommended)
|
||||
|
||||
```bash
|
||||
pip install automtu
|
||||
```
|
||||
|
||||
or editable mode for development:
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Usage
|
||||
---
|
||||
|
||||
Show only (no changes):
|
||||
### Option 2 — Local installation from source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/kevinveenbirkenbach/automtu.git
|
||||
cd automtu
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
Now the `automtu` command is available system-wide.
|
||||
|
||||
---
|
||||
|
||||
## 🚦 Usage
|
||||
|
||||
### 🔍 Show detected MTU (no changes)
|
||||
|
||||
```bash
|
||||
automtu --dry-run
|
||||
```
|
||||
|
||||
Probe PMTU to targets and apply on egress:
|
||||
sudo automtu --pmtu-target registry-1.docker.io --apply-egress-mtu
|
||||
---
|
||||
|
||||
Auto-add WireGuard peer endpoints as targets and apply WG MTU:
|
||||
### 📡 Probe PMTU and apply to egress interface
|
||||
|
||||
```bash
|
||||
sudo automtu --pmtu-target 1.1.1.1 --apply-egress-mtu
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🔐 Auto-detect WireGuard peers and apply WG MTU
|
||||
|
||||
```bash
|
||||
sudo automtu --auto-pmtu-from-wg --apply-wg-mtu
|
||||
```
|
||||
|
||||
Force WG MTU:
|
||||
sudo automtu --set-wg-mtu 1372 --apply-wg-mtu
|
||||
---
|
||||
|
||||
Help:
|
||||
automtu --help
|
||||
### ⚡ Prefer WireGuard as egress if default route uses wg0
|
||||
|
||||
```bash
|
||||
sudo automtu --prefer-wg-egress --auto-pmtu-from-wg --apply-wg-mtu
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🧮 Print only the MTU number (for Ansible & scripts)
|
||||
|
||||
```bash
|
||||
automtu --print-mtu effective
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
1452
|
||||
```
|
||||
|
||||
Perfect for:
|
||||
|
||||
```yaml
|
||||
- name: Detect MTU
|
||||
command: automtu --print-mtu effective
|
||||
register: mtu
|
||||
|
||||
- name: Apply MTU
|
||||
command: ip link set mtu {{ mtu.stdout }} dev eth0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 📤 JSON output (CI / automation)
|
||||
|
||||
```bash
|
||||
automtu --print-json
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
{
|
||||
"egress": { "iface": "eth0", "base_mtu": 1500, "effective_mtu": 1452 },
|
||||
"pmtu": { "policy": "min", "chosen": 1452 },
|
||||
"wg": { "iface": "wg0", "mtu": 1372 },
|
||||
"dry_run": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡 Notes
|
||||
|
||||
* Applying MTU requires root (`sudo`) unless `--dry-run` is used
|
||||
* PMTU probing may fail if ICMP is blocked — fallback is automatic
|
||||
* MTU changes are runtime-only (not persistent across reboot)
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Why automtu?
|
||||
|
||||
Because networking stacks are layered, tunneled, NATed and virtualized.
|
||||
Path MTU matters — especially for:
|
||||
|
||||
* Docker-in-Docker
|
||||
* VPN tunnels
|
||||
* Cloud providers
|
||||
* Kubernetes nodes
|
||||
* CI runners
|
||||
|
||||
automtu removes guesswork and prevents hard-to-debug TLS timeouts.
|
||||
|
||||
---
|
||||
|
||||
## 👤 Author
|
||||
|
||||
**Kevin Veen-Birkenbach**
|
||||
[https://www.veen.world](https://www.veen.world)
|
||||
🌍 [https://www.iveen.world](https://www.iveen.world)
|
||||
|
||||
Open Source, Automation, Infrastructure & Digital Sovereignty.
|
||||
|
||||
---
|
||||
|
||||
## ❤️ Support
|
||||
|
||||
If automtu helped you, consider supporting the project:
|
||||
|
||||
* ⭐ Star on GitHub
|
||||
* ☕ Buy Me a Coffee
|
||||
* 💙 GitHub Sponsors
|
||||
|
||||
---
|
||||
|
||||
Happy networking! 🌐✨
|
||||
|
||||
Reference in New Issue
Block a user