marslanalvi avatar

devops-infrastructure-networking

Terraform/IaC, Linux administration, shell scripting, networking and homelab

version
1.0.0
GitHub stars
5

Install

/plugin install devops-infrastructure-networking@skills-stack

Run it inside Claude Code after adding the marketplace with /plugin marketplace add marslanalvi/SkillsStack.

Contents

Discovered from source

Skills 21

/aegisops-ai β€” Autonomous Governance Orchestrator

AegisOps-AI is described by its upstream as a governance pipeline that integrates advanced AI reasoning directly into the SDLC. It acts as an intelligent gatekeeper for systems-level security, cloud infrastructure costs, and Kubernetes compliance.

Goal

To automate high-stakes security and financial audits by:

  1. Identifying logic-based vulnerabilities (UAF, Stale State) in Linux Kernel patches.
  2. Detecting massive "Silent Disaster" cost drifts in Terraform plans.
  3. Translating natural language security intent into hardened K8s manifests.

When to Use

  • Kernel Patch Review: Auditing raw C-based Git diffs for memory safety.
  • Pre-Apply IaC Audit: Analyzing terraform plan outputs to prevent bill spikes.
  • Cluster Hardening: Generating "Least Privilege" securityContexts for deployments.
  • CI/CD Quality Gating: Blocking non-compliant merges via GitHub Actions.

When Not to Use

  • Web App Logic: Do not use for standard web vulnerabilities (XSS, SQLi); use dedicated SAST scanners.
  • Non-C Memory Analysis: The patch analyzer is optimized for C-logic; avoid using it for high-level languages like Python or JS.
  • Direct Resource Mutation: This is an auditor, not a deployment tool. It does not execute terraform apply or kubectl apply.
  • Post-Mortem Analysis: For analyzing why a previous AI session failed, use /analyze-project instead.

πŸ€– Generative AI Integration

AegisOps-AI leverages the Google GenAI SDK to implement a "Reasoning Path" for autonomous security and financial audits:

  • Neural Patch Analysis: Performs semantic code reviews of Linux Kernel patches, moving beyond simple pattern matching to understand complex memory state logic.
  • Intelligent Cost Synthesis: Processes raw Terraform plan diffs through a financial reasoning model to detect high-risk resource escalations and "silent" fiscal drifts.
  • Natural Language Policy Mapping: Translates human security intent into syntactically correct, hardened Kubernetes securityContext configurations.

🧭 Core Modules

1. 🐧 Kernel Patch Reviewer (patch_analyzer.py)

  • Problem: Manual review of Linux Kernel memory safety is time-consuming and prone to human error.
  • Solution: A configured model proposes findings on raw Git diffs; verify each reachable trigger and consequence through code review and appropriate tests. No latency or detection guarantee is made.
  • Key Output: analysis_results.json

2. πŸ’° FinOps & Cloud Auditor (cost_auditor.py)

  • Problem: Infrastructure-as-Code (IaC) changes can lead to accidental "Silent Disasters" and massive cloud bill spikes.
  • Solution: Analyzes terraform plan output to identify cost anomaliesβ€”such as accidental upgrades from t3.micro to high-performance GPU instances.
  • Key Output: infrastructure_audit_report.json

3. ☸️ K8s Policy Hardener (k8s_policy_generator.py)

  • Problem: Implementing "Least Privilege" security contexts in Kubernetes is complex and often neglected.
  • Solution: Translates natural language security requirements into candidate YAML manifests requiring schema, policy and application validation (Read-only root FS, Non-root enforcement, etc.).
  • Key Output: hardened_deployment.yaml

πŸ› οΈ Setup & Environment

AAS bundles this guide only: patch_analyzer.py, cost_auditor.py, k8s_policy_generator.py, main.py and their reports are upstream components, not local bundled files. Verify the upstream repository, a fixed revision, license, dependencies, model availability and actual entry point before using the tool. Treat provider findings as advisory, not an automatic CI merge authority.

Obtain authorization for paid model calls and transmission of private patches, plans or cluster configuration. Redact secrets and personal/account identifiers; do not assume .env storage is automatically secure.

1. Clone the Repository

git clone https://github.com/Champbreed/AegisOps-AI.git
cd AegisOps-AI

2. Setup

python3 -m venv venv
source venv/bin/activate
pip install google-genai python-dotenv

3. API Configuration

Use the host's existing private credential mechanism for GEMINI_API_KEY. If a local .env is required by the reviewed upstream implementation, ensure it is owner-only and gitignored, preserve any existing file and never display its contents. Confirm the installed SDK/model combination instead of assuming an old model alias remains available.

🏁 Operational Dashboard

Only after reviewing the fixed upstream checkout and authorizing its network/cost effects, its documented entry point may be run there:

python3 main.py

Pattern: Over-Privileged Container

  • Indicators: allowPrivilegeEscalation: true or root user execution.
  • Investigation: Pass security intent (e.g., "non-root only") to the K8s Hardener module.

πŸ’‘ Best Practices

  • Context is King: Provide at least 5 lines of context around Git diffs for more accurate neural reasoning.
  • Continuous Gating: Run the FinOps auditor before every infrastructure change, not after.
  • Manual Sign-off: Use AI findings as a high-fidelity signal, but maintain human-in-the-loop for kernel-level merges.

πŸ”’ Security & Safety Notes

  • Key Management: Use CI/CD secrets for GEMINI_API_KEY in production.
  • Least Privilege: Test "Hardened" manifests in staging first to ensure no functional regressions.

Links

Limitations

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Cisco IOS Patterns

Use this skill when reviewing Cisco IOS or IOS-XE snippets, building a change-window checklist, or explaining how to collect evidence from a router or switch without making the incident worse.

When to Use

  • Reviewing IOS or IOS-XE configuration before a planned change.
  • Choosing read-only show commands for troubleshooting.
  • Checking ACL wildcard masks and interface direction.
  • Explaining global, interface, routing process, and line configuration modes.
  • Verifying that a change landed in running config and was saved intentionally.

Operating Rules

Treat IOS examples as patterns, not paste-ready production changes. Confirm the platform, interface names, current config, rollback path, and out-of-band access before making changes on a real device.

Prefer this workflow:

  1. Capture current state with read-only commands.
  2. Review the exact candidate config.
  3. Confirm management access cannot be locked out.
  4. Apply the smallest change in a maintenance window.
  5. Re-read state, compare to the baseline, then save only after validation.

Mode Reference

Router> enable
Router# show running-config
Router# configure terminal
Router(config)# interface GigabitEthernet0/1
Router(config-if)# description UPLINK-TO-CORE
Router(config-if)# no shutdown
Router(config-if)# exit
Router(config)# end
Router# show running-config interface GigabitEthernet0/1

running-config is active memory. startup-config is what survives reload. Do not save a change just because a command was accepted; validate behavior first, then use copy running-config startup-config if the change is approved.

Read-Only Collection

show version
show inventory
show processes cpu sorted
show memory statistics
show logging
show running-config | section line vty
show running-config | section interface
show running-config | section router bgp
show ip interface brief
show interfaces
show interfaces status
show vlan brief
show mac address-table
show spanning-tree
show ip route
show ip protocols
show ip access-lists
show route-map
show ip prefix-list

Collect the specific section you need instead of dumping full config into a ticket when the config may contain secrets, customer names, or private topology.

Wildcard Masks

IOS ACL and many routing statements use wildcard masks, not subnet masks.

Subnet mask       Wildcard mask
255.255.255.255   0.0.0.0
255.255.255.252   0.0.0.3
255.255.255.0     0.0.0.255
255.255.0.0       0.0.255.255

Review wildcard masks before deployment. A subnet mask accidentally used as a wildcard can match far more traffic than intended.

ip access-list extended WEB-IN
  10 permit tcp 192.0.2.0 0.0.0.255 any eq 443
  999 deny ip any any log

Every ACL has an implicit deny at the end. Add an explicit logged deny when the operational goal includes observing misses, and confirm logging volume is safe.

ACL Placement Review

Before applying an ACL to an interface, answer these questions:

  • Which traffic direction is being filtered, in or out?
  • Is management traffic sourced from a known jump host or management subnet?
  • Is there an explicit permit for required routing, DNS, NTP, monitoring, or application traffic?
  • Are hit counters available from a safe test source?
  • Is there a rollback command and an active console or out-of-band path?

Do not test reachability by removing firewall or ACL protections. Read counters, logs, and route state first.

Interface Hygiene

interface GigabitEthernet0/1
 description UPLINK-TO-CORE
 switchport mode trunk
 switchport trunk allowed vlan 10,20,30
 switchport trunk native vlan 999
 no shutdown

Use clear descriptions, explicit switchport mode, and documented native VLANs. On routed interfaces, confirm the mask, peer addressing, and routing process before assuming link state means forwarding is correct.

Change-Window Verification

Use before/after checks that match the actual change.

show running-config | section interface GigabitEthernet0/1
show interfaces GigabitEthernet0/1
show logging | include GigabitEthernet0/1|changed state|line protocol
show ip route <prefix>
show ip access-lists <name>

For routing changes, also capture neighbor state and route tables before and after the change. For ACL changes, compare hit counters from a planned test source rather than relying on a generic ping.

Anti-Patterns

  • Applying a generated config without a device-specific diff.
  • Saving configuration before post-change checks pass.
  • Using a subnet mask where IOS expects a wildcard mask.
  • Applying an ACL to the wrong interface direction.
  • Troubleshooting by disabling ACLs, route policies, or authentication.
  • Pasting full configs into public tools without sanitizing secrets and topology.

See Also

  • Agent: network-config-reviewer
  • Agent: network-troubleshooter
  • Skill: network-config-validation
  • Skill: network-interface-health

Connectivity Triage

Localize an active connectivity failure without changing network configuration. Collect the smallest useful evidence set, distinguish observations from inference, and stop when the fault domain is clear enough for the next safe action.

When to Use This Skill

Use this workflow when a macOS endpoint has an active symptom such as:

  • an API, website, or MCP service timing out or disconnecting;
  • DNS lookup failures or inconsistent name resolution;
  • packet loss, latency, or unstable interactive traffic;
  • an application that appears offline while other traffic works;
  • uncertainty about whether the problem is local, upstream, or at the service.

This is a diagnostic workflow, not a remediation workflow. Do not change interface state, DNS settings, VPN/firewall configuration, or remote service state while establishing the fault domain.

Fast Decision Flow

Work from the symptom toward the narrowest discriminating check:

symptom
  -> local link / LAN evidence
  -> DNS configuration and resolution
  -> destination reachability
  -> path quality
  -> application / service timing
  -> fault-domain assessment

Stop early when the evidence is already sufficient. Do not run every probe mechanically.

1. Define the symptom

Record the affected application or process, destination hostname or URL, when the failure started, whether it is continuous or intermittent, and whether unrelated destinations still work.

If the symptom is application-specific, preserve the exact hostname or URL the application uses. Testing an unrelated public site can establish general connectivity but cannot prove the affected service is healthy.

2. Check local-link / LAN evidence

When available, run a bounded networkQuality sample for a broad responsiveness and throughput signal. If networkQuality is unavailable, continue; it is optional.

If a known local gateway or same-LAN target is available, compare a short bounded ping sample to that local target with a short sample to the remote destination. Do not invent a gateway address. If no local target is known, leave the LAN segment unproven and continue.

Useful pattern:

ping -c 5 <known-local-target>
ping -c 5 <destination>

3. Separate DNS configuration from DNS behavior

Inspect the system resolver state, especially when VPNs, split DNS, or scoped resolvers may be involved:

scutil --dns

Then test the destination name directly with a bounded DNS query:

dig +time=2 +tries=1 <hostname>

Treat these as different evidence. scutil --dns shows resolver configuration; dig shows query behavior. A successful lookup does not prove the returned endpoint is reachable.

4. Test reachability and path quality

Use a short ping sample when ICMP is a useful signal:

ping -c 5 <destination>

If the hostname resolves, test the returned address separately only when doing so helps distinguish DNS behavior from path failure. If resolution currently fails, use an address only when it was previously observed from trustworthy incident evidence; otherwise leave address-level reachability unknown.

Use a bounded numeric traceroute when path visibility would reduce uncertainty:

traceroute -n -q 1 -m 20 <destination>

A silent or changing hop is an observation, not proof that the hop is broken. Routers may filter or rate-limit traceroute traffic while forwarding application traffic normally.

5. Inspect the affected application's live network activity

When the problem is process-specific, use a bounded nettop capture rather than watching indefinitely:

nettop -n -L 3 -p <process-name-or-pid>

Use it to confirm whether the process is opening connections, which endpoints it is using, and whether traffic is flowing. Lack of visible activity may mean the application never attempted the connection; it does not by itself identify why.

6. Time the application path

For HTTP(S), use curl phase timing against the actual affected endpoint when a safe read-only request is available. Confirm the incident-supplied endpoint is a complete http:// or https:// URL, preserve its original scheme, and pass the URL as one quoted argument rather than interpolating arbitrary incident text into the shell command:

curl -sS -o /dev/null \
  -w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  --connect-timeout 5 --max-time 15 '<affected-http-or-https-url>'

Interpret the phases comparatively. High time-to-first-byte can include server processing, so it is not proof of network latency.

Evidence Rules

Label conclusions as one of:

  • Observed β€” directly supported by command output or user-provided evidence.
  • Inferred β€” the most likely explanation after correlating observations.
  • Unknown β€” not established by the current evidence.

Never treat one probe as proof of root cause. In particular:

  • failed ping can reflect ICMP filtering rather than an outage;
  • successful ping does not prove an application is healthy;
  • non-responsive traceroute hops do not prove packet loss at those routers;
  • successful DNS resolution does not prove reachability;
  • high HTTP first-byte time can be dominated by remote application processing.

When observations conflict, prefer inconclusive over a confident guess.

Fault-Domain Assessment

Return exactly one primary category:

  • local-link/LAN β€” evidence degrades before or at the local network boundary;
  • DNS β€” resolver configuration or lookup behavior explains the failure better than path evidence;
  • upstream-path β€” local evidence is healthy and correlated path evidence degrades beyond the LAN;
  • remote-service/application β€” transport/path evidence is healthy enough while the affected service or process behavior remains abnormal;
  • inconclusive β€” current evidence cannot separate the remaining fault domains.

Use qualitative confidence: low, medium, or high. Confidence reflects evidence quality and correlation, not severity.

Incident Result Format

Symptom

Restate the active failure and affected destination/application.

Observations

List only relevant measurements, including important unavailable or blocked evidence. Mark observations, inferences, and unknowns clearly.

Fault-domain assessment

Report the category, confidence, and a short evidence-linked explanation.

Next safest check

Give one diagnostic action that most reduces uncertainty. Do not jump to configuration changes unless the user separately asks for remediation.

Safety and Boundaries

During diagnosis, do not:

  • alter interface state or restart network services;
  • edit resolver configuration or flush DNS caches;
  • modify firewall or VPN settings;
  • install packages or require Homebrew;
  • send state-changing requests to remote services;
  • run indefinite or high-volume probes when a bounded sample will answer the question.

Partial probes, blocked ICMP, VPNs, captive portals, scoped DNS, proxies, endpoint controls, and transient failures are evidence limitations rather than diagnoses.

Detailed Interpretation

Read references/details.md for command-by-command interpretation, ambiguity handling, intermittent-failure guidance, and worked examples.

Related Skills

  • incident-runbook-templates - Turn recurring connectivity incidents into repeatable response procedures
  • on-call-handoff-patterns - Preserve active connectivity evidence across responder handoffs
  • postmortem-writing - Document confirmed causes and corrective actions after the incident

Fedora Hyprland Installer Skill

This skill provides a limited workflow for a conventional mutable Fedora desktop. Fedora Atomic variants require a separate package-management plan; do not run these DNF scripts there. Use the target desktop user session, not a root shell, for user configuration and services. Backups and a working alternate session are prerequisites for disruptive changes.

Resolve the Skill Directory

Before running a bundled script, resolve SKILL_DIR to the directory that contains this SKILL.md. Do not assume the user's current working directory or guess a global installation path. If the agent cannot resolve the installed skill directory from its runtime context, stop and ask the user to provide it. Invoke bundled shell files explicitly with bash and a quoted path, for example bash "$SKILL_DIR/scripts/detect-system.sh".

When to Use

  • Use when installing or updating a Fedora-packaged Hyprland desktop stack.
  • Use when verifying a Hyprland session, portals, PipeWire, or WirePlumber on Fedora.
  • Use when diagnosing the limited repair cases documented below or removing the Hyprland-specific packages installed by this workflow.

Core Directives & Safety Rules

  1. Fedora-First: Always use Fedora tools (dnf, systemctl, loginctl). Never use apt, pacman, or yay.
  2. Never Blindly Execute: Inspect the system prior to any installation or modification.
  3. Preserve Existing Desktop: Do not uninstall GNOME, KDE, or any existing desktop environment. Hyprland should be added as a session choice in the display manager (GDM/SDDM/LightDM).
  4. Mandatory Backup: Always create a timestamped backup in ~/.local/state/fedora-hyprland-installer/backups/ before writing or altering configurations in ~/.config/hypr/, ~/.config/waybar/, etc.
  5. GPU Awareness: Check whether the system uses NVIDIA, AMD, Intel, or Hybrid graphics before configuring environment variables or graphics drivers. Never use arbitrary .run installers for NVIDIA; rely on Fedora/RPM Fusion repositories.
  6. Privileged Operations: Sudo commands must be clearly identified and communicated to the user. Do not hardcode passwords.
  7. Idempotency: Running actions multiple times must be safe and avoid duplicate config lines.
  8. Explicit Consent: Show the exact package or service changes first. Run scripts that mutate packages or services only after the user confirms; use repair.sh without --apply for diagnosis.

Workflow Guide

1. Installation Workflow

