zhongwei/gh-phaezer-claude-mkt-plugins-networking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:47:18 +08:00
commit 57a131c6fd
18 changed files with 6838 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

628
commands/generate-netplan-config.md Normal file
View File

@@ -0,0 +1,628 @@
---
description: Generate netplan YAML configuration files
argument-hint: 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:
```bash
# 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**
```bash
# 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**
```bash
# 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)**
```bash
# 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**
```bash
# 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**
```bash
# After successful try, apply permanently
sudo netplan apply
# Or with debug output
sudo netplan --debug apply
```
6. **Verify Configuration**
```bash
# 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:**
```bash
# Generate backend configuration
sudo netplan generate
# Check generated configuration
sudo netplan get
# Show current netplan configuration
cat /etc/netplan/*.yaml
```
**Interface Status:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Show VLAN interfaces
ip -d link show type vlan
# Show specific VLAN
ip -d link show vlan100
```
**Bridge Validation:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:
```bash
# 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)
```yaml
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
```yaml
network:
version: 2
renderer: networkd
ethernets:
eth0:
dhcp4: true
dhcp6: false
```
### VLAN Configuration
```yaml
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
```yaml
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)
```yaml
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
```yaml
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
```