networking

Networking: Configuration, Troubleshooting, and Optimization

Configure, troubleshoot, and optimize Linux networking infrastructure. Covers DNS, reverse proxies, VPNs, firewalls (nftables), VLANs, subnetting, high availability, dynamic routing, and network performance tuning.

Target versions (October 2026):

Tool	Version	Notes
Caddy	2.11.6	Auto-HTTPS, Caddyfile + JSON API; GHSA-6365-7ppr-5r92 is fixed since 2.11.5
Nginx	1.30.5 stable / 1.31.6 mainline	Patched for CVE-2026-90439; includes fixes for CVE-2026-42533/60005/56434
Traefik	3.7.13 (v2 lane 2.11.57)	Gateway API native, v2 EOL approaching
HAProxy	3.4.6 LTS / 3.3.16 stable / 3.2.25 LTS	3.4 LTS EOL 2031-Q2
WireGuard tools	1.0.20260223	Kernel module + userspace tools
strongSwan	6.1.0 (fixes CVE-2026-78133 and ten others, 2026-09-07)	swanctl config (legacy ipsec.conf deprecated)
nftables	1.1.7	iptables successor, default on modern distros
keepalived	2.4.3	VRRP + health checks
Unbound	1.26.1	Security floor after the 2026-09-16 advisories
CoreDNS	1.14.7	K8s default DNS, plugin-based
FRRouting	10.7.1	Released 2026-08-31 alongside 10.6.2/10.5.5/10.4.5
Tailscale / Headscale	Headscale 0.29.4	Self-hosted control server
cloudflared	2026.9.3	Cloudflare Tunnel (outbound-only)
OpenVPN	2.7.7 / 2.6.23 LTS	2.7.x: multi-socket, DCO; 2.6 is the LTS branch

Security recheck (2026-10-02): nginx's publisher advisories rate CVE-2026-90439 (HTTP/3 buffer overflow) medium: affected 1.29.2-1.31.5, fixed in 1.30.5+ or 1.31.6+. CVE-2026-42533 (map/regex buffer overflow) major: affected 0.9.6-1.31.2, fixed in 1.30.4+ or 1.31.3+; CVE-2026-60005 and CVE-2026-56434 were fixed in those same 1.30.4+/1.31.3+ releases. CVE-2026-42530 (HTTP/3 use-after-free) affects 1.31.0-1.31.1 and is fixed in 1.31.2+. The separate, earlier CVE-2026-42945 (rewrite buffer overflow) was fixed in 1.30.1/1.31.0. Check enabled modules and vendor backports. Unbound advisories also rate CVE-2026-32665 high: DoQ-enabled 1.22.0-1.25.1 is affected, with a fix in 1.25.2. Check compile-time DoQ support and configured listeners before assessing exposure.

When to use

• Configuring DNS servers (Unbound, CoreDNS, dnsmasq, BIND9, Pi-hole, AdGuard Home)
• Setting up or troubleshooting reverse proxies and load balancers
• VPN configuration (WireGuard, OpenVPN, IPsec) and overlay networks
• Linux firewall rules (nftables, legacy iptables)
• VLAN configuration, subnetting, network segmentation
• High availability with keepalived/VRRP, floating IPs
• Network diagnostics (tcpdump, mtr, ss, dig, iperf3, Wireshark/tshark)
• TCP/network performance tuning (MTU, buffers, congestion control, bufferbloat)
• Dynamic routing with FRRouting (BGP, OSPF)
• TLS/certificate management for network services
• Split-horizon DNS, DNS-over-HTTPS/TLS, DNSSEC

When NOT to use

• OPNsense/pfSense firewall appliance management (use opnsense-pfsense)
• Web browsing, scraping, or headless page interaction - use the host's browsing tools
• Kubernetes networking: NetworkPolicy, Gateway API, service mesh, CNI (use kubernetes)
• Broad Kubernetes cluster health checks, node status, and post-maintenance diagnostics (use kubernetes-health)
• Docker/container networking: bridge, overlay, Compose networks (use docker)
• Cloud VPCs, security groups, managed load balancers (use terraform)
• Network config management at scale via playbooks (use ansible)
• Offensive pentesting, exploitation, lateral movement (use privilege-escalation)
• Application-level security review, SSRF, header injection (use security-audit)
• CI/CD-automated network configuration management at pipeline scale (use ci-cd)

