gh-phaezer-claude-mkt-plugins-networking/commands/generate-netplan-config.md

description, argument-hint

description	argument-hint
Generate netplan YAML configuration files	Optional netplan requirements

You are initiating netplan configuration generation using a structured workflow to create production-ready netplan YAML configuration files for modern Ubuntu and Debian systems.

Workflow Steps

1. Gather Requirements

If the user provides specific requirements in their message, use those directly. Otherwise, ask the user for:

Basic Requirements:

• Target system (Ubuntu version 17.10+, Debian with netplan)
• Renderer preference (networkd for servers, NetworkManager for desktops)
• Interfaces to configure (eth0, enp0s3, wlan0, etc.)
• IP addressing method (static, DHCP, or both)
• DNS nameservers
• Search domains

For Static IP Configuration:

• IP address and CIDR (e.g., 192.168.1.100/24)
• Gateway IP address (or use routes with "to: default")
• Additional IP addresses (if needed)

For VLAN Configuration:

• VLAN IDs and parent interfaces
• IP addressing for each VLAN
• VLAN naming convention (e.g., vlan100 or eth0.100)

For Bridge Configuration:

• Bridge interfaces to create
• Physical interfaces to attach to bridges
• STP settings (true/false)
• Forward delay settings
• IP addressing for bridges
• Use case (virtualization, container networking)

For Bond Configuration:

• Bond interfaces to create
• Physical interfaces to bond
• Bond mode (active-backup, 802.3ad, balance-rr, balance-xor, etc.)
• MII monitor interval
• Primary interface (for active-backup mode)
• LACP rate (for 802.3ad)

For WiFi Configuration:

• SSID and password
• Security type (WPA2, WPA3)
• DHCP or static configuration

Advanced Options:

