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 (May 2026):

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 firewall-appliance)
• Web browsing, scraping, or headless page interaction - use browse
• Kubernetes networking: NetworkPolicy, Gateway API, service mesh, CNI (use kubernetes)
• Broad Kubernetes cluster health checks, node status, and post-maintenance diagnostics (use cluster-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 lockpick)
• Application-level security review, SSRF, header injection (use security-audit)

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: nftables rules need nft list ruleset > /etc/nftables.conf or a 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

• Current source checked: dated versions, CLI flags, API names, and support windows are verified against primary docs before repeating them
• Hidden state identified: local config, credentials, caches, contexts, branches, cluster targets, or previous runs are made explicit before acting
• Verification is real: final checks exercise the actual runtime, parser, service, or integration point instead of only linting prose or happy paths
• 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

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.

Best Practices

• Diagnose before changing: capture current routes, rules, addresses, and resolver state.
• Change one layer at a time: DNS, routing, firewall, proxy, VPN, or application.
• Keep emergency access open when editing firewall, VPN, or default-route configuration remotely.

Workflow

Step 1: Identify the task type

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. Network misconfigs can lock you out. If working over SSH, set a revert timer (at now + 5 minutes <<< 'systemctl restart networking').
• Log what you changed. Network debugging is 10x harder when you don't know what changed.

Step 4: Validate

Quick Reference: Diagnostic Tools

Quick Reference: CIDR Cheat Sheet

Private ranges (RFC 1918): 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 CGNAT (RFC 6598): 100.64.0.0/10 (used by Tailscale, carrier NAT) Link-local: 169.254.0.0/16 (IPv4), fe80::/10 (IPv6) ULA (IPv6): fd00::/8 (private, like RFC 1918 for IPv6)

Quick Reference: DNS Record Types

Quick Reference: Reverse Proxy Selection

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

WireGuard site-to-site quick start

# 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 = 1420 for most setups; subtract 80 more if over PPPoE

[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). Key generation: wg genkey | tee privatekey | wg pubkey > publickey.

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-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:

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

Output Contract

See skills/_shared/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, emit the full contract -- boxed inline header, body summary inline plus per-finding detail in the deliverable file, boxed conclusion, conclusion table -- 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

• firewall-appliance - manages BSD-based firewall appliances (OPNsense, pfSense). This skill handles Linux networking; firewall-appliance handles FreeBSD appliance firewalls. If the user mentions pfctl, CARP, or OPNsense/pfSense hostnames, route to firewall-appliance.
• kubernetes - owns K8s networking (NetworkPolicy, Gateway API, service mesh, CNI). This skill covers general DNS and proxy config; K8s-specific networking goes to kubernetes.
• cluster-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.
• lockpick - 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).
• browse - web browsing, scraping, headless page interaction. This skill covers network infrastructure, not web content retrieval.

Rules

1. Ask which interface. Never assume eth0. Modern Linux uses predictable interface names. Check with ip link or ask the user.
2. Test before persisting. Network misconfigs can lock you out of remote machines. Apply changes temporarily, verify connectivity (especially SSH), then persist.
3. MTU matters. VPN tunnels, VXLAN, and PPPoE all reduce effective MTU. Mismatched MTU causes silent packet drops that are painful to debug. Always calculate and set explicitly.
4. Check who manages DNS. systemd-resolved, NetworkManager, and manual /etc/resolv.conf fight each other. Identify the active manager before making DNS changes.
5. 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.
6. 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.
7. Subnet overlap kills VPNs. Before assigning VPN address ranges, inventory all LAN subnets and existing VPN ranges. Overlapping ranges cause routing black holes.
8. Defer to specialized skills. OPNsense/pfSense -> firewall-appliance. K8s networking -> kubernetes. Container networking -> docker. Cloud infra -> terraform. Pentesting -> lockpick.