---

AI Self-Check

Before returning any generated network configuration, verify:

• No hardcoded secrets: passwords, PSKs, API keys use placeholders or env vars
• Correct interface names: didn't assume eth0 - modern Linux uses predictable names (enp0s3, ens18, etc.). Ask or check ip link output
• MTU considered: VPN tunnels need reduced MTU (WireGuard: 1420, OpenVPN: ~1400, VXLAN: 1450). Mismatched MTU causes silent packet drops
• DNS resolver order: systemd-resolved vs /etc/resolv.conf vs NetworkManager - check which DNS manager is active before modifying
• Firewall persistence: install the validated rules file as /etc/nftables.conf and enable nftables.service to persist across reboots. Raw nft add commands are ephemeral
• Port conflicts checked: reverse proxy ports (80, 443) may conflict with existing services. Verify with ss -tlnp
• TLS versions: minimum TLS 1.2 for all services. TLS 1.3 preferred where supported
• Private IP ranges correct: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (not /24)
• Subnet overlap: VPN address ranges must not overlap with LAN or other VPN ranges
• IPv6 considered: dual-stack config or explicit disable. Half-configured IPv6 leaks traffic around IPv4-only VPNs
• Backup before modifying: save current config before changes (nft list ruleset > backup.nft, cp nginx.conf nginx.conf.bak). Network misconfigs can lock out remote access
• Service reload vs restart: prefer graceful reload (nginx -s reload, systemctl reload) over restart to avoid dropping active connections
• IP forwarding enabled: any config involving routing, VPN, or inter-VLAN traffic needs net.ipv4.ip_forward = 1 (and net.ipv6.conf.all.forwarding = 1 for dual-stack). Without it, the kernel silently drops forwarded packets
• systemd-resolved conflict: if deploying a local DNS server (Unbound, CoreDNS, dnsmasq), check whether systemd-resolved is binding port 53. Disable its stub listener (DNSStubListener=no) or bind your server to a different port
• Topology verified: interface names, routes, DNS resolvers, namespaces, VPN state, and firewall backend are observed before changes
• Rollback path preserved: remote network changes include timed rollback, console access, or an alternate path
• Cross-cutting agent hygiene applied - see references/agent-hygiene.md

---

Performance

• Measure path, DNS, TLS, and application latency separately before tuning.
• Use packet captures with narrow filters and time windows to avoid huge captures and privacy spill.
• Prefer persistent nftables sets, DNS caches, and proxy connection reuse where appropriate.

Workflow

For any change, copy this checklist and track progress:

- [ ] Step 1: Task type identified and matching reference read
- [ ] Step 2: Current state captured (addresses, routes, firewall, DNS manager, VPNs)
- [ ] Step 3: One change applied with a saved config and an armed rollback
- [ ] Step 4: Validated (on failure: restore, fix, return to Step 3)

Step 1: Identify the task type

Task type	Start with	Reference
Troubleshoot	Symptoms, recent changes, affected scope	references/troubleshooting.md
Configure DNS	Current resolver, authoritative vs recursive, split-horizon needs	references/dns.md
Set up reverse proxy	Which proxy, upstream services, TLS requirements	references/reverse-proxies.md
Configure VPN	Topology (p2p, hub-spoke, mesh), protocol choice	references/vpn.md
Network segmentation	VLANs, subnets, nftables zones, namespaces	references/segmentation.md
High availability	keepalived/VRRP, floating IPs, health checks	references/ha.md

Step 2: Gather context

Before writing config or running commands:

