zhongwei/gh-phaezer-claude-mkt-plugins-networking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-phaezer-claude-mkt-plugi…/commands/sonic-config.md
Zhongwei Li 57a131c6fd Initial commit
2025-11-30 08:47:18 +08:00

13 KiB
Raw Permalink Blame History

description, argument-hint
description argument-hint
Generate SONiC NOS configuration files Optional SONiC requirements

You are initiating SONiC (Software for Open Networking in the Cloud) NOS configuration using a structured workflow to create production-ready SONiC configuration files and operational procedures.

Workflow Steps

1. Gather Requirements

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

Basic Requirements:

  • SONiC version (community or enterprise/vendor-specific)
  • Platform/hardware (Broadcom, Mellanox, Intel, etc.)
  • Switch role (Leaf, Spine, ToR, Border, etc.)
  • Hostname and basic metadata

Configuration Type Needed:

  • Interface configuration (physical ports, speeds, MTU)
  • VLAN configuration
  • Port channel/LAG configuration
  • BGP routing configuration
  • OSPF routing configuration
  • ACL configuration
  • QoS configuration
  • Loopback interfaces
  • Static routes
  • System management (NTP, syslog, SNMP)

For Interface Configuration:

  • Interface names (Ethernet0, Ethernet4, etc.)
  • Speeds (10G, 25G, 40G, 100G, 400G)
  • Admin status (up/down)
  • MTU settings (typically 9100 for data centers)
  • FEC settings (RS, FC)

For VLAN Configuration:

  • VLAN IDs and descriptions
  • VLAN member ports
  • Tagging mode (tagged/untagged)
  • VLAN interface IP addresses

For Port Channel/LAG:

  • Port channel interface names
  • Member interfaces
  • LACP configuration
  • Minimum links

For BGP Configuration:

  • Local ASN
  • BGP neighbors (IP, ASN, descriptions)
  • Peer groups
  • Route policies and prefix lists
  • Address families (IPv4, IPv6, EVPN)
  • Authentication

For ACL Configuration:

  • ACL table names and types (L3, L2, CTRLPLANE)
  • ACL rules (priorities, actions, match criteria)
  • Port bindings

For QoS Configuration:

  • DSCP to TC mapping
  • TC to queue mapping
  • Scheduler policies
  • Port QoS profiles

2. Launch sonic-engineer Agent

Use the Task tool to launch the sonic-engineer agent with a detailed prompt containing:

Generate SONiC configuration for the following requirements:

[Insert gathered requirements here with all details]

Please provide:
1. Complete config_db.json file
2. Equivalent CLI commands for reference
3. Step-by-step deployment procedure
4. Validation commands specific to this configuration
5. Rollback procedure
6. Any platform-specific notes or requirements
7. Prerequisites (SONiC version, required features)

3. Review Generated Configuration

When the agent returns the configuration, review it for:

  • Valid JSON syntax
  • Correct SONiC schema structure
  • All required sections present (DEVICE_METADATA, etc.)
  • Proper interface naming for the platform
  • No conflicting configurations
  • Complete BGP/routing configuration
  • Appropriate security settings

4. Validate JSON Syntax

Before deployment, ensure JSON syntax validation:

# Validate JSON syntax
python3 -m json.tool config_db.json

# Or use jq
jq . config_db.json

# Check for common issues
jq 'keys' config_db.json  # Show top-level keys

5. Present Deployment Procedure

Ensure the generated configuration includes a safe deployment procedure:

  1. Backup Current Configuration

    # Save current running config
config save -y

# Create timestamped backup
sudo cp /etc/sonic/config_db.json /etc/sonic/config_db.json.backup.$(date +%Y%m%d_%H%M%S)

# Save current state
show running-config > ~/sonic-config-backup-$(date +%Y%m%d_%H%M%S).txt
show interfaces status >> ~/sonic-config-backup-$(date +%Y%m%d_%H%M%S).txt

  2. Validate New Configuration

    # Validate JSON syntax
python3 -m json.tool new_config_db.json

# Validate SONiC config format
sonic-cfggen -j new_config_db.json --print-data

# Check for required keys
jq 'has("DEVICE_METADATA")' new_config_db.json

  3. Deploy Configuration

    # Copy new configuration
sudo cp new_config_db.json /etc/sonic/config_db.json

# Set correct permissions
sudo chown root:root /etc/sonic/config_db.json
sudo chmod 644 /etc/sonic/config_db.json

  4. Apply Configuration

    # Method 1: Load configuration without full restart