• MTU settings (jumbo frames for 9000 MTU)
• Static routes with metrics
• Routing policy rules
• IPv6 configuration
• Optional interfaces (don't wait at boot)
• DHCP overrides (use-dns, use-routes, etc.)

2. Launch netplan-config-generator Agent

Use the Task tool to launch the netplan-config-generator agent with a detailed prompt containing:

Generate netplan YAML configuration for the following requirements:

[Insert gathered requirements here with all details]

Please provide:
1. Complete netplan YAML file content
2. Recommended filename (e.g., /etc/netplan/01-network-config.yaml)
3. Step-by-step deployment procedure
4. Validation commands with netplan try
5. Rollback procedure
6. Comments explaining each section
7. Any version-specific considerations

3. Review Generated Configuration

When the agent returns the configuration, review it for:

• Valid YAML syntax (proper indentation with spaces, not tabs)
• Includes version: 2 at the top
• Correct renderer specification
• Proper CIDR notation for IP addresses
• No conflicting gateway definitions
• Appropriate use of modern routes vs deprecated gateway4/gateway6
• Correct interface naming for the target system

4. Validate YAML Syntax

Before deployment, ensure YAML syntax validation:

# Install YAML linter if needed
sudo apt-get install -y yamllint

# Validate YAML syntax
yamllint /etc/netplan/01-network-config.yaml

# Or use Python JSON tool
python3 -c "import yaml; yaml.safe_load(open('/etc/netplan/01-network-config.yaml'))"

# Netplan's own syntax check
sudo netplan generate

5. Present Deployment Procedure

Ensure the generated configuration includes a safe deployment procedure:

1. Backup Current Configuration

   # Backup all existing netplan files
   sudo mkdir -p /etc/netplan/backup
   sudo cp /etc/netplan/*.yaml /etc/netplan/backup/
   
   # Backup current network state
   ip addr show > ~/network-backup-$(date +%Y%m%d_%H%M%S).txt
   ip route show >> ~/network-backup-$(date +%Y%m%d_%H%M%S).txt
   

2. Create New Configuration File

   # Create new netplan configuration
   sudo nano /etc/netplan/01-network-config.yaml
   
   # Paste the generated YAML configuration
   # Save and exit (Ctrl+X, Y, Enter)
   
   # Set correct permissions
   sudo chmod 600 /etc/netplan/01-network-config.yaml
   sudo chown root:root /etc/netplan/01-network-config.yaml
   

3. Remove Conflicting Configurations (if any)

   # List existing netplan files
   ls -la /etc/netplan/
   
   # Remove old cloud-init config if replacing it
   # sudo rm /etc/netplan/50-cloud-init.yaml
   
   # Or disable cloud-init network config
   # echo "network: {config: disabled}" | sudo tee /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
   

4. Test Configuration with Auto-Revert

   # Try configuration with 120-second auto-revert
   sudo netplan try
   
   # The configuration will be applied
   # If you lose connectivity, it auto-reverts after 120 seconds
   # If everything works, press Enter to accept
   
   # For debug output
   sudo netplan --debug try
   

5. Apply Configuration Permanently

   # After successful try, apply permanently
   sudo netplan apply
   
   # Or with debug output
   sudo netplan --debug apply
   

6. Verify Configuration

   # Check interface status
   ip addr show
   
   # Check routing table
   ip route show
   
   # Check IPv6 routes
   ip -6 route show
   
   # Test connectivity
   ping -c 4 <gateway-ip>
   ping -c 4 8.8.8.8
   
   # Check DNS resolution
   resolvectl status
   nslookup google.com
   

6. Provide Validation Commands

Include comprehensive validation commands:

Netplan Status:

# Generate backend configuration
sudo netplan generate

# Check generated configuration
sudo netplan get

# Show current netplan configuration
cat /etc/netplan/*.yaml

Interface Status:

# Show all interfaces with networkctl (systemd-networkd)
networkctl status

# Show specific interface
networkctl status eth0

# Traditional ip command
ip addr show
ip link show

# Show interface statistics
ip -s link show eth0

Routing Validation:

# Show IPv4 routes
ip route show

# Show IPv6 routes
ip -6 route show

# Show all routing tables
ip route show table all

# Test specific route
ip route get 8.8.8.8

DNS Validation:

# Check DNS configuration (systemd-resolved)
resolvectl status

# Check resolv.conf
cat /etc/resolv.conf

# Test DNS resolution
nslookup google.com
dig google.com

VLAN Validation:

# Show VLAN interfaces
ip -d link show type vlan

# Show specific VLAN
ip -d link show vlan100

Bridge Validation:

# Show bridge interfaces
ip -d link show type bridge

# Show bridge details with bridge command
bridge link show

# Check bridge forwarding database
bridge fdb show

Bond Validation:

# Show bond interfaces
ip -d link show type bond

# Check bonding status (if using kernel bonding)
cat /proc/net/bonding/bond0

# Show bond details
ip -d link show bond0

WiFi Validation:

# Show WiFi status
nmcli device wifi list

# Show connection status
nmcli connection show

# Check WiFi interface
iw dev wlan0 info

7. Include Troubleshooting Commands

Provide troubleshooting commands for common issues:

Configuration Not Applying:

# Debug netplan apply
sudo netplan --debug apply

# Check netplan logs
sudo journalctl -u systemd-networkd -n 50

# For NetworkManager renderer
sudo journalctl -u NetworkManager -n 50

# Generate configuration manually
sudo netplan generate

# Check generated files
ls -la /run/netplan/
cat /run/netplan/*.network

YAML Syntax Errors:

# Validate YAML syntax
yamllint /etc/netplan/*.yaml

# Check for tabs vs spaces
cat -A /etc/netplan/01-network-config.yaml | grep $'\t'

# Python YAML validation
python3 -c "import yaml; yaml.safe_load(open('/etc/netplan/01-network-config.yaml'))"

Interface Not Coming Up:

# Check interface status
networkctl status eth0

# Check systemd-networkd status
sudo systemctl status systemd-networkd

# Restart networkd
sudo systemctl restart systemd-networkd

# Check for interface errors
ip link show eth0

# Check kernel messages
dmesg | grep eth0

No Network Connectivity:

# Check IP address assignment
ip addr show

# Check default route
ip route show default

# Check physical link
ethtool eth0

# Test ARP
ip neigh show

# Check firewall
sudo iptables -L -n -v

DNS Not Working:

# Check systemd-resolved status
sudo systemctl status systemd-resolved

# Restart resolved
sudo systemctl restart systemd-resolved

# Check DNS servers
resolvectl status

# Check resolv.conf symlink
ls -la /etc/resolv.conf

# Test DNS manually
dig @8.8.8.8 google.com

Renderer Issues:

# Check which renderer is active
ps aux | grep -E "networkd|NetworkManager"

# Switch from networkd to NetworkManager
sudo systemctl stop systemd-networkd
sudo systemctl disable systemd-networkd
sudo systemctl start NetworkManager
sudo systemctl enable NetworkManager

# Then update netplan renderer to NetworkManager

8. Document Rollback Procedure

Ensure rollback procedure is clearly documented:

# Method 1: Restore backup configuration
sudo cp /etc/netplan/backup/*.yaml /etc/netplan/
sudo netplan apply

# Method 2: Manual configuration (temporary - survives until reboot)
sudo ip addr add 192.168.1.100/24 dev eth0
sudo ip route add default via 192.168.1.1
sudo ip link set eth0 up

# Method 3: Boot with old configuration
# If netplan try timed out, old config is automatically restored

# Method 4: Edit from recovery mode
# Reboot into recovery mode if remote access is lost
# Edit /etc/netplan/*.yaml
# Run: netplan apply
# Resume normal boot

# Verify rollback
ip addr show
ip route show
ping -c 4 <gateway-ip>

Best Practices

When generating netplan configurations:

1. Use Correct YAML Syntax

   • Always use spaces for indentation (typically 2 spaces)
   • Never use tabs
   • Use proper list syntax with dashes
   • Quote special characters in SSIDs

2. File Naming Convention

   • Use numeric prefixes: 01-, 02-, 10-, 50-
   • Files processed in lexicographical order
   • Example: /etc/netplan/01-network-config.yaml
   • Cloud-init uses 50-, so use 01- to override

3. Renderer Selection

   • networkd: For servers, VMs, containers (lightweight)
   • NetworkManager: For desktops, laptops (feature-rich GUI)

4. Modern vs Legacy Syntax

   • Prefer routes over deprecated gateway4/gateway6
   • Use nameservers for DNS configuration
   • Use addresses with CIDR notation

5. Security

   • Set file permissions to 600 (only root readable)
   • Don't commit files with WiFi passwords to public repos
   • Use separate files for sensitive configurations

6. Testing Strategy

   • Always use netplan try before netplan apply
   • Test in non-production first
   • Have console/KVM access before making changes
   • Keep backup configurations

7. Documentation

   • Add YAML comments for complex configurations
   • Document interface purposes
   • Note any quirks or special requirements

Common Scenarios

Simple Static IP Server (Modern Syntax)

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      addresses:
        - 192.168.1.100/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4

DHCP Configuration

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: true
      dhcp6: false

VLAN Configuration

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
  vlans:
    vlan100:
      id: 100
      link: eth0
      addresses:
        - 10.0.100.1/24
    vlan200:
      id: 200
      link: eth0
      addresses:
        - 10.0.200.1/24

Bridge for Virtualization

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
    eth1:
      dhcp4: false
  bridges:
    br0:
      interfaces:
        - eth0
        - eth1
      addresses:
        - 192.168.1.10/24
      routes:
        - to: default
          via: 192.168.1.1
      parameters:
        stp: false
        forward-delay: 0

Bond Configuration (LACP)

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
    eth1:
      dhcp4: false
  bonds:
    bond0:
      interfaces:
        - eth0
        - eth1
      addresses:
        - 192.168.1.10/24
      routes:
        - to: default
          via: 192.168.1.1
      parameters:
        mode: 802.3ad
        mii-monitor-interval: 100
        lacp-rate: fast

WiFi Configuration

network:
  version: 2
  renderer: NetworkManager
  wifis:
    wlan0:
      access-points:
        "MyNetwork":
          password: "securepassword"
      dhcp4: true

Version Compatibility

Netplan 0.103+:

• Prefer routes with to: default over gateway4/gateway6
• Better routing policy support

Ubuntu Versions:

• Ubuntu 17.10+: Netplan by default
• Ubuntu 20.04 LTS: Netplan 0.99+
• Ubuntu 22.04 LTS: Netplan 0.103+
• Ubuntu 24.04 LTS: Latest netplan features

Renderer Availability:

• systemd-networkd: Available on all netplan systems
• NetworkManager: May need installation on server editions

Migration Notes

From /etc/network/interfaces:

• Netplan uses YAML instead of interfaces file format
• Convert iface eth0 inet static to YAML ethernets section
• Convert bond/bridge syntax to netplan parameters
• Update scripts to use netplan apply instead of ifup/ifdown

From NetworkManager (GUI Config):

• Export existing connections to netplan format
• Use renderer: NetworkManager to keep using GUI
• Or migrate to renderer: networkd for server deployments

Notes

• Netplan is a network configuration abstraction for Ubuntu 17.10+
• Generates backend configuration for NetworkManager or systemd-networkd
• YAML configuration stored in /etc/netplan/
• Changes require netplan apply to take effect
• netplan try is the safest way to test changes (auto-reverts after timeout)
• Files processed in lexicographical order (01-, 02-, etc.)
• Cloud-init may create 50-cloud-init.yaml - use 01- to override

Example Task Invocation

generate-netplan-config I need Ubuntu 22.04 server with static IP 192.168.1.50/24 on enp0s3, gateway 192.168.1.1, two VLANs (100 and 200 on enp0s3), DNS 8.8.8.8, using networkd renderer