1. What distro and init system? (systemd vs OpenRC - affects service management)
2. What's the current network state? (ip addr, ip route, ss -tlnp, resolvectl status)
3. Is there an existing firewall? (nft list ruleset, iptables-save)
4. Who manages DNS? (resolvectl status or cat /etc/resolv.conf - check for systemd-resolved stub)
5. Any existing VPN/overlay? (wg show, tailscale status, ip link for tun/wg/vxlan devices)
6. Is this behind NAT? (affects VPN, reverse proxy, and HA design)

Step 3: Implement

Read the appropriate reference file for detailed patterns. Key principles:

• Test before persisting. Add nftables rules, verify connectivity, then save. Apply reverse proxy config changes with --dry-run or syntax check first (caddy validate, nginx -t, haproxy -c).
• One change at a time. Over SSH, save the exact rules/routes/manager configuration being changed and schedule a tested restoration command before applying. A generic networking restart is not a rollback. Verify the timer exists with systemctl list-timers nft-rollback.timer; cancel it only after a second session confirms management access and the intended allowed/blocked traffic. For nftables, run exactly:

  nft -c -f new.nft                                  # syntax check; stop on error
  { echo 'flush ruleset'; nft list ruleset; } > /root/nft-rollback.nft
  systemd-run --on-active=5m --unit=nft-rollback \
    nft -f /root/nft-rollback.nft                   # one atomic transaction
  nft -f new.nft
  systemctl list-timers nft-rollback.timer           # confirm the rollback is armed
  systemctl stop nft-rollback.timer                  # only after the second-session check
  

• Log what you changed. Network debugging is 10x harder when you don't know what changed.

Step 4: Validate

If a check fails, restore the saved configuration (or let the rollback timer fire), fix the change, and return to Step 3. Detect missing tools first: for t in dig mtr tcpdump iperf3 nft wg; do command -v "$t" >/dev/null || echo "missing: $t"; done

What to validate	How
DNS resolution	dig @server domain A +short, dig domain AAAA +short
Reverse proxy	curl -v https://domain (verify certificate trust, headers, upstream response)
VPN tunnel	wg show (WireGuard), ping across tunnel, check ip route
Firewall rules	nft list ruleset, test both allowed and blocked traffic
VLAN tagging	ip -d link show, tcpdump -e -i interface (check 802.1Q tags)
HA failover	Stop primary, verify VIP migrates, check journalctl -u keepalived
Performance	iperf3 -c server, mtr target, check for packet loss and jitter

---

Quick Reference: Diagnostic Tools

Tool	Purpose	Key usage
ip	Interface, route, neighbor, rule management	ip addr, ip route, ip neigh, ip link
ss	Socket statistics (replaces netstat)	ss -tlnp (TCP listeners), ss -ulnp (UDP)
dig	DNS queries	dig @8.8.8.8 example.com A +short
mtr	Combined traceroute + ping	mtr -n --report target (non-interactive)
tcpdump	Packet capture	tcpdump -i any -nn port 53 (DNS traffic)
tshark	Wireshark CLI	tshark -i any -f 'port 443' -Y 'tls.handshake'
curl	HTTP testing	curl -v -o /dev/null https://target (verified TLS and HTTP details)
iperf3	Bandwidth testing	Server: iperf3 -s / Client: iperf3 -c server
nft	nftables rule management	nft list ruleset, nft monitor trace
wg	WireGuard status	wg show, wg showconf wg0
resolvectl	systemd-resolved status	resolvectl status, resolvectl query domain
nmap	Port scanning, service detection	nmap -sV -p 1-1024 target
socat	Multipurpose relay	socat TCP-LISTEN:8080,fork TCP:backend:80

---

Quick Reference: CIDR and DNS

CIDR/netmask and DNS record-type lookup tables live in references/cheat-sheets.md. Load that file only when a task needs the literal mapping.

---

Quick Reference: Reverse Proxy Selection

Proxy	Best for	TLS	Config style	L4 support
Caddy	Simple setups, auto-HTTPS	Automatic (ACME)	Caddyfile / JSON API	Yes (experimental)
Nginx	High traffic, static files	Manual or certbot	nginx.conf	Yes (stream module)
Traefik	Docker/K8s, dynamic backends	Automatic (ACME)	Labels / file / K8s CRDs	Yes (TCP/UDP)
HAProxy	Pure load balancing, L4/L7	Manual	haproxy.cfg	Yes (native)