config load /etc/sonic/config_db.json -y

# Method 2: Full configuration reload (restarts services)
config reload -y

# Method 3: Load and save
config load /etc/sonic/config_db.json -y && config save -y

  5. Verify Configuration

    # Check interfaces
show interfaces status

# Check IP configuration
show ip interfaces

# Check BGP (if configured)
show ip bgp summary

# Check VLANs (if configured)
show vlan brief

# Check port channels (if configured)
show interfaces portchannel

# Check system status
show system-health

6. Provide Validation Commands

Include comprehensive validation commands for each configuration type:

Interface Validation:

# Show all interface status
show interfaces status

# Show specific interface
show interfaces status Ethernet0

# Show interface counters
show interfaces counters

# Show interface errors
show interfaces counters errors

# Show transceiver information
show interfaces transceiver info

# Show interface description
show interfaces description

VLAN Validation:

# Show VLAN configuration
show vlan brief

# Show detailed VLAN config
show vlan config

# Show VLAN member ports
show vlan id 100

Port Channel Validation:

# Show port channel summary
show interfaces portchannel

# Show LACP status
show lacp neighbor
show lacp internal

# Show port channel details
show interface PortChannel1

BGP Validation:

# Show BGP summary
show ip bgp summary

# Show BGP neighbors
show ip bgp neighbors

# Show BGP routes
show ip bgp

# Show received routes from neighbor
show ip bgp neighbors 192.168.1.1 received-routes

# Show advertised routes to neighbor
show ip bgp neighbors 192.168.1.1 advertised-routes

# Show BGP configuration
show runningconfiguration bgp

OSPF Validation:

# Show OSPF neighbors
show ip ospf neighbor

# Show OSPF routes
show ip ospf route

# Show OSPF database
show ip ospf database

# Show OSPF interfaces
show ip ospf interface

ACL Validation:

# Show ACL tables
show acl table

# Show ACL rules
show acl rule

# Show ACL counters
acl-loader show table
acl-loader show rule

QoS Validation:

# Show QoS maps
show qos map dscp-to-tc
show qos map tc-to-queue

# Show queue counters
show queue counters

# Show priority-group
show priority-group

System Validation:

# Show system information
show version
show platform summary
show platform syseeprom

# Show services
show services

# Show system health
show system-health

# Show running configuration
show running-config

7. Include Troubleshooting Commands

Provide troubleshooting commands for common issues:

Configuration Not Applied:

# Check config_db.json syntax
python3 -m json.tool /etc/sonic/config_db.json

# Check SONiC services
show services

# Restart specific service
sudo systemctl restart bgp
sudo systemctl restart swss

# Check service logs
sudo journalctl -u bgp -n 100
sudo journalctl -u swss -n 100

# View syslog
show logging
tail -f /var/log/syslog

Interface Issues:

# Check interface admin state
show interfaces status Ethernet0

# Check physical link
show interfaces transceiver info Ethernet0

# Check interface errors
show interfaces counters errors Ethernet0

# Clear interface counters
sonic-clear counters

# Check ASIC programming
show platform switch

BGP Not Establishing:

# Check BGP configuration
show runningconfiguration bgp

# Check BGP neighbors
show ip bgp neighbors 192.168.1.1

# Enable BGP debugging
vtysh -c "debug bgp neighbor-events"
vtysh -c "debug bgp updates"

# Check connectivity to neighbor
ping 192.168.1.1

# Check routing table
show ip route

VLAN Issues:

# Check VLAN configuration
show vlan config

# Check VLAN member configuration
redis-cli -n 4 HGETALL "VLAN_MEMBER|Vlan100|Ethernet8"

# Check bridge FDB
show mac

# Check VLAN interface
show ip interfaces | grep Vlan

Database Issues:

# Access config database (DB 4)
redis-cli -n 4

# Show all keys
redis-cli -n 4 KEYS "*"

# Show specific configuration
redis-cli -n 4 HGETALL "PORT|Ethernet0"
redis-cli -n 4 HGETALL "DEVICE_METADATA|localhost"

# Check application database (DB 0)
redis-cli -n 0 KEYS "*"

8. Document Rollback Procedure

Ensure rollback procedure is clearly documented:

# Method 1: Restore from backup
sudo cp /etc/sonic/config_db.json.backup.YYYYMMDD_HHMMSS /etc/sonic/config_db.json
config reload -y

# Method 2: Load previous working config
config load /etc/sonic/config_db.json.backup.YYYYMMDD_HHMMSS -y