When the user asks to "Install Hyprland" or "Setup Hyprland on Fedora":

  1. Execute bash "$SKILL_DIR/scripts/detect-system.sh" and bash "$SKILL_DIR/scripts/detect-gpu.sh".
  2. Execute bash "$SKILL_DIR/scripts/preflight.sh" to inspect the Fedora marker, network reachability, package-manager presence and sudo binary. It does not establish Fedora lifecycle support, repository health or effective sudo authorization.
  3. Execute bash "$SKILL_DIR/scripts/backup.sh" to preserve any pre-existing configurations.
  4. Show the package plan with bash "$SKILL_DIR/scripts/install.sh" --dry-run; after explicit approval, execute bash "$SKILL_DIR/scripts/install.sh" to install Hyprland, Wayland portal packages (xdg-desktop-portal-hyprland, xdg-desktop-portal-gtk), PipeWire/WirePlumber, terminal, launcher, status bar, and authentication agent.
  5. Include configuration creation in the approved plan, then execute bash "$SKILL_DIR/scripts/configure.sh" to write a clean, functional initial Hyprland config (~/.config/hypr/hyprland.conf) using detected terminal/launcher defaults. Review keyboard layout, autostart paths and exact-version syntax; GPU vendor presence alone must not force NVIDIA environment variables on hybrid or non-proprietary-driver setups.
  6. Execute bash "$SKILL_DIR/scripts/verify.sh" to ensure binaries, portal services, PipeWire, and login desktop entries (/usr/share/wayland-sessions/hyprland.desktop) exist and validate.
  7. Present a summary report detailing installed packages, backup paths, and login instructions.

2. Repair Workflow

When the user asks to "Fix Hyprland", "Hyprland won't start", "No audio", "Screen sharing broken":

  1. Run bash "$SKILL_DIR/scripts/detect-system.sh" and inspect system logs (journalctl -xe, journalctl --user -u xdg-desktop-portal).
  2. Execute bash "$SKILL_DIR/scripts/repair.sh" to report a missing Hyprland config, missing portal package, and inactive PipeWire/WirePlumber services.
  3. Review the proposed changes with the user, then execute bash "$SKILL_DIR/scripts/repair.sh" --apply only after approval. The script can create a missing config, install missing portal packages, and enable or restart the checked user services; investigate other faults manually.
  4. Execute bash "$SKILL_DIR/scripts/verify.sh".

3. Update Workflow

When the user asks to "Update Hyprland":

  1. Run bash "$SKILL_DIR/scripts/backup.sh".
  2. Show the package plan with bash "$SKILL_DIR/scripts/install.sh" --dry-run --update and obtain approval.
  3. Update Hyprland and related Wayland packages via bash "$SKILL_DIR/scripts/install.sh" --update.
  4. Run the limited presence/service checks via bash "$SKILL_DIR/scripts/verify.sh".

4. Uninstall Workflow

When the user asks to "Uninstall Hyprland":

  1. Explain to the user which packages will be removed.
  2. Run bash "$SKILL_DIR/scripts/backup.sh".
  3. Show the removal list and obtain approval, then execute bash "$SKILL_DIR/scripts/uninstall.sh" --yes to remove the listed Hyprland-specific packages while preserving base desktop environments (GNOME/KDE) and user backup files.

Reference Manuals

Examples

Inspect the system and preview the package plan without changing it:

bash "$SKILL_DIR/scripts/detect-system.sh"
bash "$SKILL_DIR/scripts/detect-gpu.sh"
bash "$SKILL_DIR/scripts/install.sh" --dry-run

install.sh --dry-run prints a requested package list, not a resolved DNF transaction. Inspect the actual transaction before accepting it. DNF removal can include dependencies; the script cannot promise preservation from its two-package input list. verify.sh does not parse Hyprland configuration, exercise login/screensharing/audio, or prove overall system integrity. A zero exit with PARTIAL status is not a successful end-to-end installation.

Limitations

  • Bundled shell files are intentionally non-executable under the repository safety policy and must be invoked explicitly with bash as shown above.
  • Fedora package availability varies by Fedora release and enabled repositories. This skill does not enable RPM Fusion or install GPU drivers.
  • GPU detection identifies vendors, not whether a proposed configuration is correct for a particular driver version, hybrid-graphics routing, monitor, or laptop.
  • The repair script covers only the checks it reports; it does not diagnose broken symlinks, kernel parameters, GPU driver mismatches, or every portal/audio failure.
  • Generated configuration is a minimal starting point and is not merged into an existing hyprland.conf.
  • Commands that install or remove packages, change services, or regenerate initramfs require review, explicit consent, and suitable privileges.

Firewall Configuration

Configure host-based and cloud firewalls for network security.

When to Use This Skill

Use this skill when:

  • Setting up a new server and need to restrict network access
  • Implementing network segmentation between application tiers
  • Configuring cloud security groups for AWS, GCP, or Azure resources
  • Migrating from iptables to nftables
  • Auditing existing firewall rules for compliance
  • Responding to a security incident requiring emergency network blocks

Prerequisites

  • Root or sudo access on Linux hosts
  • AWS CLI configured for cloud security groups
  • Understanding of TCP/IP, ports, and protocols
  • Network diagram showing required traffic flows

Before writes, inventory the active firewall manager, IPv4/IPv6 policy, container/CNI rules and current management path. Preserve a verified rules backup, out-of-band console and tested rollback. Use an atomic reviewed ruleset where supported; do not flush NAT/mangle or an entire ruleset on a shared host. Examples are alternative local-lab sketches, not a script to run sequentially.

iptables

Basic Setup with Default Deny

# Preserve existing rules; do not flush production/container-managed tables.
# Build and validate a complete candidate offline, including management allows,
# before atomically applying it within authorized scope.

# Default policies - deny all inbound, allow outbound
iptables -P INPUT DROP
iptables -P FORWARD DROP
iptables -P OUTPUT ACCEPT

# Allow established connections
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Allow loopback
iptables -A INPUT -i lo -j ACCEPT

# Drop invalid packets
iptables -A INPUT -m conntrack --ctstate INVALID -j DROP

# Allow SSH (restrict to management subnet)
iptables -A INPUT -p tcp --dport 22 -s 10.0.100.0/24 -j ACCEPT

# Allow HTTP/HTTPS from anywhere
iptables -A INPUT -p tcp -m multiport --dports 80,443 -j ACCEPT

# Allow ICMP (ping) with rate limiting
iptables -A INPUT -p icmp --icmp-type echo-request -m limit --limit 1/s --limit-burst 4 -j ACCEPT

# Log dropped packets (rate limited to avoid log flooding)
iptables -A INPUT -m limit --limit 5/min -j LOG --log-prefix "IPTABLES-DROP: " --log-level 4

# Save rules (Debian/Ubuntu)
iptables-save > /etc/iptables/rules.v4
ip6tables-save > /etc/iptables/rules.v6

Anti-DDoS Rules

# SYN flood protection
# Do not add a global SYN ACCEPT: it bypasses service/source restrictions.
# Apply a measured, service-specific limiter before the matching service allow;
# a host firewall cannot guarantee mitigation of upstream bandwidth exhaustion.

# Limit new connections per source IP
iptables -A INPUT -p tcp --dport 80 -m connlimit --connlimit-above 50 -j REJECT

# Block port scanning (detect TCP flags abuse)
iptables -A INPUT -p tcp --tcp-flags ALL NONE -j DROP
iptables -A INPUT -p tcp --tcp-flags ALL ALL -j DROP
iptables -A INPUT -p tcp --tcp-flags ALL FIN,URG,PSH -j DROP
iptables -A INPUT -p tcp --tcp-flags SYN,RST SYN,RST -j DROP
iptables -A INPUT -p tcp --tcp-flags SYN,FIN SYN,FIN -j DROP

Application-Specific Rules

# Web server with database backend
# Allow app servers to reach database (port 5432)
iptables -A INPUT -p tcp --dport 5432 -s 10.0.1.0/24 -j ACCEPT

# Allow monitoring (Prometheus node exporter)
iptables -A INPUT -p tcp --dport 9100 -s 10.0.200.0/24 -j ACCEPT

# DNS resolution
iptables -A INPUT -p udp --sport 53 -j ACCEPT
iptables -A INPUT -p tcp --sport 53 -j ACCEPT

# NTP
iptables -A INPUT -p udp --sport 123 -j ACCEPT

# Block specific IP (incident response)
iptables -I INPUT 1 -s 203.0.113.50 -j DROP

UFW (Uncomplicated Firewall)

# Enable UFW with default deny
ufw default deny incoming
ufw default allow outgoing

# Allow SSH from management network
ufw allow from 10.0.100.0/24 to any port 22 proto tcp

# Enable only after confirming this allow matches the actual management path.
ufw enable

# Allow HTTP/HTTPS
ufw allow 80/tcp
ufw allow 443/tcp

# Allow specific application profile
ufw allow 'Nginx Full'

# Rate limit SSH (max 6 connections in 30 seconds)
ufw limit ssh

# Allow port range
ufw allow 8000:8080/tcp

# Deny specific IP
ufw deny from 203.0.113.50

# Check status
ufw status verbose
ufw status numbered

# Delete a rule by number
ufw delete 3

# Application profiles
ufw app list
ufw app info 'Nginx Full'

nftables

Illustrative Server Configuration

Not a complete router/container policy: the forward chain drops traffic, so the DNAT example below also needs narrowly scoped forwarding and IP forwarding configuration. Validate required ICMPv6 control/error traffic for the actual network before use. The late SYN limiter does not affect earlier accepted HTTP/HTTPS packets.

#!/usr/sbin/nft -f
flush ruleset

# Define variables
define LAN = 10.0.0.0/16
define MGMT = 10.0.100.0/24
define MONITOR = 10.0.200.0/24

table inet filter {
  # Rate limiting set
  set rate_limit {
    type ipv4_addr
    flags dynamic,timeout
    timeout 1m
  }

  chain input {
    type filter hook input priority 0; policy drop;

    # Connection tracking
    ct state established,related accept
    ct state invalid drop

    # Loopback
    iif "lo" accept

    # ICMP and ICMPv6
    ip protocol icmp icmp type { echo-request, destination-unreachable, time-exceeded } limit rate 10/second accept
    ip6 nexthdr icmpv6 icmpv6 type { echo-request, nd-neighbor-solicit, nd-neighbor-advert, nd-router-solicit, nd-router-advert, destination-unreachable, packet-too-big, time-exceeded, parameter-problem } accept

    # SSH from management only
    tcp dport 22 ip saddr $MGMT accept

    # HTTP/HTTPS from anywhere
    tcp dport { 80, 443 } accept

    # Prometheus metrics from monitoring subnet
    tcp dport 9100 ip saddr $MONITOR accept

    # Rate limit new connections
    tcp flags syn limit rate over 25/second burst 50 packets drop

    # Log dropped traffic
    log prefix "nft-drop: " level warn limit rate 5/minute
  }

  chain forward {
    type filter hook forward priority 0; policy drop;
  }

  chain output {
    type filter hook output priority 0; policy accept;

    # Optional: restrict outbound to known destinations
    # tcp dport { 80, 443, 53 } accept
    # udp dport { 53, 123 } accept
    # ct state established,related accept
    # drop
  }
}

# NAT table for port forwarding
table ip nat {
  chain prerouting {
    type nat hook prerouting priority -100;
    # Forward port 8080 to internal app server
    tcp dport 8080 dnat to 10.0.1.10:8080
  }

  chain postrouting {
    type nat hook postrouting priority 100;
    oifname "eth0" masquerade
  }
}

nftables Management Commands

# Load configuration
nft -f /etc/nftables.conf

# List all rules
nft list ruleset

# List specific table
nft list table inet filter

# Add a rule dynamically
nft add rule inet filter input tcp dport 8443 accept

# Insert rule at position
nft insert rule inet filter input position 5 ip saddr 10.0.50.0/24 tcp dport 3306 accept

# Delete a rule by handle
nft -a list chain inet filter input  # show handles
nft delete rule inet filter input handle 15

# Monitor in real time
nft monitor

AWS Security Groups

Terraform Configuration