Default to Caddy for a new single-host setup; keep the proxy already deployed when there is one.

Caddy reverse proxy quick start

# /etc/caddy/Caddyfile - three subdomains, auto-HTTPS
app.example.com {
    reverse_proxy localhost:3000
}

api.example.com {
    reverse_proxy localhost:8080
}

grafana.example.com {
    reverse_proxy localhost:3001
}

Caddy handles TLS certificate provisioning automatically via ACME (Let's Encrypt). DNS A/AAAA records for all three subdomains must point to the host. Validate: caddy validate --config /etc/caddy/Caddyfile.

Read references/reverse-proxies.md for configuration patterns, TLS setup, health checks, rate limiting, and WebSocket/gRPC proxying.

---

Quick Reference: VPN Protocol Selection

Protocol	Speed	Complexity	Key exchange	Best for
WireGuard	Fastest	Minimal config	Noise (Curve25519)	P2P, hub-spoke, general use
OpenVPN	Good	Complex PKI	TLS/x509	Legacy, tap mode (L2)
IPsec (strongSwan)	Good	Most complex	IKEv2	Site-to-site, standards compliance
Tailscale/Headscale	Fast (WG underneath)	Zero config	WG + DERP relays	Overlay mesh, remote access
Nebula	Fast	Low	Certificate-based	Large mesh, Slack-scale

Default to WireGuard; choose another only for a need in its "Best for" column.

WireGuard site-to-site quick start

Each peer must route its local LAN. If WireGuard runs on a separate host rather than the LAN's default gateway, add a route on each LAN gateway for the remote LAN via its local WireGuard host. Verify return routes, forwarding and firewall policy in both directions; tunnel-peer pings alone do not prove LAN-to-LAN connectivity.

# Site A (/etc/wireguard/wg0.conf) - 10.0.1.0/24
[Interface]
PrivateKey = <SITE_A_PRIVATE_KEY>
Address = 10.100.0.1/30
ListenPort = 51820
# MTU: derive from measured underlay; 1420 for 1500-byte underlay with 80-byte overhead,
# or 1412 for a 1492-byte PPPoE underlay with the same overhead.

[Peer]
PublicKey = <SITE_B_PUBLIC_KEY>
Endpoint = site-b.example.com:51820
AllowedIPs = 10.0.2.0/24, 10.100.0.2/32
PersistentKeepalive = 25

# Site B (/etc/wireguard/wg0.conf) - 10.0.2.0/24
[Interface]
PrivateKey = <SITE_B_PRIVATE_KEY>
Address = 10.100.0.2/30
ListenPort = 51820

[Peer]
PublicKey = <SITE_A_PUBLIC_KEY>
Endpoint = site-a.example.com:51820
AllowedIPs = 10.0.1.0/24, 10.100.0.1/32
PersistentKeepalive = 25

Both sides need net.ipv4.ip_forward = 1 in /etc/sysctl.d/. AllowedIPs is the remote subnet (not 0.0.0.0/0 - that's full-tunnel, not site-to-site). Generate keys in a new protected directory with umask 077, following references/vpn.md; never overwrite existing keys.

Read references/vpn.md for setup patterns, key management, MTU tuning, NAT traversal, and overlay network comparison.

---

Quick Reference: nftables vs iptables

iptables is legacy. nftables is the default on Debian 11+, RHEL 9+, Arch, and most modern distros.

# Minimal nftables ruleset - stateful firewall with SSH
table inet filter {
  chain input {
    type filter hook input priority 0; policy drop;
    ct state established,related accept
    iif lo accept
    tcp dport 22 accept
    icmp type echo-request accept
    icmpv6 type { echo-request, nd-neighbor-solicit, nd-neighbor-advert, nd-router-advert } accept
  }
  chain forward { type filter hook forward priority 0; policy drop; }
  chain output { type filter hook output priority 0; policy accept; }
}

Read references/segmentation.md for VLAN setup, nftables zones, network namespaces, and inter-VLAN routing patterns.

---

PCI-DSS 4.0 Relevance

Network configuration touches several PCI-DSS requirements:

Req	Area	What to check
1.2	Network security controls	Firewall rules restrict inbound/outbound to minimum necessary
1.3	CDE segmentation	VLANs, nftables, or physical separation between CDE and other networks
1.4	Trusted/untrusted boundaries	Reverse proxy TLS termination, WAF placement
2.2	Hardening	Disable unnecessary services, unused ports closed
4.1	Encryption in transit	TLS 1.2+ everywhere, no plaintext on untrusted segments
11.3	Network monitoring	IDS/IPS (Suricata), log aggregation, flow analysis

---

Reference Files

• references/dns.md - DNS server comparison, DNSSEC, split-horizon, DoH/DoT, Pi-hole/AdGuard, troubleshooting
• references/reverse-proxies.md - Caddy, Nginx, Traefik, HAProxy configuration patterns, TLS, WebSocket, gRPC, rate limiting
• references/vpn.md - WireGuard, OpenVPN, IPsec/strongSwan setup, overlay networks (Tailscale, Headscale, Nebula, ZeroTier), key management
• references/segmentation.md - VLANs, subnetting, nftables firewall patterns, network namespaces, IPv6
• references/troubleshooting.md - Diagnostic methodology, tool deep-dives, common issues, performance tuning
• references/ha.md - keepalived/VRRP, floating IPs, HAProxy + keepalived HA, health check patterns
• references/cheat-sheets.md - CIDR/netmask table, private/CGNAT/link-local/ULA ranges, DNS record types

Output Contract

See references/output-contract.md for the full contract.

• Skill name: NETWORKING
• Deliverable bucket: audits
• Mode: conditional. When invoked to analyze, review, audit, or improve existing repo content, apply the reporting size and evidence rules in references/output-contract.md and write the deliverable to docs/local/audits/networking/<YYYY-MM-DD>-<slug>.md. When invoked to answer a question, teach a concept, build a new artifact, or generate content, respond freely without the contract.
• Severity scale: P0 | P1 | P2 | P3 | info (see shared contract; only used in audit/review mode).

Related Skills

• opnsense-pfsense - manages BSD-based firewall appliances (OPNsense, pfSense). This skill handles Linux networking; opnsense-pfsense handles FreeBSD appliance firewalls. If the user mentions pfctl, CARP, or OPNsense/pfSense hostnames, route to opnsense-pfsense.
• kubernetes - owns K8s networking (NetworkPolicy, Gateway API, service mesh, CNI). This skill covers general DNS and proxy config; K8s-specific networking goes to kubernetes.
• kubernetes-health - owns read-only Kubernetes cluster diagnostics. If the request is "is the cluster healthy?" rather than "configure DNS/proxy/routing", route there.
• docker - owns container networking (bridge, Compose networks, port mapping). This skill covers host-level Linux networking.
• terraform - owns cloud infrastructure (VPCs, security groups, cloud LBs, Route53). This skill covers bare-metal/VM networking.
• ansible - manages config at scale via playbooks. This skill provides the networking knowledge; ansible handles the automation wrapper.
• privilege-escalation - offensive network testing, exploitation, lateral movement. This skill covers defensive configuration and hardening.
• security-audit - application-level security review (SSRF, header injection). This skill covers network-layer security (firewalls, TLS, segmentation).
• Web content retrieval uses the host's browsing tools; this skill configures network infrastructure.
• ci-cd - pipeline design for automated network config management. This skill provides the networking knowledge; ci-cd handles pipeline orchestration around it.

Rules

1. Verify the existing firewall. Check nft list ruleset and iptables-save before adding rules. Mixing nftables and iptables on the same system causes unpredictable behavior.
2. No plaintext on untrusted segments. TLS 1.2+ for all services. If something needs to cross an untrusted network without TLS, tunnel it through a VPN.