# Method 3: Manual configuration via CLI (temporary)
# Use vtysh for routing protocols
sudo vtysh
# Use config commands for interfaces/VLANs
config interface ip add Ethernet0 192.168.1.1/24

# Method 4: Factory reset (CAUTION)
# sudo config-setup factory

# Verify rollback
show interfaces status
show ip bgp summary
show vlan brief

Best Practices

When generating SONiC configurations:

  1. Configuration Management

    • Always backup before changes
    • Use version control for config_db.json
    • Test in lab environment first
    • Document all changes

  2. Interface Configuration

    • Use consistent interface naming
    • Configure appropriate MTU for network (9100 for data centers)
    • Enable FEC where appropriate
    • Add meaningful descriptions

  3. Routing Configuration

    • Use BGP authentication
    • Implement prefix filtering
    • Configure maximum-prefix limits
    • Use BFD for fast convergence

  4. VLAN Design

    • Plan VLAN ID scheme
    • Use meaningful VLAN descriptions
    • Separate traffic types appropriately
    • Configure VLAN interfaces for L3

  5. High Availability

    • Configure redundant uplinks
    • Use port channels for link aggregation
    • Implement BFD for fast failure detection
    • Configure multiple BGP sessions

  6. Security

    • Implement control plane ACLs
    • Use routing protocol authentication
    • Configure management ACLs
    • Enable logging and monitoring

  7. Operational Excellence

    • Configure NTP for time synchronization
    • Set up syslog to central server
    • Enable SNMP monitoring
    • Use consistent naming conventions

Common Scenarios

Data Center Leaf Switch (BGP Unnumbered)

  • Underlay BGP with spine neighbors
  • VLAN configuration for server access
  • Port channels for server bonding
  • Loopback for VTEP
  • ACLs for security

Top-of-Rack (ToR) Switch

  • Access port configuration for servers
  • Uplinks to spine (port channels)
  • VLANs for network segmentation
  • Basic BGP or OSPF routing
  • QoS policies

Spine Switch

  • High-density 100G/400G interfaces
  • BGP configuration for all leaf neighbors
  • Route reflection (if used)
  • Minimal VLANs (management only)
  • BFD for fast convergence

Border/Edge Switch

  • External BGP peering
  • Route filtering and policies
  • ACLs for security
  • NAT configuration (if supported)
  • Internet routing table handling

SONiC Architecture Notes

Key Components:

  • Redis Database: Configuration and state storage
  • Docker Containers: Modular service architecture
  • SAI: Switch Abstraction Interface for hardware
  • FRR: Routing protocol daemon (BGP, OSPF, etc.)
  • Orchestration Agent: Translates config to ASIC

Database Structure:

  • ConfigDB (DB 4): Configuration data
  • AppDB (DB 0): Application state
  • StateDB (DB 6): Operational state
  • ASIC_DB (DB 1): Hardware programming

Configuration Methods:

  1. config_db.json (recommended for automation)
  2. CLI commands (immediate application)
  3. OpenConfig/gNMI (enterprise features)
  4. REST API (if available)

Platform Considerations

Broadcom-based Switches:

  • Common in enterprise and cloud
  • SAI fully supported
  • Check BCM shell access if needed

Mellanox-based Switches:

  • Common in high-performance networks
  • Spectrum ASIC series
  • Check SX-SDK version

Barefoot/Intel Tofino:

  • Programmable pipeline
  • P4 runtime support
  • Check platform-specific features

Interface Naming:

  • Usually Ethernet0, Ethernet4, etc. (increments of 4)
  • Check platform documentation for mapping
  • Alias field for human-readable names

Notes

  • SONiC uses JSON-based configuration (config_db.json)
  • Configuration stored in Redis database
  • Supports both CLI and file-based configuration
  • Container-based architecture for modularity
  • Uses FRR for routing protocols (BGP, OSPF, IS-IS)
  • SAI provides hardware abstraction
  • Always validate JSON syntax before deployment
  • Test routing changes in maintenance windows
  • Monitor ASIC programming after changes

Example Task Invocation

sonic-config I need a data center leaf switch configuration with ASN 65001, two spine BGP neighbors (192.168.1.1 and 192.168.1.2 both AS 65100), VLAN 100 for servers on Ethernet8-Ethernet24, loopback 10.0.0.1/32, and port channel with Ethernet0 and Ethernet4 for uplink
Reference in New Issue View Git Blame Copy Permalink