# Web tier security group
resource "aws_security_group" "web" {
  name_prefix = "web-sg-"
  vpc_id      = aws_vpc.main.id
  description = "Security group for web servers"

  ingress {
    description = "HTTPS from internet"
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  ingress {
    description = "HTTP redirect"
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    description = "All outbound"
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }

  tags = {
    Name        = "web-sg"
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

# App tier - only accepts traffic from web tier
resource "aws_security_group" "app" {
  name_prefix = "app-sg-"
  vpc_id      = aws_vpc.main.id
  description = "Security group for application servers"

  ingress {
    description     = "HTTP from web tier"
    from_port       = 8080
    to_port         = 8080
    protocol        = "tcp"
    security_groups = [aws_security_group.web.id]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# Database tier - only accepts from app tier
resource "aws_security_group" "db" {
  name_prefix = "db-sg-"
  vpc_id      = aws_vpc.main.id
  description = "Security group for database servers"

  ingress {
    description     = "PostgreSQL from app tier"
    from_port       = 5432
    to_port         = 5432
    protocol        = "tcp"
    security_groups = [aws_security_group.app.id]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

AWS CLI Commands

# Create security group
aws ec2 create-security-group \
  --group-name web-sg \
  --description "Web server SG" \
  --vpc-id vpc-0abc123

# Add inbound rule
aws ec2 authorize-security-group-ingress \
  --group-id sg-0abc123 \
  --protocol tcp --port 443 \
  --cidr 0.0.0.0/0

# Add rule referencing another security group
aws ec2 authorize-security-group-ingress \
  --group-id sg-0db456 \
  --protocol tcp --port 5432 \
  --source-group sg-0app789

# Remove a rule
aws ec2 revoke-security-group-ingress \
  --group-id sg-0abc123 \
  --protocol tcp --port 22 \
  --cidr 0.0.0.0/0

# Describe rules
aws ec2 describe-security-group-rules \
  --filters Name=group-id,Values=sg-0abc123

Firewall Rule Audit Script

#!/bin/bash
# firewall-audit.sh - Audit current firewall rules for common issues

echo "=== Firewall Audit Report ==="
echo "Date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo "Host: $(hostname)"
echo ""

# Check if firewall is active
if command -v nft &>/dev/null; then
    echo "--- nftables rules ---"
    nft list ruleset
elif command -v iptables &>/dev/null; then
    echo "--- iptables rules ---"
    iptables -L -n -v --line-numbers
fi

echo ""
echo "--- Open ports ---"
ss -tlnp

echo ""
echo "--- Potential issues ---"

# Check for overly permissive rules
if iptables -L INPUT -n 2>/dev/null | grep -q "0.0.0.0/0.*dpt:22"; then
    echo "WARNING: SSH (port 22) open to 0.0.0.0/0 - restrict to management subnet"
fi

if iptables -L INPUT -n 2>/dev/null | grep -q "0.0.0.0/0.*dpt:3306"; then
    echo "CRITICAL: MySQL (port 3306) open to 0.0.0.0/0"
fi

if iptables -L INPUT -n 2>/dev/null | grep -q "0.0.0.0/0.*dpt:5432"; then
    echo "CRITICAL: PostgreSQL (port 5432) open to 0.0.0.0/0"
fi

# Check default policies
DEFAULT_INPUT=$(iptables -L INPUT 2>/dev/null | head -1 | grep -oP 'policy \K\w+')
if [ "$DEFAULT_INPUT" = "ACCEPT" ]; then
    echo "CRITICAL: Default INPUT policy is ACCEPT - should be DROP"
fi

Troubleshooting

ProblemCauseSolution
Locked out of SSHRule order or default deny applied before allowUse out-of-band console access; add SSH allow rule first
Rules lost after rebootRules not persistedInstall iptables-persistent or save to /etc/nftables.conf
Docker bypasses iptablesDocker modifies iptables FORWARD chainReview the Docker backend and supported policy chain; disabling Docker firewall management can break isolation/NAT and is not a routine fix
nftables and iptables conflictBoth running simultaneouslyIdentify whether iptables uses the nft backend and which manager owns rules; do not remove packages or flush blindly
AWS SG rule limit reachedMax 60 inbound rules per SGUse prefix lists or consolidate CIDR ranges
Legitimate traffic blockedRule ordering issuePlace more specific allow rules before general deny rules

Best Practices

  • Default deny policy on all chains
  • Minimal rule sets - only open what is required
  • Regular rule audits (monthly minimum)
  • Log denied traffic for security monitoring
  • Document all rules with descriptions and ticket references
  • Use connection tracking for stateful inspection
  • Rate limit inbound connections to prevent DDoS
  • Separate management traffic from application traffic
  • Test rule changes in staging before production
  • Keep persistent backups of working rule sets

Related Skills

  • linux-hardening (linux-hardening) - System security
  • aws-vpc (aws-vpc) - AWS networking
  • zero-trust (zero-trust) - Identity-based access patterns
  • vpn-setup (vpn-setup) - Secure tunnel configuration

Limitations

  • Apply guidance only within authorized scope; test destructive steps in non-production first.
  • Docs-only import: upstream scripts and templates not bundled.

Example

# Read-only first: inventory before any active step.
which <tool> && <tool> --help | head -n 20

Adapted from BagelHole/DevOps-Security-Agent-Skills (MIT); frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance. Docs-only import: helper scripts and templates not bundled.

Flox Environments

Flox creates reproducible development environments defined in a single TOML manifest. Every developer on the team gets identical packages, tools, and configuration β€” across macOS and Linux β€” without containers or VMs. Built on Nix with access to over 150,000 packages.

When to Activate

Use this skill when the user has an environment management problem β€” even if they haven't mentioned Flox. Flox is the right tool when:

  • The project needs system-level packages (compilers, databases, CLI tools) alongside language-specific dependencies
  • Reproducibility matters β€” the setup should work identically on a teammate's machine, in CI, or on a fresh laptop
  • The user needs multiple tools to coexist β€” e.g., Python 3.11 + PostgreSQL 16 + Redis + Node.js in one environment
  • Cross-platform support is needed (macOS and Linux from the same config)
  • AI agents need to install tools β€” Flox lets agents add packages to a project-scoped environment without sudo, system pollution, or sandbox restrictions

If the user just needs a single language runtime with no system dependencies, standard tooling (nvm, pyenv, rustup alone) may suffice. If they need full OS-level isolation, containers might be more appropriate. Flox sits in the sweet spot: declarative, reproducible environments without container overhead.

Prerequisite: Flox must be installed first β€” see flox.dev/docs for macOS, Linux, and Docker.

Core Concepts

Flox environments are defined in .flox/env/manifest.toml and activated with flox activate. The manifest declares packages, environment variables, setup hooks, and shell configuration β€” everything needed to reproduce the environment anywhere.

Key paths:

  • .flox/env/manifest.toml β€” Environment definition (commit this)
  • $FLOX_ENV β€” Runtime path to installed packages (like /usr β€” contains bin/, lib/, include/)
  • $FLOX_ENV_CACHE β€” Persistent local storage for caches, venvs, data (survives rebuilds)
  • $FLOX_ENV_PROJECT β€” Project root directory (where .flox/ lives)

Essential Commands

flox init                       # Create new environment
flox search <package> [--all]   # Search for packages
flox show <package>             # Show available versions
flox install <package>          # Add a package
flox list                       # List installed packages
flox activate                   # Enter environment
flox activate -- <cmd>          # Run a command in the environment without a subshell
flox edit                       # Edit manifest interactively

Manifest Structure

# .flox/env/manifest.toml

[install]
# Packages to install β€” the core of the environment
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# Static environment variables
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# Non-interactive setup scripts (run every activation)
on-activate = """
  echo "Environment ready"
"""

[profile]
# Shell functions and aliases (available in interactive shell)
common = """
  alias dev="npm run dev"
"""

[options]
# Supported platforms
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Package Installation Patterns

Basic Installation

[install]
nodejs.pkg-path = "nodejs"
python.pkg-path = "python311"
rustup.pkg-path = "rustup"

Version Pinning

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver range: latest 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Exact version

Platform-Specific Packages

[install]
# Linux-only tools
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

# macOS frameworks
Security.pkg-path = "darwin.apple_sdk.frameworks.Security"
Security.systems = ["x86_64-darwin", "aarch64-darwin"]

# GNU tools on macOS (where BSD defaults differ)
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Resolving Package Conflicts

When two packages install the same binary, use priority (lower number wins):

[install]
gcc.pkg-path = "gcc12"
gcc.priority = 3

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc wins file conflicts

Use pkg-group to group packages that should resolve versions together:

[install]
python.pkg-path = "python311"
python.pkg-group = "python-stack"

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # Resolves together with python

Language-Specific Recipes

Python with uv

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
PIP_CACHE_DIR = "$FLOX_ENV_CACHE/pip-cache"

[hook]
on-activate = """
  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Node.js

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"

[hook]
on-activate = """
  if [ -f package.json ] && [ ! -d node_modules ]; then
    npm install --silent
  fi
"""

Rust

[install]
rustup.pkg-path = "rustup"
pkg-config.pkg-path = "pkg-config"
openssl.pkg-path = "openssl"

[vars]
RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"
CARGO_HOME = "$FLOX_ENV_CACHE/cargo"

[profile]
common = """
  export PATH="$CARGO_HOME/bin:$PATH"
"""

Go

[install]
go.pkg-path = "go"
gopls.pkg-path = "gopls"
delve.pkg-path = "delve"

[vars]
GOPATH = "$FLOX_ENV_CACHE/go"
GOBIN = "$FLOX_ENV_CACHE/go/bin"

[profile]
common = """
  export PATH="$GOBIN:$PATH"
"""

C/C++

[install]
gcc.pkg-path = "gcc13"
gcc.pkg-group = "compilers"

# IMPORTANT: gcc alone doesn't expose libstdc++ headers β€” you need gcc-unwrapped
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.pkg-group = "libraries"

cmake.pkg-path = "cmake"
cmake.pkg-group = "build"

gnumake.pkg-path = "gnumake"
gnumake.pkg-group = "build"

gdb.pkg-path = "gdb"
gdb.systems = ["x86_64-linux", "aarch64-linux"]

Hooks and Profile

Hooks β€” Non-Interactive Setup

Hooks run on every activation. Keep them fast and idempotent. Rule of thumb: if it should happen automatically, put it in [hook]; if the user should be able to type it, put it in [profile].

[hook]
on-activate = """
  setup_database() {
    if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
      initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
    fi
  }
  setup_database
"""

Profile β€” Interactive Shell Configuration

Profile code is available in the user's shell session.

[profile]
common = """
  dev() { npm run dev; }
  test() { npm run test -- "$@"; }
"""

Anti-Patterns

Absolute Paths

# BAD β€” breaks on other machines
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# GOOD β€” use Flox environment variables
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

Using exit in Hooks

# BAD β€” kills the shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config"
    exit 1
  fi
"""

# GOOD β€” return from hook, don't exit
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config β€” run setup first"
    return 1
  fi
"""

Storing Secrets in Manifest

# BAD β€” manifest is committed to git
[vars]
API_KEY = "<set-at-runtime>"

# GOOD β€” reference external config or pass at runtime
# Use: API_KEY="<your-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

Slow Hooks Without Idempotency Guards

# BAD β€” reinstalls every activation
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# GOOD β€” skip if already installed
[hook]
on-activate = """
  if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Putting User Commands in Hooks

# BAD β€” hook functions aren't available in the interactive shell
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# GOOD β€” use [profile] for user-invokable functions
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

Full-Stack Example

A complete environment for a Python API with PostgreSQL:

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"
postgresql.pkg-path = "postgresql_16"
redis.pkg-path = "redis"
jq.pkg-path = "jq"
curl.pkg-path = "curl"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
DATABASE_URL = "postgres://localhost:5432/myapp"
REDIS_URL = "redis://localhost:6379"

[hook]
on-activate = """
  if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
    initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
  fi

  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

[profile]
common = """
  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }
  migrate() { alembic upgrade head; }
"""

[services]
postgres.command = "postgres -D $FLOX_ENV_CACHE/pgdata -k $FLOX_ENV_CACHE"
redis.command = "redis-server --port 6379 --daemonize no"

[options]
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Activate with services: flox activate --start-services

Environment Sharing

Flox environments are git-native. Commit the .flox/ directory and every collaborator gets the same environment:

git add .flox/
git commit -m "Add Flox environment"
# Teammates just run:
git clone <repo> && cd <repo> && flox activate

For reusable base environments across projects, push to FloxHub:

flox push                         # Push environment to FloxHub
flox activate -r owner/env-name   # Activate remote environment anywhere

Compose environments with [include]:

[include]
base.floxhub = "myorg/python-base"

[install]
# Project-specific additions on top of base
fastapi.pkg-path = "python311Packages.fastapi"

AI-Assisted and Vibe Coding

Flox is ideal for AI-assisted development and vibe coding workflows. When an AI agent needs a tool that isn't available in the current environment β€” a compiler, a database, a linter, a CLI utility β€” it can add it to the project's Flox manifest without requiring sudo access, polluting system packages, or hitting sandbox restrictions.

Why this matters for agents:

  • No sudo required β€” flox install works entirely in user space, so agents can add packages without elevated permissions
  • Project-scoped β€” packages are installed into the project environment only, not globally, so different projects can have different versions without conflict
  • Sandbox-friendly β€” agents running in sandboxed or restricted environments can still install the tools they need through Flox
  • Reversible β€” every change is captured in manifest.toml, so unwanted packages can be removed cleanly with no system residue
  • Reproducible β€” when an agent sets up an environment, that exact setup is committed to git and works for everyone

Agent workflow pattern:

# Agent discovers it needs a tool (e.g., jq for JSON processing)
flox search jq                    # Verify the package exists
flox install jq                   # Install into project environment

# Or for more control, edit the manifest directly
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# Add the package to [install] section, then apply
flox edit -f "$tmp_manifest"

# Run a command with the tool available
flox activate -- jq '.results[]' data.json

This makes Flox a natural fit for any workflow where Claude Code or other AI agents need to bootstrap project tooling on the fly.

Debugging

flox list -c                      # Show raw manifest
flox activate -- which python     # Check which binary resolves
flox activate -- env | grep FLOX  # See Flox environment variables
flox search <package> --all       # Broader package search (case-sensitive)

Common issues:

  • Package not found: Search is case-sensitive β€” try flox search --all
  • File conflicts between packages: Add priority to the package that should win
  • Hook failures: Use return not exit; guard with ${FLOX_ENV_CACHE:-}
  • Stale dependencies: Delete the $FLOX_ENV_CACHE/.deps_installed flag file

Related Skills

The following skills are available as part of the Flox Claude Code plugin for deeper integration:

  • flox β€” Environments, services and databases, builds and packaging, containers, FloxHub publishing, environment composition and sharing, and CUDA/GPU development
  • floxify β€” Onboard an existing repo to Flox by detecting its runtimes, services, and build tools
  • flox-debug β€” Diagnose catalog resolution problems when a package won't resolve to the expected version

Learn more and install at flox.dev/docs

Homelab Network Readiness

Use this skill before changing a home or small-lab network that mixes VLANs, Pi-hole or another local DNS resolver, firewall rules, and remote VPN access.

This is a planning and review skill. Do not turn it into copy-paste router, firewall, or VPN configuration unless the target platform, current topology, rollback path, console access, and maintenance window are all known.

When to Use

  • Preparing to split a flat network into trusted, IoT, guest, server, or management VLANs.
  • Moving DHCP clients to Pi-hole, AdGuard Home, Unbound, or another local DNS resolver.
  • Adding WireGuard, Tailscale, ZeroTier, OpenVPN, or router-native VPN access.
  • Reviewing whether a homelab change can lock the operator out of the gateway, switch, access point, DNS server, or VPN server.
  • Turning an informal home-network idea into a staged migration plan with validation evidence.

Safety Rules

  • Keep the first answer read-only: inventory, risks, staged plan, validation, and rollback.
  • Do not expose gateway admin panels, DNS resolvers, SSH, NAS consoles, or VPN management UIs directly to the public internet.
  • Do not provide firewall, NAT, VLAN, DHCP, or VPN commands without a confirmed platform and a rollback procedure.
  • Require out-of-band or same-room console access before changing management VLANs, trunk ports, firewall default policies, or DHCP/DNS settings.
  • Keep a working path back to the internet before pointing the whole network at a new DNS resolver or VPN route.
  • Treat IoT, guest, camera, and lab-server networks as different trust zones until the operator explicitly chooses otherwise.

Required Inventory

Collect this before giving implementation steps:

AreaQuestions
Internet edgeWhat is the modem or ONT? Is the ISP router bridged or still routing?
GatewayWhat routes, firewalls, handles DHCP, and terminates VPNs?
SwitchingWhich switch ports are uplinks, access ports, trunks, or unmanaged?
Wi-FiWhich SSIDs map to which networks, and are APs wired or mesh?
AddressingWhat subnets exist today, and which ranges conflict with VPN sites?
DNS/DHCPWhich service currently hands out leases and resolver addresses?
ManagementHow will the operator reach the gateway, switch, and AP after changes?
RecoveryWhat can be reverted locally if DNS, DHCP, VLANs, or VPN routes break?

VLAN And Trust-Zone Plan

Start with intent rather than vendor syntax.

ZoneTypical contentsDefault policy
TrustedLaptops, phones, admin workstationsCan reach shared services and management only when needed
ServersNAS, Home Assistant, lab hosts, DNS resolverAccepts narrow inbound flows from trusted clients
IoTTVs, smart plugs, cameras, speakersInternet access plus explicit exceptions only
GuestVisitor devicesInternet-only, no LAN reachability
ManagementGateway, switches, APs, controllersReachable only from trusted admin devices
VPNRemote clientsSame or narrower access than trusted clients

Before recommending VLAN IDs or subnets, confirm:

  1. The gateway supports inter-VLAN routing and firewall rules.
  2. The switch supports the required tagged and untagged port behavior.
  3. The APs can map SSIDs to VLANs.
  4. The operator knows which port they are connected through during the change.
  5. The management network remains reachable after trunk and SSID changes.

DNS Filtering Readiness

Pi-hole or another local resolver should be introduced as a dependency, not as a single point of failure.

  1. Give the resolver a reserved address before using it in DHCP options.
  2. Confirm it can resolve public DNS and local home.arpa names.
  3. Keep the gateway or a second resolver available as a temporary fallback.
  4. Test one client or one VLAN before changing every DHCP scope.
  5. Document which networks may bypass filtering and why.
  6. Check that blocking rules do not break captive portals, work VPNs, firmware updates, or medical/security devices.

Useful validation evidence:

Client gets expected DHCP lease
Client receives expected DNS resolver
Public DNS lookup succeeds
Local home.arpa lookup succeeds
Blocked test domain is blocked only where intended
Gateway and DNS admin interfaces are not reachable from guest or IoT networks

Remote Access Readiness

For WireGuard-style access, decide what the VPN is allowed to reach before generating keys or opening ports.

ModeUse whenRisk notes
Split tunnel to one subnetRemote admin for NAS or lab hostsKeep route list narrow
Split tunnel to trusted servicesAccess selected apps by IP or DNSRequires precise firewall rules
Full tunnelUntrusted networks or travelMore bandwidth and DNS responsibility
Overlay VPNSimpler remote access with identity controlsStill needs ACL review

Do not recommend port forwarding until the operator confirms:

  • The VPN endpoint is patched and actively maintained.
  • The forwarded port goes only to the VPN service, not an admin UI.
  • Dynamic DNS, public IP behavior, and ISP CGNAT status are understood.
  • Peer keys can be revoked without rebuilding the whole network.
  • Logs or connection status can verify who connected and when.

Change Sequence

Prefer small, reversible changes:

  1. Snapshot the current topology, IP plan, DHCP settings, DNS settings, and firewall rules.
  2. Reserve infrastructure addresses for gateway, DNS, controller, APs, NAS, and VPN endpoint.
  3. Create the new zone or VLAN without moving critical devices.
  4. Move one test client and validate DHCP, DNS, routing, internet, and block behavior.
  5. Add narrow firewall exceptions for required flows.
  6. Move one low-risk device group.
  7. Add VPN access with the narrowest route and firewall policy that satisfies the use case.
  8. Document final state, known exceptions, and rollback commands or UI steps.

Review Checklist

  • Each network has a reason to exist and a clear trust boundary.
  • No management interface is reachable from guest, IoT, or the public internet.
  • DNS failure does not take down the operator's ability to recover locally.
  • DHCP scope changes were tested on one client before broad rollout.
  • VPN clients receive only the routes and DNS settings they need.
  • Firewall rules are default-deny between zones, with named exceptions.
  • The operator can still reach gateway, switch, AP, DNS, and VPN admin surfaces.
  • Rollback is documented in the same vocabulary as the chosen platform UI or CLI.

Anti-Patterns

  • Segmenting networks before knowing which switch ports and SSIDs carry which VLANs.
  • Moving the admin workstation off the only reachable management network.
  • Pointing all DHCP scopes at a Pi-hole before testing fallback DNS.
  • Publishing NAS, DNS, router, or hypervisor management directly to the internet.
  • Treating VPN access as equivalent to full trusted-LAN access.
  • Adding allow-all firewall rules temporarily and forgetting to remove them.
  • Copying commands from another vendor or firmware version without checking the exact platform syntax.

See Also

  • Skill: homelab-network-setup
  • Skill: network-config-validation
  • Skill: network-interface-health

Homelab Network Setup

Use this skill to design a home or small-lab network that can grow without needing a full rebuild.

When to Use

  • Planning a new home network or redesigning an ISP-router-only setup.
  • Choosing gateway, switch, and access point roles.
  • Designing IP ranges, DHCP scopes, static reservations, and DNS.
  • Preparing for future VLANs, Pi-hole, NAS, lab servers, or VPN access.
  • Troubleshooting a new network that has double NAT, unstable Wi-Fi, or changing server addresses.

How It Works

Start by separating device roles:

Internet
  |
Modem or ONT
  |
Gateway or router      NAT, firewall, DHCP, DNS, inter-VLAN routing
  |
Managed switch         wired clients, AP uplinks, optional VLAN trunks
  |
Access points          Wi-Fi only; ideally wired backhaul
Servers and NAS        stable addresses, DNS names, monitoring
Clients and IoT        DHCP pools, isolated later if VLANs are available

Pick a gateway that matches the operator, not just the feature checklist:

OptionBest fitNotes
ISP routerBasic internet onlyLimited control and often poor VLAN support
UniFi gatewayManaged home networkGood UI, ecosystem lock-in
OPNsense or pfSenseFlexible homelabStrong VLAN, firewall, VPN, and DNS control
MikroTikAdvanced network usersPowerful, but easy to misconfigure
Linux routerTinkerersDocument rollback before using as primary gateway

IP Plan

Avoid the most common default, 192.168.1.0/24, when you expect to use VPNs. It often conflicts with hotels, offices, and ISP routers.

Example small homelab plan:

192.168.10.0/24  trusted clients
192.168.20.0/24  IoT and media devices
192.168.30.0/24  servers and NAS
192.168.40.0/24  guest Wi-Fi
192.168.99.0/24  network management

Gateway convention: .1
Infrastructure reservations: .2 through .49
Dynamic DHCP pool: .50 through .240
Spare room: .241 through .254

Use home.arpa for local names. It is reserved for home networks and avoids the leakage/conflict problems of ad hoc names like home.lan.

nas.home.arpa
pihole.home.arpa
gateway.home.arpa
switch-01.home.arpa

DHCP And DNS

  • Use DHCP reservations for anything you SSH into, bookmark, monitor, or expose as a service.
  • Hand out the gateway as DNS until a local resolver is intentionally deployed.
  • If using Pi-hole or another DNS filter, give it a reservation first, then point DHCP DNS options at that address.
  • Keep a small static/reserved range per subnet so replacements do not collide with dynamic leases.

Cabling And Wi-Fi

  • Prefer wired AP backhaul over mesh when you can run Ethernet.
  • Use a PoE switch for APs and cameras if the budget allows it.
  • Label both ends of each cable and keep a simple port map.
  • Put the gateway, switch, DNS server, and NAS on UPS power if outages are common.

Examples

Beginner Upgrade

Goal: Keep the ISP router but stabilize a small lab.

  1. Set DHCP reservations for NAS, Pi, and any SSH hosts.
  2. Move local names to home.arpa.
  3. Disable duplicate DHCP servers on secondary routers or APs.
  4. Wire the main AP instead of relying on wireless backhaul.

VLAN-Ready Plan

Goal: Prepare for future segmentation without enabling it immediately.

  1. Choose non-overlapping /24 ranges for trusted, IoT, servers, guest, and management.
  2. Reserve .1 for the gateway and .2-.49 for infrastructure on every subnet.
  3. Buy a gateway and switch that support VLANs and inter-VLAN firewall rules.
  4. Document which SSIDs and switch ports will eventually map to each network.

Anti-Patterns

  • Double NAT without a reason or documentation.
  • Using 192.168.1.0/24 when VPN access is planned.
  • Dynamic addresses for NAS, Pi-hole, Home Assistant, or other service hosts.
  • Consumer routers repurposed as APs while their DHCP servers are still enabled.
  • Flat networks with cameras, smart plugs, laptops, and servers all sharing the same trust boundary.

See Also

  • Skill: network-interface-health
  • Skill: network-config-validation

Homelab Pi-hole DNS

Pi-hole is a network-wide DNS ad blocker that runs on a Raspberry Pi or any Linux host. Every device on your network gets ad and malware domain blocking automatically β€” no browser extension needed.

When to Use

  • Installing Pi-hole on a Raspberry Pi or Linux host
  • Configuring Pi-hole as the DNS server for a home network
  • Adding or managing blocklists
  • Setting up DNS-over-HTTPS (DoH) upstream resolvers
  • Creating local DNS records (e.g. nas.home.lan, pi.home.lan)
  • Troubleshooting devices that lose internet access after Pi-hole is installed
  • Running Pi-hole alongside or instead of DHCP

How Pi-hole Works

Normal flow (without Pi-hole):
  Device β†’ requests ads.tracker.com β†’ ISP DNS β†’ real IP β†’ ads load

With Pi-hole:
  Device β†’ requests ads.tracker.com β†’ Pi-hole DNS β†’ blocked (returns 0.0.0.0) β†’ no ad

All DNS queries go through Pi-hole first.
Pi-hole checks against blocklists.
Blocked domains return a null response β€” the ad/tracker never loads.
Allowed domains get forwarded to your upstream resolver (Cloudflare, Google, etc.).

Installation

Docker (Recommended)

Docker is the easiest way to install Pi-hole and makes updates and backups straightforward.

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Web admin
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # set via .env file or secret
      PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
      DNSMASQ_LISTENING: "all"
    volumes:
      - "./etc-pihole:/etc/pihole"
      - "./etc-dnsmasq.d:/etc/dnsmasq.d"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN              # only needed if Pi-hole will serve DHCP

Replace <pinned-release-tag> with a current Pi-hole release tag before deploying. Avoid latest for long-lived DNS infrastructure so upgrades are deliberate and reviewable.

Set PIHOLE_WEBPASSWORD in a .env file next to docker-compose.yml, chmod it to 600, and keep it out of git β€” do not put the password directly in the compose file.

Access web admin at: http://<pi-ip>/admin

Bare-Metal Install (Raspberry Pi OS / Debian / Ubuntu)

Pi-hole requires a static IP before installing.

# Step 1: Assign a static IP (edit /etc/dhcpcd.conf on Pi OS)
sudo nano /etc/dhcpcd.conf
# Add at the bottom:
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# Step 2: Download and inspect the installer before running it.
# Prefer the package or installer path documented by Pi-hole for your OS/version.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # review before proceeding

# Step 3: Run
bash pi-hole-install.sh

# Follow the interactive installer:
# 1. Select network interface (eth0 for wired β€” recommended)
# 2. Select upstream DNS (Cloudflare or leave default β€” can change later)
# 3. Confirm static IP
# 4. Install the web admin interface (recommended)
# 5. Note the admin password shown at the end

Pointing Your Network at Pi-hole

# Method 1: Change DNS in your router DHCP settings (recommended)
  Router admin UI β†’ DHCP Settings β†’ DNS Server
  Primary DNS: 192.168.3.2  (Pi-hole IP)
  Secondary DNS: leave blank for strict blocking, or use a second Pi-hole.
                 A public fallback such as 1.1.1.1 improves availability during
                 rollout but can bypass blocking because clients may query it.

  All devices get Pi-hole as DNS automatically on next DHCP renewal.
  Force renewal: reconnect Wi-Fi or run 'sudo dhclient -r && sudo dhclient' on Linux

# Method 2: Per-device DNS (useful for testing before network-wide rollout)
  Windows: Control Panel β†’ Network Adapter β†’ IPv4 Properties β†’ set DNS manually
  macOS: System Settings β†’ Network β†’ Details β†’ DNS β†’ set manually
  Linux: /etc/resolv.conf or NetworkManager

# Method 3: Pi-hole as DHCP server (replaces router DHCP)
  Pi-hole admin β†’ Settings β†’ DHCP β†’ Enable
  Disable DHCP on your router first β€” two DHCP servers on the same network cause conflicts
  Advantage: hostname resolution works automatically (devices register their names)

Blocklist Management

# Pi-hole admin β†’ Adlists β†’ Add new adlist

# Recommended blocklists:
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # default β€” 200k+ domains

  https://blocklistproject.github.io/Lists/malware.txt
  # malware domains

  https://blocklistproject.github.io/Lists/tracking.txt
  # tracking/telemetry

# After adding a list:
  Tools β†’ Update Gravity  (downloads and compiles all blocklists)

# If a site is blocked that should not be (false positive):
  Pi-hole admin β†’ Whitelist β†’ Add domain
  Example: api.my-legitimate-service.com

# Check what is being blocked in real time:
  Dashboard β†’ Query Log  (live DNS query stream with block/allow status)

DNS-over-HTTPS Upstream

DNS-over-HTTPS encrypts your DNS queries so your ISP cannot see what sites you resolve.

# Install cloudflared (Cloudflare's DoH proxy).
# Prefer Cloudflare's package repository for automatic signed package verification.
# If you download a binary directly, pin a release version and verify its checksum.
CLOUDFLARED_VERSION="<pinned-version>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# Verify the checksum/signature from Cloudflare's release notes before installing.
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# Create cloudflared config
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml << EOF
proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query
EOF

# Create systemd service
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# Now point Pi-hole at the local DoH proxy:
# Pi-hole admin β†’ Settings β†’ DNS β†’ Custom upstream DNS
# Set to: 127.0.0.1#5053
# Uncheck all other upstream resolvers

Local DNS Records

Make your services reachable by name (e.g. nas.home.lan, grafana.home.lan).

Domain name note: .home.lan is widely used in homelabs and works in practice. The IETF-reserved suffix for local use is .home.arpa (RFC 8375) β€” use that to follow the standard. Avoid .local for Pi-hole DNS records as it conflicts with mDNS/Bonjour.

# Pi-hole admin β†’ Local DNS β†’ DNS Records

  Domain              IP
  nas.home.lan        192.168.30.10
  pi.home.lan         192.168.30.2
  grafana.home.lan    192.168.30.3
  proxmox.home.lan    192.168.30.4

# From any device on your network:
  ping nas.home.lan        β†’ 192.168.30.10
  http://grafana.home.lan  β†’ your Grafana dashboard

# For subdomains, add a CNAME:
  Pi-hole admin β†’ Local DNS β†’ CNAME Records
  Domain: portainer.home.lan β†’ Target: pi.home.lan

Troubleshooting

# Pi-hole blocking something it should not
pihole -q example.com          # Check if domain is blocked and which list
pihole -w example.com          # Whitelist immediately

# DNS not resolving at all
pihole status                  # Check if pihole-FTL is running
dig @192.168.3.2 google.com   # Test DNS directly against Pi-hole

# Restart Pi-hole DNS
pihole restartdns

# Check query logs for a specific device
pihole -t                      # Live tail of all queries
# Or filter by client in the web admin Query Log

# Pi-hole gravity update (refresh blocklists)
pihole -g

Anti-Patterns

# BAD: Depending on one Pi-hole without a recovery path
# If Pi-hole crashes or the Pi loses power, DNS can stop working
# GOOD: Keep a documented router fallback for rollback during setup
# BETTER: Run two Pi-hole instances for redundancy; avoid public fallback DNS for strict blocking

# BAD: Installing Pi-hole without a static IP
# If the Pi gets a new DHCP IP, all devices lose DNS
# GOOD: Set static IP first, then install Pi-hole

# BAD: Enabling Pi-hole DHCP without disabling the router's DHCP first
# Two DHCP servers on the same network hand out conflicting IPs
# GOOD: Disable router DHCP, then enable Pi-hole DHCP

# BAD: Never updating gravity (blocklists)
# New ad and malware domains accumulate β€” stale lists miss them
# GOOD: Schedule weekly gravity update: pihole -g (or enable in Settings β†’ API)

Best Practices

  • Give the Pi a static IP or DHCP reservation before installing Pi-hole
  • Use Pi-hole as primary DNS; for redundancy, add a second Pi-hole instead of a public resolver if you need strict blocking
  • Enable DoH (DNS-over-HTTPS) with cloudflared for encrypted upstream queries
  • Set home.lan as your local domain and create DNS records for all your services
  • Review the Query Log occasionally β€” blocked queries show you what devices are doing

Related Skills

  • homelab-network-setup
  • homelab-vlan-segmentation
  • homelab-wireguard-vpn

Homelab VLAN Segmentation

How to split a home network into isolated VLANs so IoT devices, guests, and your main PCs cannot talk to each other. The most impactful security upgrade for a home network.

All firewall rules shown here add isolation between segments β€” they do not remove existing protections. Apply changes in a maintenance window and verify connectivity between segments after each step before moving on.

When to Use

  • Setting up VLANs on a home network for the first time
  • Isolating IoT devices (smart bulbs, cameras, TVs) from trusted devices
  • Creating a guest Wi-Fi network that cannot reach home devices
  • Explaining how VLANs work to someone unfamiliar with the concept
  • Configuring trunk ports, access ports, and SSID-to-VLAN mapping
  • Troubleshooting inter-VLAN routing or firewall rule issues on pfSense/OPNsense/UniFi

How It Works

Without VLANs β€” flat network:
  All devices on 192.168.1.0/24
  Smart TV (potential malware) β†’ can reach your NAS, PCs, everything

With VLANs:
  VLAN 10 β€” Trusted    192.168.10.0/24  (PCs, phones, laptops)
  VLAN 20 β€” IoT        192.168.20.0/24  (smart TV, bulbs, cameras)
  VLAN 30 β€” Servers    192.168.30.0/24  (NAS, Pi, VMs)
  VLAN 40 β€” Guest      192.168.40.0/24  (visitor Wi-Fi)
  VLAN 99 β€” Management 192.168.99.0/24  (switch/AP web UIs)

  Smart TV β†’ blocked from reaching 192.168.10.0/24 and 192.168.30.0/24
  Guests β†’ internet only, cannot see any home devices

VLAN Design Template

VLAN  Name        Subnet              Gateway         Purpose
10    trusted     192.168.10.0/24     192.168.10.1    PCs, phones, laptops
20    iot         192.168.20.0/24     192.168.20.1    Smart home devices
30    servers     192.168.30.0/24     192.168.30.1    NAS, Pi, self-hosted
40    guest       192.168.40.0/24     192.168.40.1    Visitor Wi-Fi
99    management  192.168.99.0/24     192.168.99.1    Network gear web UIs

Examples

Typical homelab with UniFi AP and managed switch:

Scenario: 3-bedroom house, UniFi Dream Machine + UniFi 8-port switch + 2 APs

VLAN 10 β€” Trusted    192.168.10.0/24   MacBook, iPhones, iPad
VLAN 20 β€” IoT        192.168.20.0/24   Nest thermostat, Philips Hue, Ring doorbell, smart TVs
VLAN 30 β€” Servers    192.168.30.0/24   Synology NAS (192.168.30.10), Pi-hole (192.168.30.2)
VLAN 40 β€” Guest      192.168.40.0/24   Visitor Wi-Fi β€” internet only

SSID β†’ VLAN mapping:
  "Home"      β†’ VLAN 10 (WPA2, strong password, trusted devices only)
  "IoT"       β†’ VLAN 20 (WPA2, separate password, printed on router for setup)
  "Guest"     β†’ VLAN 40 (WPA2, simple password you can share freely)

Switch port behavior:
  Port 1  β†’ trunk to router (tagged VLANs 10,20,30,40,99)
  Port 2  β†’ trunk to APs (tagged VLANs 10,20,40; AP handles per-SSID tagging)
  Port 3  β†’ access VLAN 30 (NAS β€” untagged, no VLAN awareness needed)
  Port 4  β†’ access VLAN 30 (Pi-hole β€” untagged)
  Port 5–8 β†’ access VLAN 10 (wired workstations)

Firewall rules applied (all rules add isolation, none remove existing protections):
  IoT β†’ Trusted: BLOCK
  IoT β†’ Servers: BLOCK except 192.168.30.2:53 (Pi-hole DNS allowed)
  IoT β†’ Internet: ALLOW
  Guest β†’ Local networks: BLOCK
  Guest β†’ Internet: ALLOW
  Trusted β†’ everywhere: ALLOW

UniFi Configuration

Create Networks in UniFi Controller

Settings β†’ Networks β†’ Create New Network

For each VLAN:
  Name: IoT
  Purpose: Corporate  (gives DHCP + routing)
  VLAN ID: 20
  Network: 192.168.20.0/24
  Gateway IP: 192.168.20.1
  DHCP: Enable
  DHCP Range: 192.168.20.100 – 192.168.20.254

Map SSIDs to VLANs (UniFi)

Settings β†’ WiFi β†’ Create New WiFi

  Name: IoT-Network
  Password: <separate password>
  Network: IoT  ← select your VLAN here
  # All devices connecting to this SSID land in VLAN 20

  Name: Guest
  Password: <guest password>
  Network: Guest
  Guest Policy: Enable  ← isolates guests from each other too

UniFi Firewall Rules (Traffic Rules)

Settings β†’ Traffic & Security β†’ Traffic Rules

# Block IoT from reaching Trusted VLAN
  Action: Block
  Category: Local Network
  Source: IoT (192.168.20.0/24)
  Destination: Trusted (192.168.10.0/24)

# Allow IoT to reach internet only
  Action: Allow
  Source: IoT
  Destination: Internet

# Block Guest from all local networks
  Action: Block
  Source: Guest
  Destination: Local Networks

pfSense / OPNsense Configuration

Create VLANs

Interfaces β†’ Assignments β†’ VLANs β†’ Add

  Parent Interface: em1  (your LAN NIC)
  VLAN Tag: 20
  Description: IoT

# Repeat for each VLAN, then assign each VLAN to an interface:
Interfaces β†’ Assignments β†’ Add
  Select the VLAN you created β†’ click Add
  Enable the interface, set IP to gateway address (192.168.20.1/24)

DHCP for Each VLAN

Services β†’ DHCP Server β†’ Select your VLAN interface

  Enable DHCP
  Range: 192.168.20.100 to 192.168.20.254
  DNS Servers: 192.168.30.2  ← Pi-hole IP if you have one

Firewall Rules (pfSense/OPNsense)

# Rules are processed top-to-bottom, first match wins.

# On the IoT interface (VLAN 20):
  Rule 1: Allow IoT β†’ Pi-hole DNS  ← MUST come before the RFC1918 block rule
    Protocol: UDP/TCP
    Source: IoT net
    Destination: 192.168.30.2 port 53
    Action: Allow

  Rule 2: Block IoT β†’ RFC1918 (all private IP ranges)
    Protocol: any
    Source: IoT net
    Destination: RFC1918  (192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12)
    Action: Block

  Rule 3: Allow IoT β†’ internet
    Protocol: any
    Source: IoT net
    Destination: any
    Action: Allow

# On the Trusted interface (VLAN 10):
  Allow all (trusted devices can reach everything)
    Source: Trusted net
    Destination: any
    Action: Allow

# Additional exceptions for IoT devices that need specific local services:
  Insert before Rule 2 (the RFC1918 block):
    Protocol: TCP
    Source: IoT net
    Destination: 192.168.30.x port 8123  ← Home Assistant
    Action: Allow

MikroTik Configuration

# Step 1: Create a bridge with VLAN filtering enabled
/interface bridge
add name=bridge vlan-filtering=yes

# Step 2: Add physical ports to the bridge
# Trunk port to router/uplink (tagged for all VLANs)
/interface bridge port
add bridge=bridge interface=ether1 frame-types=admit-only-vlan-tagged

# Access port for trusted devices (untagged VLAN 10)
/interface bridge port
add bridge=bridge interface=ether2 pvid=10 frame-types=admit-only-untagged-and-priority-tagged

# Access port for IoT devices (untagged VLAN 20)
/interface bridge port
add bridge=bridge interface=ether3 pvid=20 frame-types=admit-only-untagged-and-priority-tagged

# Step 3: Define which VLANs are allowed on which ports
/interface bridge vlan
add bridge=bridge tagged=ether1 untagged=ether2 vlan-ids=10
add bridge=bridge tagged=ether1 untagged=ether3 vlan-ids=20

# Step 4: Create VLAN interfaces on the bridge (gateway IPs)
/interface vlan
add interface=bridge name=vlan10 vlan-id=10
add interface=bridge name=vlan20 vlan-id=20

# Step 5: Assign gateway IPs
/ip address
add interface=vlan10 address=192.168.10.1/24
add interface=vlan20 address=192.168.20.1/24

# Step 6: DHCP pools and servers
/ip pool
add name=pool-trusted ranges=192.168.10.100-192.168.10.254
add name=pool-iot ranges=192.168.20.100-192.168.20.254

/ip dhcp-server
add interface=vlan10 address-pool=pool-trusted name=dhcp-trusted
add interface=vlan20 address-pool=pool-iot name=dhcp-iot

/ip dhcp-server network
add address=192.168.10.0/24 gateway=192.168.10.1
add address=192.168.20.0/24 gateway=192.168.20.1

# Step 7: Firewall β€” block IoT from reaching trusted VLAN
/ip firewall filter
add chain=forward src-address=192.168.20.0/24 dst-address=192.168.10.0/24 \
    action=drop comment="Block IoT to Trusted"

Switch Trunk vs Access Ports

# Trunk port: carries multiple VLANs (tagged) β€” connects switch-to-switch, switch-to-router, switch-to-AP
# Access port: carries one VLAN (untagged) β€” connects to end devices (PC, camera, NAS)

# A managed switch port connected to your router should be a trunk:
  Allowed VLANs: 10, 20, 30, 40, 99

# A port connecting to a PC should be an access port:
  VLAN: 10 (trusted)
  No tagging β€” the PC does not know or care about VLANs

# A port connecting to an AP must be a trunk:
  The AP tags traffic from each SSID with the right VLAN ID
  Allowed VLANs: 10, 20, 40  (whichever SSIDs the AP serves)

Anti-Patterns

# BAD: Creating VLANs without adding firewall rules
# VLANs without firewall rules do not provide security β€” inter-VLAN routing is open by default
# GOOD: Add explicit block rules immediately after creating VLANs

# BAD: Putting the Pi-hole in the IoT VLAN
# IoT devices can reach it but trusted devices cannot (without extra rules)
# GOOD: Pi-hole in the Servers VLAN with a rule allowing all VLANs to reach port 53

# BAD: Native VLAN equals management VLAN
# Untagged traffic landing in your management VLAN enables VLAN hopping attacks
# GOOD: Use a dedicated unused VLAN as native (e.g. VLAN 999), keep management traffic tagged

# BAD: Same Wi-Fi password for IoT SSID and trusted SSID
# Anyone who learns the password can connect IoT devices to the wrong segment

Best Practices

  • Start with 4 VLANs: Trusted, IoT, Servers, Guest β€” add more as needed
  • Put Pi-hole in the Servers VLAN (192.168.30.x)
  • Add a firewall rule allowing DNS (port 53) from all VLANs to the Pi-hole IP β€” before any RFC1918 block rule
  • Test isolation after every rule change: from the IoT VLAN, try to ping a trusted device β€” it should fail
  • Use a management VLAN for switch and AP web UIs and restrict access to the Trusted VLAN only
  • Document your VLAN design in a table (VLAN ID, name, subnet, purpose)

Related Skills

  • homelab-network-setup
  • homelab-pihole-dns
  • homelab-wireguard-vpn

Homelab WireGuard VPN

WireGuard is a fast, modern VPN protocol. It is the right choice for remote access to a home network β€” simpler to configure than OpenVPN and faster than most alternatives.

All configuration examples show common setups. Review each command β€” especially the iptables forwarding rules and key file permissions β€” before applying them to your system, and make changes in a maintenance window.

When to Use

  • Setting up WireGuard server on a Raspberry Pi, Linux host, pfSense, or router
  • Generating WireGuard keypairs and writing peer config files
  • Configuring remote access from a phone or laptop to a home network
  • Explaining split tunneling (route only home traffic) vs full tunnel (route all traffic)
  • Troubleshooting WireGuard connections that will not come up
  • Automating peer configuration generation for multiple clients

How WireGuard Works

Your phone (WireGuard client)
    β”‚
    β”‚  Encrypted UDP tunnel (port 51820)
    β”‚
Your home router (WireGuard server β€” needs a public IP or DDNS)
    β”‚
    Your home network (192.168.1.0/24, NAS, Pi, etc.)

Every device has a keypair (public + private key).
The server knows each client's public key.
The client knows the server's public key + endpoint (IP:port).
Traffic is encrypted end-to-end with no central server or certificate authority.

Server Setup (Linux)

# Install WireGuard
sudo apt update && sudo apt install wireguard -y

# Generate server keypair β€” create files with private permissions from the start
sudo mkdir -p /etc/wireguard
sudo sh -c 'umask 077; wg genkey > /etc/wireguard/server_private.key'
sudo sh -c 'wg pubkey < /etc/wireguard/server_private.key > /etc/wireguard/server_public.key'

# Write server config β€” substitute the actual private key value
# Do not store private keys in version control or share them
sudo tee /etc/wireguard/wg0.conf << 'EOF'
[Interface]
Address = 10.8.0.1/24              # VPN subnet β€” server gets .1
ListenPort = 51820
PrivateKey = <paste_server_private_key_here>

# Scoped forwarding rules: allow VPN traffic in/out, not a blanket FORWARD ACCEPT
PostUp   = iptables -A FORWARD -i wg0 -o eth0 -j ACCEPT
PostUp   = iptables -A FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
PostUp   = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -o eth0 -j ACCEPT
PostDown = iptables -D FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
# Phone β€” replace with the actual phone public key
PublicKey = <phone_public_key>
AllowedIPs = 10.8.0.2/32

[Peer]
# Laptop β€” replace with the actual laptop public key
PublicKey = <laptop_public_key>
AllowedIPs = 10.8.0.3/32
EOF
sudo chmod 600 /etc/wireguard/wg0.conf

# Replace eth0 with your actual outbound interface name
# Check with: ip route show default

# Enable IP forwarding (required for routing traffic through the server)
echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system

# Start WireGuard and enable on boot
sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

Client Configuration

# Generate a unique keypair for each client device
# Run on the client, or on the server and transfer the private key securely β€” never in plaintext
umask 077
wg genkey | tee phone_private.key | wg pubkey > phone_public.key

# Client config file (phone_wg0.conf):
[Interface]
PrivateKey = <phone_private_key>
Address = 10.8.0.2/32
DNS = 192.168.1.2                  # Optional: use Pi-hole for DNS over the tunnel

[Peer]
PublicKey = <server_public_key>
Endpoint = your-home-ip.ddns.net:51820  # Your public IP or DDNS hostname
AllowedIPs = 192.168.1.0/24            # Split tunnel: only home network traffic
# AllowedIPs = 0.0.0.0/0, ::/0        # Full tunnel: all traffic through VPN

PersistentKeepalive = 25              # Keep NAT hole open (required for mobile clients)

Split Tunnel vs Full Tunnel

# Split tunnel: AllowedIPs = 192.168.1.0/24
  Only traffic destined for your home network goes through the VPN.
  Internet traffic (YouTube, Spotify) goes directly β€” better performance on mobile.
  Best for: "I just want to reach my NAS and Pi from anywhere."

# Full tunnel: AllowedIPs = 0.0.0.0/0, ::/0
  ALL traffic goes through your home internet connection.
  Useful for: piggybacking home DNS/Pi-hole ad blocking.
  Downside: home upload speed becomes your bottleneck everywhere.

# Multi-subnet split tunnel (most common homelab use case):
  AllowedIPs = 192.168.10.0/24, 192.168.20.0/24, 192.168.30.0/24, 10.8.0.0/24
  Routes all your VLANs through the tunnel; internet stays direct.

Key Generation and Peer Management

import subprocess

def generate_keypair() -> tuple[str, str]:
    """Generate a WireGuard keypair. Returns (private_key, public_key)."""
    private = subprocess.check_output(["wg", "genkey"]).decode().strip()
    public = subprocess.run(
        ["wg", "pubkey"], input=private.encode(), capture_output=True
    ).stdout.decode().strip()
    return private, public

def generate_preshared_key() -> str:
    return subprocess.check_output(["wg", "genpsk"]).decode().strip()

def build_client_config(
    client_private_key: str,
    client_vpn_ip: str,       # e.g. "10.8.0.3"
    server_public_key: str,
    server_endpoint: str,     # e.g. "home.example.com:51820"
    allowed_ips: str = "192.168.1.0/24",
    dns: str = "",
) -> str:
    dns_line = f"DNS = {dns}\n" if dns else ""
    return f"""[Interface]
PrivateKey = {client_private_key}
Address = {client_vpn_ip}/32
{dns_line}
[Peer]
PublicKey = {server_public_key}
Endpoint = {server_endpoint}
AllowedIPs = {allowed_ips}
PersistentKeepalive = 25
"""

def build_server_peer_block(
    client_public_key: str,
    client_vpn_ip: str,
    comment: str = "",
) -> str:
    comment_line = f"# {comment}\n" if comment else ""
    return f"""
{comment_line}[Peer]
PublicKey = {client_public_key}
AllowedIPs = {client_vpn_ip}/32
"""

Keep private keys out of source control. If you use this script, write key material to files with mode 600 and never log or print it.

pfSense / OPNsense WireGuard

# pfSense: VPN β†’ WireGuard β†’ Add Tunnel
  Interface Keys: Generate (creates keypair automatically)
  Listen Port: 51820
  Interface Address: 10.8.0.1/24

# Add Peer (one per client):
  Public Key: <client public key>
  Allowed IPs: 10.8.0.2/32

# Assign the WireGuard interface:
  Interfaces β†’ Assignments β†’ Add (select wg0)
  Enable interface, no IP needed (it is set in the tunnel config)

# Firewall rules:
  WAN β†’ Allow UDP port 51820 inbound (so clients can reach the server)
  WireGuard interface β†’ Allow traffic to LAN networks you want reachable

DDNS (Dynamic DNS) for Home Servers

Most home internet connections have a dynamic IP. Use DDNS so your VPN endpoint stays reachable after an IP change.

# Option 1: Cloudflare DDNS β€” store credentials in a secrets file, not inline
# docker-compose entry using an env file:
  ddns-updater:
    image: qmcgaw/ddns-updater
    env_file: ./ddns.env   # store zone_id and token here, not in compose
    restart: unless-stopped

# ddns.env (chmod 600, not committed to git):
# SETTINGS_CLOUDFLARE_ZONE_ID=your_zone_id
# SETTINGS_CLOUDFLARE_TOKEN=your_api_token

# Option 2: DuckDNS (free, simple)
  Sign up at duckdns.org β†’ get a token and subdomain (myhome.duckdns.org)
  Store token in /etc/ddns.env (mode 600), then use a small root-owned script:

  # /usr/local/bin/update-duckdns
  #!/bin/sh
  set -eu
  . /etc/ddns.env
  curl --fail --silent --show-error --max-time 10 \
    --get "https://www.duckdns.org/update" \
    --data-urlencode "domains=myhome" \
    --data-urlencode "token=${DUCKDNS_TOKEN}" \
    --data-urlencode "ip="

  # Cron job:
  */5 * * * * /usr/local/bin/update-duckdns >/dev/null 2>&1

Troubleshooting

# Check WireGuard status and last handshake
sudo wg show

# If "latest handshake" is never or very old, the tunnel is not connected.
# Check:
# 1. Is UDP port 51820 open on the router/firewall?
sudo ufw status  # or check pfSense/UniFi firewall rules

# 2. Is the server public key in the client config correct?
sudo wg show wg0 public-key   # Compare to what is in the client config

# 3. Is IP forwarding enabled on the server?
cat /proc/sys/net/ipv4/ip_forward  # Should be 1

# 4. Does the client AllowedIPs cover the IP you are trying to reach?
# If AllowedIPs = 192.168.1.0/24 and you are trying to reach 192.168.3.5, it will not route.

# Check kernel logs for WireGuard errors
dmesg | grep wireguard

# Restart WireGuard
sudo wg-quick down wg0 && sudo wg-quick up wg0

Anti-Patterns

# BAD: Storing private keys in version control or sharing them
# Private keys are equivalent to passwords β€” never commit them to git

# BAD: Using AllowedIPs = 0.0.0.0/0 on mobile without considering the impact
# Full tunnel routes all mobile traffic through your home upload β€” usually slow

# BAD: Not setting PersistentKeepalive on mobile clients
# Mobile clients behind NAT drop idle tunnels without it

# BAD: Opening port 51820 in the firewall but forgetting IP forwarding on the server
# Tunnel connects but no traffic routes β€” confusing to debug

# BAD: Sharing a keypair across multiple client devices
# Each device must have its own unique keypair β€” shared keys break the security model

# BAD: Using a broad "FORWARD ACCEPT" iptables rule
# Scope forwarding rules to the wg0 interface and direction only

Best Practices

  • Generate a unique keypair per client device β€” never reuse keys
  • Use split tunneling (AllowedIPs = <home subnets>) for mobile
  • Set PersistentKeepalive = 25 on all mobile clients
  • Use DDNS if your ISP assigns a dynamic IP; store credentials in env files, not inline
  • Use scoped iptables forwarding rules (inbound on wg0 only) rather than a blanket FORWARD ACCEPT
  • Add Pi-hole's IP as DNS = in client configs to get ad blocking over the VPN
  • Rotate the server keypair periodically and update all client configs

Related Skills

  • homelab-network-setup
  • homelab-vlan-segmentation
  • homelab-pihole-dns

Hybrid Cloud Networking

Configure secure, high-performance connectivity between on-premises and cloud environments using VPN, Direct Connect, ExpressRoute, Interconnect, and FastConnect.

Purpose

Establish secure, reliable network connectivity between on-premises data centers and cloud providers (AWS, Azure, GCP, OCI).

When to Use

  • Connect on-premises to cloud
  • Extend datacenter to cloud
  • Implement hybrid active-active setups
  • Meet compliance requirements
  • Migrate to cloud gradually

Connection Options

AWS Connectivity

1. Site-to-Site VPN
  • IPSec VPN over internet
  • Up to 1.25 Gbps per tunnel
  • Cost-effective for moderate bandwidth
  • Higher latency, internet-dependent
resource "aws_vpn_gateway" "main" {
  vpc_id = aws_vpc.main.id
  tags = {
    Name = "main-vpn-gateway"
  }
}

resource "aws_customer_gateway" "main" {
  bgp_asn    = 65000
  ip_address = "203.0.113.1"
  type       = "ipsec.1"
}

resource "aws_vpn_connection" "main" {
  vpn_gateway_id      = aws_vpn_gateway.main.id
  customer_gateway_id = aws_customer_gateway.main.id
  type                = "ipsec.1"
  static_routes_only  = false
}
2. AWS Direct Connect
  • Dedicated network connection
  • 1 Gbps to 100 Gbps
  • Lower latency, consistent bandwidth
  • More expensive, setup time required

Reference: See references/direct-connect.md

Azure Connectivity

1. Site-to-Site VPN
resource "azurerm_virtual_network_gateway" "vpn" {
  name                = "vpn-gateway"
  location            = azurerm_resource_group.main.location
  resource_group_name = azurerm_resource_group.main.name

  type     = "Vpn"
  vpn_type = "RouteBased"
  sku      = "VpnGw1"

  ip_configuration {
    name                          = "vnetGatewayConfig"
    public_ip_address_id          = azurerm_public_ip.vpn.id
    private_ip_address_allocation = "Dynamic"
    subnet_id                     = azurerm_subnet.gateway.id
  }
}
2. Azure ExpressRoute
  • Private connection via connectivity provider
  • Up to 100 Gbps
  • Low latency, high reliability
  • Premium for global connectivity

GCP Connectivity

1. Cloud VPN
  • IPSec VPN (Classic or HA VPN)
  • HA VPN: 99.99% SLA
  • Up to 3 Gbps per tunnel
2. Cloud Interconnect
  • Dedicated (10 Gbps, 100 Gbps)
  • Partner (50 Mbps to 50 Gbps)
  • Lower latency than VPN

OCI Connectivity

1. IPSec VPN Connect
  • IPSec VPN with redundant tunnels
  • Dynamic routing through DRG
  • Good fit for branch offices and migration phases
2. OCI FastConnect
  • Private dedicated connectivity through Oracle or partner edge
  • Suitable for predictable throughput and lower-latency hybrid traffic
  • Commonly paired with DRG for hub-and-spoke designs

Hybrid Network Patterns

Pattern 1: Hub-and-Spoke

On-Premises Datacenter
         ↓
    VPN/Direct Connect
         ↓
    Transit Gateway (AWS) / vWAN (Azure)
         ↓
    β”œβ”€ Production VPC/VNet
    β”œβ”€ Staging VPC/VNet
    └─ Development VPC/VNet

Pattern 2: Multi-Region Hybrid

On-Premises
    β”œβ”€ Direct Connect β†’ us-east-1
    └─ Direct Connect β†’ us-west-2
            ↓
        Cross-Region Peering

Pattern 3: Multi-Cloud Hybrid

On-Premises Datacenter
    β”œβ”€ Direct Connect β†’ AWS
    β”œβ”€ ExpressRoute β†’ Azure
    β”œβ”€ Interconnect β†’ GCP
    └─ FastConnect β†’ OCI

Routing Configuration

BGP Configuration

On-Premises Router:
- AS Number: 65000
- Advertise: 10.0.0.0/8

Cloud Router:
- AS Number: 64512 (AWS), 65515 (Azure), provider-assigned for GCP/OCI
- Advertise: Cloud VPC/VNet CIDRs

Route Propagation

  • Enable route propagation on route tables
  • Use BGP for dynamic routing
  • Implement route filtering
  • Monitor route advertisements

Security Best Practices

  1. Use private connectivity (Direct Connect/ExpressRoute/Interconnect/FastConnect)
  2. Implement encryption for VPN tunnels
  3. Use VPC endpoints to avoid internet routing
  4. Configure network ACLs and security groups
  5. Enable VPC Flow Logs for monitoring
  6. Implement DDoS protection
  7. Use PrivateLink/Private Endpoints
  8. Monitor connections with CloudWatch/Azure Monitor/Cloud Monitoring/OCI Monitoring
  9. Implement redundancy (dual tunnels)
  10. Regular security audits

High Availability

Dual VPN Tunnels

resource "aws_vpn_connection" "primary" {
  vpn_gateway_id      = aws_vpn_gateway.main.id
  customer_gateway_id = aws_customer_gateway.primary.id
  type                = "ipsec.1"
}

resource "aws_vpn_connection" "secondary" {
  vpn_gateway_id      = aws_vpn_gateway.main.id
  customer_gateway_id = aws_customer_gateway.secondary.id
  type                = "ipsec.1"
}

Active-Active Configuration

  • Multiple connections from different locations
  • BGP for automatic failover
  • Equal-cost multi-path (ECMP) routing
  • Monitor health of all connections

Monitoring and Troubleshooting

Key Metrics

  • Tunnel status (up/down)
  • Bytes in/out
  • Packet loss
  • Latency
  • BGP session status

Troubleshooting

# AWS VPN
aws ec2 describe-vpn-connections
aws ec2 get-vpn-connection-telemetry

# Azure VPN
az network vpn-connection show
az network vpn-connection show-device-config-script

# OCI IPSec VPN
oci network ip-sec-connection list
oci network cpe list

Cost Optimization

  1. Right-size connections based on traffic
  2. Use VPN for low-bandwidth workloads
  3. Consolidate traffic through fewer connections
  4. Minimize data transfer costs
  5. Use dedicated private links for high bandwidth
  6. Implement caching to reduce traffic

Related Skills

  • multi-cloud-architecture - For architecture decisions
  • terraform-module-library - For IaC implementation

Linux Administration

Core Linux system administration skills for managing production servers, development environments, and infrastructure hosts across Debian/Ubuntu and RHEL/CentOS distributions.

When to Use

  • Provisioning and maintaining Linux servers in any environment
  • Installing, updating, or removing software packages
  • Managing filesystems, disk usage, and mount points
  • Investigating runaway processes or high resource consumption
  • Scheduling recurring tasks with cron or systemd timers
  • Analyzing system and application logs for troubleshooting

Prerequisites

  • Root or sudo access on the target system
  • SSH access configured (see ssh-configuration skill)
  • Familiarity with a terminal text editor (vim, nano)
  • Package manager available (apt on Debian/Ubuntu, dnf on RHEL 8+/Fedora)

Operational boundaries

Examples are alternatives, not a script to run top-to-bottom. Inspect the exact host/distro and proposed package changes first; avoid blanket -y upgrades/removals on production without a maintenance plan. Formatting destroys data: verify device identity, mounts and backups before mkfs/fsck, and prefer UUIDs with a backed-up fstab. Keep an independent SSH/console path while changing firewall/mount/auth settings. Verify third-party repository signing-key fingerprints against official documentation before trusting them. Logs and process arguments may contain secrets; bound and redact captured output. Use authenticated TLS for remote log upload.

Package Management

Debian / Ubuntu (apt)

# Update package index and upgrade all installed packages
apt update && apt upgrade -y

# Search for a package by keyword
apt search nginx

# Show detailed package info including dependencies
apt show nginx

# Install a specific version of a package
apt install nginx=1.24.0-1ubuntu1

# Install multiple packages in one command
apt install -y nginx certbot python3-certbot-nginx

# Remove a package but keep its config files
apt remove nginx

# Remove a package and purge all config files
apt purge nginx

# Remove unused dependency packages
apt autoremove -y

# List all installed packages
dpkg -l | grep nginx

# Pin a package to prevent automatic upgrades
cat <<'EOF' > /etc/apt/preferences.d/pin-nginx
Package: nginx
Pin: version 1.24.0-1ubuntu1
Pin-Priority: 1001
EOF

# Add an external repository (example: Docker CE)
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
  > /etc/apt/sources.list.d/docker.list
apt update

RHEL / CentOS / Fedora (dnf)

# Update all packages
dnf update -y

# Search for a package
dnf search nginx

# Show package details
dnf info nginx

# Install a package
dnf install -y nginx

# Install a specific version
dnf install nginx-1.24.0-1.el9

# Remove a package
dnf remove nginx

# List installed packages
dnf list installed | grep nginx

# Enable a module stream (example: Node.js 20)
dnf module enable nodejs:20
dnf install -y nodejs

# Add an external repository
dnf install -y epel-release

# View repository list
dnf repolist --all

# Clean cached package data
dnf clean all

System Information

# Kernel and OS release
uname -a
cat /etc/os-release

# Hostname and system metadata
hostnamectl

# CPU information
lscpu
nproc                      # Number of processing units

# Memory usage (human-readable)
free -h

# Disk usage summary
df -hT                     # Include filesystem type
du -sh /var/log/*          # Summarize directory sizes

# Network interfaces and IP addresses
ip addr show
ip route show              # Routing table

# Uptime and load average
uptime
w                          # Who is logged in and load

Filesystem Management

# List block devices and partitions
lsblk
fdisk -l

# Create a new ext4 filesystem on a partition
mkfs.ext4 /dev/sdb1

# Mount a filesystem temporarily
mount /dev/sdb1 /mnt/data

# Add a persistent mount via fstab
echo '/dev/sdb1  /mnt/data  ext4  defaults,noatime  0  2' >> /etc/fstab
mount -a                   # Mount everything in fstab

# Check and repair a filesystem (unmount first)
umount /dev/sdb1
fsck.ext4 /dev/sdb1  # inspect repair prompts; do not auto-accept on the wrong device

# Monitor disk I/O in real time
iostat -xz 2

# Find files larger than 100 MB
find / -xdev -type f -size +100M -exec ls -lh {} \;

# Check inode usage (out-of-inodes can mimic out-of-disk)
df -i

Process Management

# List all processes with full details
ps auxf

# Interactive process viewer (prefer htop if installed)
top
htop

# Find processes by name
pgrep -la nginx

# Show process tree
pstree -p

# Send graceful stop signal (SIGTERM)
kill <pid>

# Force kill an unresponsive process (SIGKILL)
kill -9 <pid>

# Kill all processes matching a name
pkill nginx

# Show open files for a process
lsof -p <pid>

# Show which process is listening on a port
ss -tlnp | grep :80
lsof -i :80

# Run a process immune to hangups (persists after logout)
nohup /opt/myapp/start.sh > /var/log/myapp.log 2>&1 &

# Start a NEW process with a CPU quota (does not constrain an existing PID)
systemd-run --scope -p CPUQuota=25% --unit=limit-myapp /opt/myapp/start.sh

Cron Job Management

# Edit the current user's crontab
crontab -e

# List current user's cron jobs
crontab -l

# Example crontab entries
# β”Œβ”€β”€β”€β”€β”€ minute (0-59)
# β”‚ β”Œβ”€β”€β”€β”€β”€ hour (0-23)
# β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€ day of month (1-31)
# β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€ month (1-12)
# β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€ day of week (0-7, 0 and 7 = Sunday)
# * * * * * command

# Run a backup every day at 2:30 AM
30 2 * * * /usr/local/bin/backup.sh >> /var/log/backup.log 2>&1

# Run a cleanup every Sunday at midnight
0 0 * * 0 /usr/local/bin/cleanup.sh

# Run a health check every 5 minutes
*/5 * * * * /usr/local/bin/healthcheck.sh

# Place system-wide cron scripts in drop-in directories
ls /etc/cron.daily/
ls /etc/cron.weekly/

# Restrict cron access to specific users
echo "deploy" >> /etc/cron.allow

Log Management

# Follow systemd journal for a specific service
journalctl -u nginx -f

# Show logs since last boot
journalctl -b

# Show logs from a specific time range
journalctl --since "2025-01-15 08:00" --until "2025-01-15 12:00"

# Show only error-level and above
journalctl -p err

# Tail traditional syslog
tail -f /var/log/syslog          # Debian/Ubuntu
tail -f /var/log/messages        # RHEL/CentOS

# Kernel ring buffer messages
dmesg -T                          # Human-readable timestamps
dmesg --level=err,warn

# Check disk usage of log directory
du -sh /var/log/*

# Configure logrotate for a custom application
cat <<'EOF' > /etc/logrotate.d/myapp
/var/log/myapp/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 myapp myapp
    sharedscripts
    postrotate
        systemctl reload myapp > /dev/null 2>&1 || true
    endscript
}
EOF

# Prefer logrotate -d for a non-mutating preview; force only when authorized
logrotate -f /etc/logrotate.d/myapp

# Centralized logging: forward journal to a remote syslog
# In /etc/systemd/journal-upload.conf:
# URL=http://logserver.example.com:19532

Networking Essentials

# Test connectivity
ping -c 4 8.8.8.8

# DNS lookup
dig example.com
nslookup example.com

# Trace route to host
traceroute example.com

# List listening ports and associated processes
ss -tlnp

# Show active connections
ss -tunap

# Firewall management (UFW on Ubuntu)
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
ufw status verbose

# Firewall management (firewalld on RHEL/CentOS)
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --reload
firewall-cmd --list-all

Troubleshooting

SymptomDiagnostic CommandCommon Fix
Disk fulldf -h and du -sh /var/log/*Clear old logs, run logrotate -f, remove temp files
Out of inodesdf -iDelete many small files, check /tmp and mail spools
High CPU usagetop, ps aux --sort=-%cpuIdentify and restart or kill the offending process
High memory / swappingfree -h, vmstat 1Tune vm.swappiness, add RAM, identify memory leak
Service won't startsystemctl status <svc>, journalctl -u <svc>Check config syntax, file permissions, port conflicts
DNS resolution failsdig @8.8.8.8 example.com, cat /etc/resolv.confFix nameserver entries, restart systemd-resolved
Package dependency errorapt --fix-broken install or dnf distro-syncResolve held or conflicting packages
SSH connection refusedss -tlnp | grep 22, systemctl status sshdEnsure sshd is running and firewall allows port 22

Related Skills

  • ssh-configuration -- Secure remote access to Linux servers
  • user-management -- Create and manage users, groups, and sudo
  • systemd-services -- Write and manage systemd unit files
  • performance-tuning -- Kernel and application performance optimization
  • backup-recovery -- Protect server data with automated backups

Limitations

  • Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
  • Docs-only import: upstream scripts and templates not bundled.

Linux Production Shell Scripts

Detailed Guide

Read the detailed guide before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.

Prerequisites

Required Environment

  • Linux/Unix system (bash shell)
  • Appropriate permissions for tasks
  • Required utilities installed (rsync, openssl, etc.)

Required Knowledge

  • Basic bash scripting
  • Linux file system structure
  • System administration concepts

Constraints and Limitations

  • Always test scripts in non-production first
  • Use absolute paths to avoid errors
  • Quote variables to handle spaces properly
  • Many scripts require root/sudo privileges
  • Use shell tracing only on nonsecret test inputs; it logs expanded credentials and arguments

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

mTLS Configuration

Comprehensive guide to implementing mutual TLS for zero-trust service mesh communication.

Do not use this skill when

  • The task is unrelated to mtls configuration
  • You need a different domain or tool outside this scope

Instructions

  • Clarify goals, constraints, and required inputs.
  • Apply relevant best practices and validate outcomes.
  • Provide actionable steps and verification.

Use this skill when

  • Implementing zero-trust networking
  • Securing service-to-service communication
  • Certificate rotation and management
  • Debugging TLS handshake issues
  • Compliance requirements (PCI-DSS, HIPAA)
  • Multi-cluster secure communication

Core Concepts

1. mTLS Flow

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”                              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Service β”‚                              β”‚ Service β”‚
β”‚    A    β”‚                              β”‚    B    β”‚
β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜                              β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜
     β”‚                                        β”‚
β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β”      TLS Handshake          β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β”
β”‚  Proxy  │◄───────────────────────────►│  Proxy  β”‚
β”‚(Sidecar)β”‚  1. ClientHello             β”‚(Sidecar)β”‚
β”‚         β”‚  2. ServerHello + Cert      β”‚         β”‚
β”‚         β”‚  3. Client Cert             β”‚         β”‚
β”‚         β”‚  4. Verify Both Certs       β”‚         β”‚
β”‚         β”‚  5. Encrypted Channel       β”‚         β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

2. Certificate Hierarchy

Root CA (Self-signed, long-lived)
    β”‚
    β”œβ”€β”€ Intermediate CA (Cluster-level)
    β”‚       β”‚
    β”‚       β”œβ”€β”€ Workload Cert (Service A)
    β”‚       └── Workload Cert (Service B)
    β”‚
    └── Intermediate CA (Multi-cluster)
            β”‚
            └── Cross-cluster certs

Configuration boundaries

These fragments are version-specific, not a complete mesh/PKI deployment. Validate installed CRDs and proxy/ambient mode first. cert-manager Certificate/Issuer resources alone do not wire Istio’s signer; use a supported reviewed integration. A Linkerd Server governs inbound policy, not outbound external TLS; put supported outbound skip annotations on workload pod templates, not a Service. Excluding metrics/ports weakens protection and needs a reviewed network/auth policy. mTLS authenticates peers but authorization still requires allowed identities. Protect CA keys outside version control, plan overlapping trust rotation/rollback and verify both accepted and rejected identities before enforcing strict mode.

Templates

Template 1: Istio mTLS (Strict Mode)

# Enable strict mTLS mesh-wide
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system
spec:
  mtls:
    mode: STRICT
---
# Namespace-level override (permissive for migration)
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: legacy-namespace
spec:
  mtls:
    mode: PERMISSIVE
---
# Workload-specific policy
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: payment-service
  namespace: production
spec:
  selector:
    matchLabels:
      app: payment-service
  mtls:
    mode: STRICT
  portLevelMtls:
    8080:
      mode: STRICT
    9090:
      mode: DISABLE  # Metrics port, no mTLS

Template 2: Istio Destination Rule for mTLS

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: default
  namespace: istio-system
spec:
  host: "*.local"
  trafficPolicy:
    tls:
      mode: ISTIO_MUTUAL
---
# TLS to external service
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: external-api
spec:
  host: api.external.com
  trafficPolicy:
    tls:
      mode: SIMPLE
      caCertificates: /etc/certs/external-ca.pem
---
# Mutual TLS to external service
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: partner-api
spec:
  host: api.partner.com
  trafficPolicy:
    tls:
      mode: MUTUAL
      clientCertificate: /etc/certs/client.pem
      privateKey: /etc/certs/client-key.pem
      caCertificates: /etc/certs/partner-ca.pem

Template 3: Cert-Manager with Istio

# Install cert-manager issuer for Istio
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: istio-ca
spec:
  ca:
    secretName: istio-ca-secret
---
# Create Istio CA secret
apiVersion: v1
kind: Secret
metadata:
  name: istio-ca-secret
  namespace: cert-manager
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-ca-cert>
  tls.key: <base64-encoded-ca-key>
---
# Certificate for workload
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-service-cert
  namespace: my-namespace
spec:
  secretName: my-service-tls
  duration: 24h
  renewBefore: 8h
  issuerRef:
    name: istio-ca
    kind: ClusterIssuer
  commonName: my-service.my-namespace.svc.cluster.local
  dnsNames:
    - my-service
    - my-service.my-namespace
    - my-service.my-namespace.svc
    - my-service.my-namespace.svc.cluster.local
  usages:
    - server auth
    - client auth

Template 4: SPIFFE/SPIRE Integration

# SPIRE Server configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: spire-server
  namespace: spire
data:
  server.conf: |
    server {
      bind_address = "0.0.0.0"
      bind_port = "8081"
      trust_domain = "example.org"
      data_dir = "/run/spire/data"
      log_level = "INFO"
      ca_ttl = "168h"
      default_x509_svid_ttl = "1h"
    }

    plugins {
      DataStore "sql" {
        plugin_data {
          database_type = "sqlite3"
          connection_string = "/run/spire/data/datastore.sqlite3"
        }
      }

      NodeAttestor "k8s_psat" {
        plugin_data {
          clusters = {
            "demo-cluster" = {
              service_account_allow_list = ["spire:spire-agent"]
            }
          }
        }
      }

      KeyManager "memory" {
        plugin_data {}
      }

      UpstreamAuthority "disk" {
        plugin_data {
          key_file_path = "/run/spire/secrets/bootstrap.key"
          cert_file_path = "/run/spire/secrets/bootstrap.crt"
        }
      }
    }
---
# SPIRE Agent DaemonSet (abbreviated)
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: spire-agent
  namespace: spire
spec:
  selector:
    matchLabels:
      app: spire-agent
  template:
    metadata:
      labels:
        app: spire-agent
    spec:
      containers:
        - name: spire-agent
          image: ghcr.io/spiffe/spire-agent:1.8.0
          volumeMounts:
            - name: spire-agent-socket
              mountPath: /run/spire/sockets
      volumes:
        - name: spire-agent-socket
          hostPath:
            path: /run/spire/sockets
            type: DirectoryOrCreate

Template 5: Linkerd mTLS (Automatic)

# Linkerd enables mTLS automatically
# Verify with:
# linkerd viz edges deployment -n my-namespace

# For external services without mTLS
apiVersion: policy.linkerd.io/v1beta1
kind: Server
metadata:
  name: external-api
  namespace: my-namespace
spec:
  podSelector:
    matchLabels:
      app: my-app
  port: external-api
  proxyProtocol: HTTP/1  # or TLS for passthrough
---
# Skip TLS for specific port
apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    config.linkerd.io/skip-outbound-ports: "3306"  # MySQL

Certificate Rotation

# Istio - Check certificate expiry
istioctl proxy-config secret deploy/my-app -o json | \
  jq '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' | \
  tr -d '"' | base64 -d | openssl x509 -text -noout # security-allowlist: local certificate inspection

# An authorized restart may obtain a new workload certificate, but is not
# a general CA/certificate rotation procedure and disrupts workloads.
kubectl rollout restart deployment/my-app

# Check Linkerd identity
linkerd identity -n my-namespace

Debugging mTLS Issues

# Istio - Check if mTLS is enabled
istioctl authn tls-check my-service.my-namespace.svc.cluster.local

# Verify peer authentication
kubectl get peerauthentication --all-namespaces

# Check destination rules
kubectl get destinationrule --all-namespaces

# Debug TLS handshake
istioctl proxy-config log deploy/my-app --level debug
kubectl logs deploy/my-app -c istio-proxy | grep -i tls

# Linkerd - Check mTLS status
linkerd viz edges deployment -n my-namespace
linkerd viz tap deploy/my-app --to deploy/my-backend

Best Practices

Do's

  • Start with PERMISSIVE - Migrate gradually to STRICT
  • Monitor certificate expiry - Set up alerts
  • Use short-lived certs - 24h or less for workloads
  • Rotate CA periodically - Plan for CA rotation
  • Log TLS errors - For debugging and audit

Don'ts

  • Don't disable mTLS - For convenience in production
  • Don't ignore cert expiry - Automate rotation
  • Don't trust arbitrary self-signed leaf certs - A managed root CA may be self-signed; validate the intended trust chain and workload identity
  • Don't skip verification - Verify the full chain

Resources

Limitations

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Netmiko SSH Automation

Use this skill when writing or reviewing Python automation that connects to network devices with Netmiko. Keep the default path read-only; config changes need a separate change window, peer review, and rollback plan.

When to Use

  • Collecting show command output across routers, switches, or firewalls.
  • Building a small audit script for interface, routing, or config evidence.
  • Adding timeouts and exception handling to network SSH scripts.
  • Parsing command output with TextFSM when a template exists.
  • Reviewing automation before it touches production devices.

Safety Defaults

  • Start with read-only send_command() collection.
  • Keep inventory small and explicit; do not sweep whole address ranges.
  • Use environment variables, a vault, or getpass; never hardcode credentials.
  • Set connection and read timeouts.
  • Limit concurrency so older devices are not overloaded.
  • Require an explicit operator flag before send_config_set().
  • Do not call save_config() until the change has been verified and approved.

Read-Only Connection Pattern

import os
from getpass import getpass
from netmiko import ConnectHandler
from netmiko.exceptions import (
    NetmikoAuthenticationException,
    NetmikoTimeoutException,
    ReadTimeout,
)

device = {
    "device_type": "cisco_ios",
    "host": "192.0.2.10",
    "username": os.environ.get("NETMIKO_USERNAME") or input("Username: "),
    "password": os.environ.get("NETMIKO_PASSWORD") or getpass("Password: "),
    "secret": os.environ.get("NETMIKO_ENABLE_SECRET"),
    "conn_timeout": 10,
    "auth_timeout": 20,
    "banner_timeout": 15,
    "read_timeout_override": 30,
}

try:
    with ConnectHandler(**device) as conn:
        if device.get("secret") and not conn.check_enable_mode():
            conn.enable()
        output = conn.send_command("show ip interface brief", read_timeout=30)
        print(output)
except NetmikoAuthenticationException:
    print("Authentication failed")
except NetmikoTimeoutException:
    print("SSH connection timed out")
except ReadTimeout:
    print("Command read timed out")

Use placeholder addresses from documentation ranges in examples. Keep real inventory in an ignored local file or a secrets-managed system.

Batch Collection

from concurrent.futures import ThreadPoolExecutor, as_completed
from typing import Any

def collect_show(device: dict[str, Any], command: str) -> dict[str, Any]:
    host = device["host"]
    try:
        with ConnectHandler(**device) as conn:
            output = conn.send_command(command, read_timeout=45)
        return {"host": host, "ok": True, "output": output}
    except (NetmikoAuthenticationException, NetmikoTimeoutException, ReadTimeout) as exc:
        return {"host": host, "ok": False, "error": type(exc).__name__}

results = []
with ThreadPoolExecutor(max_workers=8) as pool:
    futures = [pool.submit(collect_show, device, "show version") for device in devices]
    for future in as_completed(futures):
        results.append(future.result())

Keep max_workers low unless the device estate and AAA systems are known to handle higher connection volume.

Structured Parsing

Netmiko can ask TextFSM, TTP, or Genie to parse supported command output. Treat parser output as an optimization, not the only evidence path.

with ConnectHandler(**device) as conn:
    parsed = conn.send_command(
        "show ip interface brief",
        use_textfsm=True,
        raise_parsing_error=False,
        read_timeout=30,
    )

if isinstance(parsed, str):
    print("No parser template matched; store raw output for review")
else:
    for row in parsed:
        print(row)

If parsing drives a blocking decision, keep the raw command output alongside the parsed result so an operator can inspect mismatches.

Guarded Config Pattern

import os

commands = [
    "interface GigabitEthernet0/1",
    "description CHANGE-1234 UPLINK-TO-CORE",
]

apply_changes = os.environ.get("APPLY_NETWORK_CHANGES") == "1"

if not apply_changes:
    print("Dry run only. Candidate commands:")
    print("\n".join(commands))
else:
    with ConnectHandler(**device) as conn:
        conn.enable()
        before = conn.send_command("show running-config interface GigabitEthernet0/1")
        output = conn.send_config_set(commands)
        after = conn.send_command("show running-config interface GigabitEthernet0/1")
        print(before)
        print(output)
        print(after)
        print("Verify behavior before saving startup config.")

Saving the config is a separate approval step. In production, include a rollback snippet and capture before/after evidence in the change record.

Review Checklist

  • Does the script identify an explicit inventory source?
  • Are credentials absent from source, logs, and exception messages?
  • Are conn_timeout, auth_timeout, and command read_timeout set?
  • Are failures reported per device without stopping the whole batch?
  • Does the script avoid broad scans and unbounded concurrency?
  • Are config changes behind a dry-run or explicit operator flag?
  • Is save_config() separate from the initial push and tied to verification?

Anti-Patterns

  • Hardcoding passwords, enable secrets, or private keys in source.
  • Sending config commands as the default code path.
  • Running automation against a CIDR range instead of a reviewed inventory.
  • Logging full running configs to shared systems without sanitization.
  • Treating parser success as proof that the device state is correct.

See Also

  • Skill: cisco-ios-patterns
  • Skill: network-config-validation
  • Skill: network-interface-health

Network BGP Diagnostics

Use this skill when a BGP session is down, flapping, established with missing routes, or advertising unexpected prefixes. The default workflow is read-only evidence collection; policy and reset actions belong in a reviewed change window.

When to Use

  • BGP neighbors are stuck in Idle, Connect, Active, OpenSent, or OpenConfirm.
  • A session is Established but expected prefixes are missing.
  • A route-map, prefix-list, max-prefix limit, or AS path policy may be filtering routes.
  • You need before/after evidence for a BGP change.
  • You are reviewing automation that parses BGP summary output.

Read-Only Triage Flow

  1. Identify the exact neighbor, address family, VRF, and local/remote ASNs.
  2. Capture summary state and last reset reason.
  3. Prove reachability to the peer source address.
  4. Check route policy references before assuming transport failure.
  5. Compare advertised, received, and installed routes where the platform supports those commands.
show bgp summary
show bgp neighbors <peer>
show ip route <peer>
show tcp brief | include <peer>|:179
show logging | include BGP|<peer>
show running-config | section router bgp
show ip prefix-list
show route-map

Use platform-specific address-family commands when the device uses VRFs, IPv6, VPNv4, or EVPN. Do not assume global IPv4 unicast.

State Interpretation

StateFirst checks
Established with prefix countRoute exchange is up; inspect policy and table selection
Established with zero prefixesCheck inbound policy, max-prefix, advertised routes, and AFI/SAFI
ActiveTCP session is not completing; check routing, source, ACLs, and peer reachability
ConnectTCP connection is in progress; check path and remote listener
OpenSent/OpenConfirmTCP works; check ASN, authentication, timers, capabilities, and logs
IdleNeighbor may be disabled, missing config, blocked by policy, or backoff timer

Transport Checks

ping <peer> source <local-source>
traceroute <peer> source <local-source>
show ip route <peer>
show bgp neighbors <peer> | include BGP state|Last reset|Local host|Foreign host

If the peer is sourced from a loopback, confirm both directions route to the loopback addresses and that the neighbor config uses the expected update source.

Avoid disabling ACLs or firewall policy as a diagnostic shortcut. Read hit counters, logs, and path state first.

Route Policy Checks

show bgp neighbors <peer> advertised-routes
show bgp neighbors <peer> routes
show ip prefix-list <name>
show route-map <name>
show bgp <prefix>

Some platforms require additional configuration before received-routes is available. Do not add that configuration during incident triage unless the operator approves the change.

AS Path And Prefix Review

show bgp regexp _65001_
show bgp regexp ^65001$
show bgp <prefix>
show bgp neighbors <peer> advertised-routes | include Network|Path|<prefix>

Use AS-path regex carefully. _65001_ matches AS 65001 as a token. Plain 65001 can match longer ASNs or unrelated text.

Parser Pattern

import re
from typing import Any

BGP_SUMMARY_RE = re.compile(
    r"^(?P<neighbor>\d{1,3}(?:\.\d{1,3}){3})\s+"
    r"(?P<version>\d+)\s+"
    r"(?P<remote_as>\d+)\s+"
    r"(?P<msg_rcvd>\d+)\s+"
    r"(?P<msg_sent>\d+)\s+"
    r"(?P<table_version>\d+)\s+"
    r"(?P<input_queue>\d+)\s+"
    r"(?P<output_queue>\d+)\s+"
    r"(?P<uptime>\S+)\s+"
    r"(?P<state_or_prefixes>\S+)$",
    re.M,
)

def parse_bgp_summary(raw: str) -> list[dict[str, Any]]:
    rows = []
    for match in BGP_SUMMARY_RE.finditer(raw):
        state_or_prefixes = match.group("state_or_prefixes")
        if state_or_prefixes.isdigit():
            state = "Established"
            prefixes_received = int(state_or_prefixes)
        else:
            state = state_or_prefixes
            prefixes_received = None
        rows.append({
            "neighbor": match.group("neighbor"),
            "remote_as": int(match.group("remote_as")),
            "state": state,
            "prefixes_received": prefixes_received,
            "uptime": match.group("uptime"),
        })
    return rows

Prefer structured parser output when available, but store raw output with the incident record because BGP summary formats vary by platform and address family.

Change-Window Only

These actions can affect routing and should not be suggested as automatic diagnostics:

  • Clearing a BGP session.
  • Changing neighbor authentication, timers, update source, route-maps, or prefix-lists.
  • Enabling additional received-route storage.
  • Relaxing firewall, ACL, or control-plane policy.

If a reset is approved, prefer the least disruptive soft or route-refresh option supported by the platform and document exactly why it is safe.

Anti-Patterns

  • Assuming Active always means the remote side is down.
  • Ignoring VRF, address family, or update-source differences.
  • Using broad AS-path regex without token boundaries.
  • Hard-resetting a peer before reading last reset reason and logs.
  • Treating missing received-routes output as proof that no routes arrived.

See Also

  • Skill: cisco-ios-patterns
  • Skill: network-config-validation
  • Skill: network-interface-health

Network Config Validation

Use this skill to review network configuration before a change window or before an automation run touches production devices.

When to Use

  • Reviewing Cisco IOS or IOS-XE style snippets before deployment.
  • Auditing generated config from scripts or templates.
  • Looking for dangerous commands, duplicate IP addresses, or subnet overlaps.
  • Checking whether ACLs, route-maps, prefix-lists, or line policies are referenced but not defined.
  • Building lightweight pre-flight scripts for network automation.

How It Works

Treat config validation as layered evidence, not as a complete parser. Regex checks are useful for pre-flight warnings, but final approval still needs a network engineer to review intent, platform syntax, and rollback steps.

Validate in this order:

  1. Destructive commands.
  2. Credential and management-plane exposure.
  3. Duplicate addresses and overlapping subnets.
  4. Stale references to ACLs, route-maps, prefix-lists, and interfaces.
  5. Operational hygiene such as NTP, timestamps, remote logging, and banners.

Dangerous Command Detection

import re

DANGEROUS_PATTERNS: list[tuple[re.Pattern[str], str]] = [
    (re.compile(r"\breload\b", re.I), "reload causes downtime"),
    (re.compile(r"\berase\s+(startup|nvram|flash)", re.I), "erases persistent storage"),
    (re.compile(r"\bformat\b", re.I), "formats a device filesystem"),
    (re.compile(r"\bno\s+router\s+(bgp|ospf|eigrp)\b", re.I), "removes a routing process"),
    (re.compile(r"\bno\s+interface\s+\S+", re.I), "removes interface configuration"),
    (re.compile(r"\baaa\s+new-model\b", re.I), "changes authentication behavior"),
    (re.compile(r"\bcrypto\s+key\s+(zeroize|generate)\b", re.I), "changes device SSH keys"),
]

def find_dangerous_commands(lines: list[str]) -> list[dict[str, str | int]]:
    findings = []
    for line_number, line in enumerate(lines, start=1):
        stripped = line.strip()
        for pattern, reason in DANGEROUS_PATTERNS:
            if pattern.search(stripped):
                findings.append({
                    "line": line_number,
                    "command": stripped,
                    "reason": reason,
                })
    return findings

Duplicate IPs And Subnet Overlaps

import ipaddress
import re
from collections import Counter

IP_ADDRESS_RE = re.compile(
    r"^\s*ip address\s+"
    r"(?P<ip>\d{1,3}(?:\.\d{1,3}){3})\s+"
    r"(?P<mask>\d{1,3}(?:\.\d{1,3}){3})\b",
    re.I | re.M,
)

def extract_interfaces(config: str) -> list[dict[str, str]]:
    results = []
    current = None
    for line in config.splitlines():
        if line.startswith("interface "):
            current = line.split(maxsplit=1)[1]
            continue
        match = IP_ADDRESS_RE.match(line)
        if current and match:
            ip = match.group("ip")
            mask = match.group("mask")
            network = ipaddress.ip_interface(f"{ip}/{mask}").network
            results.append({"interface": current, "ip": ip, "network": str(network)})
    return results

def find_duplicate_ips(config: str) -> list[str]:
    ips = [entry["ip"] for entry in extract_interfaces(config)]
    counts = Counter(ips)
    return sorted(ip for ip, count in counts.items() if count > 1)

def find_subnet_overlaps(config: str) -> list[tuple[str, str]]:
    networks = [ipaddress.ip_network(entry["network"]) for entry in extract_interfaces(config)]
    overlaps = []
    for index, left in enumerate(networks):
        for right in networks[index + 1:]:
            if left.overlaps(right):
                overlaps.append((str(left), str(right)))
    return overlaps

Management-Plane Checks

Parse VTY blocks by section so access-class checks do not spill across unrelated lines.

import re

def iter_blocks(config: str, starts_with: str) -> list[str]:
    blocks = []
    current: list[str] = []
    for line in config.splitlines():
        if line.startswith(starts_with):
            if current:
                blocks.append("\n".join(current))
            current = [line]
            continue
        if current:
            if line and not line.startswith(" "):
                blocks.append("\n".join(current))
                current = []
            else:
                current.append(line)
    if current:
        blocks.append("\n".join(current))
    return blocks

def check_vty_blocks(config: str) -> list[str]:
    issues = []
    for block in iter_blocks(config, "line vty"):
        if re.search(r"transport\s+input\s+.*telnet", block, re.I):
            issues.append("VTY allows Telnet; require SSH only.")
        if not re.search(r"\baccess-class\s+\S+\s+in\b", block, re.I):
            issues.append("VTY block has no inbound access-class source restriction.")
        if not re.search(r"\bexec-timeout\s+\d+\s+\d+\b", block, re.I):
            issues.append("VTY block has no explicit exec-timeout.")
    return issues

Security Hygiene Checks

SECURITY_PATTERNS = [
    (re.compile(r"\bsnmp-server community\s+(public|private)\b", re.I),
     "default SNMP community configured"),
    (re.compile(r"\bsnmp-server community\s+\S+", re.I),
     "SNMPv2 community string configured; prefer SNMPv3 authPriv"),
    (re.compile(r"\bip ssh version 1\b", re.I),
     "SSH version 1 enabled"),
    (re.compile(r"\benable password\b", re.I),
     "enable password is present; use enable secret"),
    (re.compile(r"\busername\s+\S+\s+password\b", re.I),
     "local username uses password instead of secret"),
]

BEST_PRACTICE_PATTERNS = [
    (re.compile(r"\bntp server\b", re.I), "NTP server"),
    (re.compile(r"\bservice timestamps\b", re.I), "log timestamps"),
    (re.compile(r"\blogging\s+\S+", re.I), "logging destination or buffer"),
    (re.compile(r"\bsnmp-server group\s+\S+\s+v3\s+priv\b", re.I), "SNMPv3 authPriv group"),
    (re.compile(r"\bbanner\s+(login|motd)\b", re.I), "login banner"),
]

def check_security(config: str) -> list[str]:
    return [message for pattern, message in SECURITY_PATTERNS if pattern.search(config)]

def check_missing_hygiene(config: str) -> list[str]:
    return [
        f"Missing {description}"
        for pattern, description in BEST_PRACTICE_PATTERNS
        if not pattern.search(config)
    ]

Examples

Change-Window Preflight

  1. Run dangerous-command checks on the exact snippet to be pasted.
  2. Run duplicate IP and subnet overlap checks against the full candidate config.
  3. Confirm every referenced ACL, route-map, and prefix-list exists.
  4. Confirm rollback commands and out-of-band access before any management-plane change.

Automation Preflight

Use validation as a blocking gate before Netmiko, NAPALM, Ansible, or vendor API automation pushes a generated config. Fail closed on dangerous commands and credentials. Warn on best-practice gaps that are outside the change scope.

Anti-Patterns

  • Treating regex validation as a device parser.
  • Applying generated config without a dry-run diff.
  • Recommending SNMPv2 community strings as a monitoring requirement.
  • Checking VTY blocks with regex that can accidentally span unrelated sections.
  • Testing firewall behavior by disabling ACLs instead of reading counters/logs.

See Also

  • Agent: network-config-reviewer
  • Agent: network-troubleshooter
  • Skill: network-interface-health

Network Interface Health

Use this skill when a network symptom might be caused by a physical link, switch port, cable, transceiver, duplex setting, or congested interface.

When to Use

  • A host or VLAN has packet loss, latency spikes, or intermittent reachability.
  • A switch or router interface shows CRCs, runts, giants, drops, resets, or flaps.
  • You need to compare both ends of a link before replacing hardware.
  • A change window needs before/after interface counter evidence.
  • Monitoring reports rising ifInErrors, ifOutErrors, or ifOutDiscards.

How It Works

Interface counters are evidence, but the trend matters more than the absolute number. Capture a baseline, wait a measurement interval, capture again, then compare increments.

show interfaces <interface>
show interfaces <interface> status
show logging | include <interface>|changed state|line protocol

On Linux hosts:

ip -s link show <interface>
ethtool <interface>
ethtool -S <interface>

Counter Reference

CounterMeaningCommon cause
CRCReceived frame checksum failedBad cable, dirty fiber, bad optic, duplex mismatch
input errorsAggregate receive-side errorsCheck sub-counters before concluding
runtsFrames below minimum Ethernet sizeDuplex mismatch, collision domain, faulty NIC
giantsFrames larger than expected MTUMTU mismatch or jumbo-frame boundary
input dropsDevice could not accept inbound packetsBurst, oversubscription, CPU path, queue pressure
output dropsEgress queue discarded packetsCongestion, QoS policy, undersized uplink
resetsInterface hardware resetFlapping, keepalive, driver, optic, power
collisionsEthernet collision counterHalf duplex or negotiation mismatch

Diagnosis Flow

CRCs Or Input Errors

  1. Confirm counters are incrementing, not just historical.
  2. Check both ends of the link. Receive-side errors usually point to the signal arriving on that side, not necessarily the port reporting the error.
  3. Replace patch cable or clean/replace fiber and optics.
  4. Confirm speed/duplex settings match on both sides.
  5. Check logs for flap events around the same timestamp.

Drops

  1. Separate input drops from output drops.
  2. Compare interface rate against capacity.
  3. Check QoS policy, queue counters, and whether the link is an oversubscribed uplink.
  4. Treat queue tuning as secondary. First prove whether the link is congested.

Duplex And Speed

Prefer auto-negotiation on modern Ethernet links when both sides support it. If one side must be fixed, configure both sides explicitly and document why. Never mix fixed speed/duplex on one side with auto on the other.

show interfaces <interface> | include duplex|speed

Safe Parser Example

Slice each interface block from one header to the next. Do not use an arbitrary character window; large interface blocks can cause counters to be missed or assigned to the wrong port.

import re
from typing import Any

HEADER_RE = re.compile(
    r"^(?P<name>\S+) is (?P<status>(?:administratively )?down|up), "
    r"line protocol is (?P<protocol>up|down)",
    re.I | re.M,
)
ERROR_RE = re.compile(r"(?P<input>\d+) input errors, (?P<crc>\d+) CRC", re.I)
DROP_RE = re.compile(r"(?P<output>\d+) output errors", re.I)
DUPLEX_RE = re.compile(r"(?P<duplex>Full|Half|Auto)-duplex,\s+(?P<speed>[^,]+)", re.I)

def parse_show_interfaces(raw: str) -> list[dict[str, Any]]:
    headers = list(HEADER_RE.finditer(raw))
    interfaces = []
    for index, header in enumerate(headers):
        end = headers[index + 1].start() if index + 1 < len(headers) else len(raw)
        block = raw[header.start():end]
        errors = ERROR_RE.search(block)
        drops = DROP_RE.search(block)
        duplex = DUPLEX_RE.search(block)
        interfaces.append({
            "name": header.group("name"),
            "status": header.group("status"),
            "protocol": header.group("protocol"),
            "duplex": duplex.group("duplex") if duplex else "unknown",
            "speed": duplex.group("speed").strip() if duplex else "unknown",
            "input_errors": int(errors.group("input")) if errors else 0,
            "crc_errors": int(errors.group("crc")) if errors else 0,
            "output_errors": int(drops.group("output")) if drops else 0,
        })
    return interfaces

Examples

CRCs On One Switch Port

  1. Capture counters on the local port.
  2. Capture counters on the connected remote port.
  3. Replace the cable or optic before changing routing or firewall rules.
  4. Clear counters only after recording the baseline.
  5. Recheck after a fixed interval.

Internet Slow But LAN Is Fine

  1. Check WAN interface drops/errors.
  2. Check LAN uplink utilization and output drops.
  3. Check gateway CPU if the WAN link is clean but throughput is still low.
  4. Compare wired and wireless tests before blaming upstream service.

Anti-Patterns

  • Clearing counters before saving a baseline.
  • Looking at only one side of a link.
  • Assuming all historical CRCs are active problems without a time window.
  • Mixing auto-negotiation on one side with fixed speed/duplex on the other.
  • Treating output drops as a cable problem before checking congestion.

See Also

  • Agent: network-troubleshooter
  • Skill: network-config-validation
  • Skill: homelab-network-setup

OpenTofu Migration

Migrate infrastructure-as-code from HashiCorp Terraform to the open-source OpenTofu fork.

When to Use This Skill

Use this skill when:

  • Migrating from Terraform to OpenTofu for licensing reasons
  • Setting up a new IaC project and evaluating OpenTofu vs Terraform
  • Updating CI/CD pipelines to use OpenTofu
  • Configuring the OpenTofu provider registry

Prerequisites

  • Existing Terraform codebase (0.13+)
  • OpenTofu CLI installed
  • State backend access (S3, GCS, Azure Blob, etc.)

Install OpenTofu

# macOS
brew install opentofu

# Linux (Debian/Ubuntu)
curl --proto '=https' --tlsv1.2 -fsSL https://get.opentofu.org/install-opentofu.sh \
  -o install-opentofu.sh
chmod +x install-opentofu.sh
./install-opentofu.sh --install-method deb
rm install-opentofu.sh

# Linux (RPM)
./install-opentofu.sh --install-method rpm

# Docker
docker run --rm -v $(pwd):/workspace -w /workspace \
  ghcr.io/opentofu/opentofu:latest init

# Verify installation
tofu --version

Migration Checklist

1. Verify Compatibility

# OpenTofu reads Terraform state files directly β€” no migration needed
# Check exact Terraform/OpenTofu versions and their current migration compatibility
terraform version

# Run plan with OpenTofu against existing state
tofu init
tofu plan

2. Replace CLI Commands

TerraformOpenTofu
terraform inittofu init
terraform plantofu plan
terraform applytofu apply
terraform destroytofu destroy
terraform fmttofu fmt
terraform validatetofu validate
terraform statetofu state
terraform importtofu import

3. Update Provider Lock File

# Preserve and review the provider lock file; avoid changing providers during migration.
tofu init

# Verify providers resolve correctly
tofu providers

4. Update State Backend

State files are compatible β€” no migration needed. Just verify:

# backend.tf β€” works identically with OpenTofu
terraform {
  backend "s3" {
    bucket         = "mycompany-tfstate"
    key            = "prod/infrastructure.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}
# Verify state access
tofu init
tofu state list

5. Provider Registry

OpenTofu uses its own registry but mirrors most Terraform providers:

# versions.tf
terraform {
  required_version = ">= 1.6.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 2.25"
    }
    # OpenTofu-specific providers
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

OpenTofu-Specific Features

State Encryption (Not in Terraform)

# OpenTofu supports native state encryption
terraform {
  encryption {
    key_provider "pbkdf2" "my_key" {
      passphrase = var.state_passphrase
    }
    method "aes_gcm" "encrypt" {
      keys = key_provider.pbkdf2.my_key
    }
    state {
      method   = method.aes_gcm.encrypt
      enforced = true
    }
    plan {
      method   = method.aes_gcm.encrypt
      enforced = true
    }
  }
}

Early Variable/Local Evaluation

# OpenTofu allows variables in backend config and module sources
terraform {
  backend "s3" {
    bucket = var.state_bucket  # Works in OpenTofu, not Terraform
    key    = "${var.project}/terraform.tfstate"
    region = var.aws_region
  }
}

CI/CD Pipeline Updates

GitHub Actions

# .github/workflows/tofu.yml
name: OpenTofu
on:
  pull_request:
    paths: ["infra/**"]
  push:
    branches: [main]
    paths: ["infra/**"]

permissions:
  id-token: write
  contents: read
  pull-requests: write

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup OpenTofu
        uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: "1.8.0"

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/tofu-deploy
          aws-region: us-east-1

      - name: Init
        run: tofu init
        working-directory: infra/

      - name: Plan
        id: plan
        run: tofu plan -no-color -out=tfplan
        working-directory: infra/

      - name: Comment PR with plan
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const output = `#### OpenTofu Plan
            \`\`\`
            See the private revision-bound plan artifact; do not interpolate plan text into JavaScript.
            \`\`\``;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output.substring(0, 65536)
            });

  apply:
    needs: plan
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v1
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/tofu-deploy
          aws-region: us-east-1
      # Prerequisite: retrieve the protected, reviewed plan artifact for this exact
      # revision/workspace/backend using the same pinned OpenTofu/provider versions.
      - run: tofu init && tofu apply tfplan
        working-directory: infra/

GitLab CI

# .gitlab-ci.yml
stages: [validate, plan, apply]

variables:
  TOFU_VERSION: "1.8.0"

.tofu-base:
  image: ghcr.io/opentofu/opentofu:${TOFU_VERSION}
  before_script:
    - tofu init

validate:
  extends: .tofu-base
  stage: validate
  script:
    - tofu fmt -check
    - tofu validate

plan:
  extends: .tofu-base
  stage: plan
  script:
    - tofu plan -out=tfplan
  artifacts:
    paths: [tfplan]

apply:
  extends: .tofu-base
  stage: apply
  script:
    - tofu apply tfplan
  when: manual
  only: [main]
  dependencies: [plan]

Coexistence Strategy

If you need both tools during migration:

# Use aliases to avoid conflicts
alias tf="terraform"
alias tofu="tofu"

# Or use direnv per-project
# .envrc
export PATH="/opt/opentofu/bin:$PATH"

# Wrapper script for gradual migration
#!/bin/bash
if [ -f ".use-opentofu" ]; then
    exec tofu "$@"
else
    exec terraform "$@"
fi

Troubleshooting

IssueSolution
Provider not foundInspect the existing lock/source and registry availability before any separately reviewed upgrade
State lock conflictSame as Terraform β€” check DynamoDB/blob lease
Version constraint errorChoose a tested version constraint compatible with the actual configuration
Backend migrationState is compatible β€” just run tofu init
Missing provider credentialsSame env vars work (AWS_*, GOOGLE_*, ARM_*)

Related Skills

  • terraform-aws (terraform-aws) β€” AWS IaC patterns (works with both)
  • terraform-azure (terraform-azure) β€” Azure IaC patterns
  • terraform-gcp (terraform-gcp) β€” GCP IaC patterns
  • policy-as-code (policy-as-code) β€” OPA policy checks for IaC

Limitations

  • Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
  • Docs-only import: upstream scripts and templates not bundled.

Before migration, back up configuration and state using the backend’s protected procedures; prohibit concurrent Terraform/OpenTofu writers. First compare no-change plans with unchanged provider versions. CI plan/apply fragments are incomplete without secure artifact upload/download, revision/hash binding, protected approval and an apply role unavailable to untrusted PR code; do not silently re-plan during apply. Plan/state files can contain secrets and must not be posted publicly. See OpenTofu migration guide.

Terraform Module Library

Production-ready Terraform module patterns for AWS, Azure, GCP, and OCI infrastructure.

Purpose

Create reusable, well-tested Terraform modules for common cloud infrastructure patterns across multiple cloud providers.

When to Use

  • Build reusable infrastructure components
  • Standardize cloud resource provisioning
  • Implement infrastructure as code best practices
  • Create multi-cloud compatible modules
  • Establish organizational Terraform standards

Module Structure

terraform-modules/
β”œβ”€β”€ aws/
β”‚   β”œβ”€β”€ vpc/
β”‚   β”œβ”€β”€ eks/
β”‚   β”œβ”€β”€ rds/
β”‚   └── s3/
β”œβ”€β”€ azure/
β”‚   β”œβ”€β”€ vnet/
β”‚   β”œβ”€β”€ aks/
β”‚   └── storage/
β”œβ”€β”€ gcp/
β”‚   β”œβ”€β”€ vpc/
β”‚   β”œβ”€β”€ gke/
β”‚   └── cloud-sql/
└── oci/
    β”œβ”€β”€ vcn/
    β”œβ”€β”€ oke/
    └── object-storage/

Standard Module Pattern

module-name/
β”œβ”€β”€ main.tf          # Main resources
β”œβ”€β”€ variables.tf     # Input variables
β”œβ”€β”€ outputs.tf       # Output values
β”œβ”€β”€ versions.tf      # Provider versions
β”œβ”€β”€ README.md        # Documentation
β”œβ”€β”€ examples/        # Usage examples
β”‚   └── complete/
β”‚       β”œβ”€β”€ main.tf
β”‚       └── variables.tf
└── tests/           # Terratest files
    └── module_test.go

AWS VPC Module Example

main.tf:

resource "aws_vpc" "main" {
  cidr_block           = var.cidr_block
  enable_dns_hostnames = var.enable_dns_hostnames
  enable_dns_support   = var.enable_dns_support

  tags = merge(
    {
      Name = var.name
    },
    var.tags
  )
}

resource "aws_subnet" "private" {
  count             = length(var.private_subnet_cidrs)
  vpc_id            = aws_vpc.main.id
  cidr_block        = var.private_subnet_cidrs[count.index]
  availability_zone = var.availability_zones[count.index]

  tags = merge(
    {
      Name = "${var.name}-private-${count.index + 1}"
      Tier = "private"
    },
    var.tags
  )
}

resource "aws_internet_gateway" "main" {
  count  = var.create_internet_gateway ? 1 : 0
  vpc_id = aws_vpc.main.id

  tags = merge(
    {
      Name = "${var.name}-igw"
    },
    var.tags
  )
}

variables.tf:

variable "name" {
  description = "Name of the VPC"
  type        = string
}

variable "cidr_block" {
  description = "CIDR block for VPC"
  type        = string
  validation {
    condition     = can(regex("^([0-9]{1,3}\\.){3}[0-9]{1,3}/[0-9]{1,2}$", var.cidr_block))
    error_message = "CIDR block must be valid IPv4 CIDR notation."
  }
}

variable "availability_zones" {
  description = "List of availability zones"
  type        = list(string)
}

variable "private_subnet_cidrs" {
  description = "CIDR blocks for private subnets"
  type        = list(string)
  default     = []
}

variable "enable_dns_hostnames" {
  description = "Enable DNS hostnames in VPC"
  type        = bool
  default     = true
}

variable "tags" {
  description = "Additional tags"
  type        = map(string)
  default     = {}
}

outputs.tf:

output "vpc_id" {
  description = "ID of the VPC"
  value       = aws_vpc.main.id
}

output "private_subnet_ids" {
  description = "IDs of private subnets"
  value       = aws_subnet.private[*].id
}

output "vpc_cidr_block" {
  description = "CIDR block of VPC"
  value       = aws_vpc.main.cidr_block
}

Best Practices

  1. Use semantic versioning for modules
  2. Document all variables with descriptions
  3. Provide examples in examples/ directory
  4. Use validation blocks for input validation
  5. Output important attributes for module composition
  6. Pin provider versions in versions.tf
  7. Use locals for computed values
  8. Implement conditional resources with count/for_each
  9. Test modules with Terratest
  10. Tag all resources consistently

Reference: See references/aws-modules.md and references/oci-modules.md

Module Composition

module "vpc" {
  source = "../../modules/aws/vpc"

  name               = "production"
  cidr_block         = "10.0.0.0/16"
  availability_zones = ["us-west-2a", "us-west-2b", "us-west-2c"]

  private_subnet_cidrs = [
    "10.0.1.0/24",
    "10.0.2.0/24",
    "10.0.3.0/24"
  ]

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

module "rds" {
  source = "../../modules/aws/rds"

  identifier     = "production-db"
  engine         = "postgres"
  engine_version = "15.3"
  instance_class = "db.t3.large"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnet_ids

  tags = {
    Environment = "production"
  }
}

Testing

// tests/vpc_test.go
package test

import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

func TestVPCModule(t *testing.T) {
    terraformOptions := &terraform.Options{
        TerraformDir: "../examples/complete",
    }

    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)

    vpcID := terraform.Output(t, terraformOptions, "vpc_id")
    assert.NotEmpty(t, vpcID)
}

Related Skills

  • multi-cloud-architecture - For architectural decisions
  • cost-optimization - For cost-effective designs

Sponsors

Details

Marketplace
marslanalvi/SkillsStack
Source
plugins/devops/infrastructure-networking
Category
Devops
Keywords
devops, infrastructure-networking

More from marslanalvi/SkillsStack

All 45