Sync Device Components from Template

A comprehensive NetBox custom script for synchronizing device components with device type templates. This script enables efficient bulk management of interfaces, ports, and bays across your infrastructure.

📋 Table of Contents

• Features
• Requirements
• Installation
• Usage
• Operation Modes
• Component Types
• Stack-Aware Interface Renaming
• Configuration Guide
• Testing
• Troubleshooting
• Contributing
• License

✨ Features

Supported Component Types (9 Total)

• Interfaces - Network interfaces (Ethernet, GigabitEthernet, etc.)
• Rear Ports - Rear panel connection ports
• Front Ports - Front panel connection ports
• Power Ports - Device power input connections
• Power Outlets - Power distribution outlets
• Console Ports - Console management ports
• Console Server Ports - Console server connections
• Module Bays - Expansion module/card slots
• Device Bays - Chassis expansion bays

Operation Modes

• Safe Mode - Creates new + Updates existing + Preserves components not in template (least destructive)
• Standard Mode - Creates new + Updates existing + Deletes components not in template
• Clean Sync Mode - Full synchronization with explicit deletion warnings
• Replicate Only - Only creates new components (no updates or deletes)
• Update Only - Only updates existing components (no creates or deletes)

Advanced Features

• Stack-Aware Interface Renaming - Automatically rename interfaces in Virtual Chassis environments
• Comprehensive Reporting - Detailed change summary with per-device statistics
• Component Tagging - Auto-tag created components with 'netbox-script' for tracking
• Deletion Warnings - Impact assessment for components being deleted
• Version Compatibility - Graceful handling of different NetBox versions
• Per-Device Statistics - Detailed tracking of changes per device

📦 Requirements

• NetBox 4.0 or later (Tested on NetBox 4.4.10 ✅)
• Django 3.2 or later
• Python 3.8 or later
• Tagging Support - Either django-tagging or django-taggit (optional but recommended)

NetBox Version Compatibility

Component	Min NetBox Version	Status
Interfaces, Ports	1.0+	✅ Tested
Power Components	2.0+	✅ Tested
Console Components	2.0+	✅ Tested
Module Bays	4.0+	✅ Tested on 4.4.10
Device Bays	4.0+	✅ Tested on 4.4.10

✅ Verified Working on: NetBox 4.4.10

Note: The script includes fallback handling for older versions. Module Bay and Device Bay synchronization will gracefully skip if not available in your NetBox version.

🔧 Installation

Option 1: Using NetBox UI (Easiest - Recommended)

No need to verify NetBox, Django, or Python - Just upload!

1. Navigate to Scripts: Go to Customization > Scripts in NetBox
2. Click "Add" button to create a new script
3. Choose the script file: Click "Choose file" and select Sync Device Components.py
4. Create: Click "Create" button
5. Done! Script is now ready to use

That's it! NetBox handles everything automatically.

Option 2: Using CLI (Command Line)

Copy Sync Device Components.py to your NetBox custom scripts directory:

# Linux/macOS
cp "Sync Device Components.py" /opt/netbox/netbox/scripts/

# Windows
Copy "Sync Device Components.py" "C:\netbox\netbox\scripts\"

Then restart NetBox:

# Using Docker
docker-compose restart

# Using systemd
sudo systemctl restart netbox netbox-rq

# Using supervisor
sudo supervisorctl restart netbox netbox-rq

File Placement (For CLI Method)

• Default path: /opt/netbox/netbox/scripts/
• Check your installation: Settings > System Configuration > Scripts Directory

# Using Docker
docker-compose restart

# Using systemd
sudo systemctl restart netbox netbox-rq

# Using supervisor
sudo supervisorctl restart netbox netbox-rq

Step 4: Verify Installation

For UI Method:

1. Log in to NetBox admin panel
2. Navigate to Customization > Scripts
3. Search for "Sync Device Components from Template"
4. Script should appear with green status (✓)

For CLI Method:

1. Log in to NetBox admin panel
2. Navigate to Customization > Scripts
3. Search for "Sync Device Components from Template"
4. Script should appear with green status (✓)
5. If not visible, restart NetBox services again

📖 Usage

Basic Workflow

1. Navigate to Scripts: Go to Customization > Scripts in NetBox UI
2. Click the Script: Select "Sync Device Components from Template"
3. Configure Parameters: See Configuration Guide
4. Preview Changes: Leave "Commit" unchecked first (Preview mode)
5. Execute: Click "Execute" button
6. Review Report: Examine the generated report for accuracy
7. If Satisfied: Run again with "Commit" checked to save changes
8. Validate: Review report showing all changes applied
9. Validate: Review the execution report and verify changes in NetBox

Example Scenarios

Scenario 1: Update All Interfaces on a Device Type

Operation Mode: Standard Mode
Device Type: Cisco Nexus 9396PX
Component Selection:
  ✓ Sync Interfaces
  ☐ Other components
Commit: Unchecked (Preview first)

Scenario 2: Stack-Aware Renaming for Virtual Chassis

Operation Mode: Replicate Only
Devices: Select Virtual Chassis devices
Component Selection:
  ✓ Sync Interfaces
Stack-Aware Rename: Checked
Stack Pattern: (\D+)(\d+)(/.*) $
Commit: Unchecked (Preview first)

Scenario 3: Full Synchronization with Cleanup

Operation Mode: Clean Sync Mode
Devices: Select multiple devices
Component Selection:
  ✓ Sync Interfaces
  ✓ Sync Power Ports
  ✓ Sync Console Ports
Commit: Checked

🎯 Operation Modes

Safe Mode

• ✅ Creates new components from template
• ✅ Updates existing components
• ✅ Preserves components not in template
• Use Case: First-time sync, preserving custom components
• Risk Level: Lowest

Standard Mode

• ✅ Creates new components from template
• ✅ Updates existing components
• ❌ Deletes components not in template
• Use Case: Regular maintenance sync
• Risk Level: Medium

Clean Sync Mode

• ✅ Creates new components from template
• ✅ Updates existing components
• ❌ Deletes components not in template
• ⚠️ Displays detailed warnings about deletions
• Use Case: Full cleanup with awareness
• Risk Level: High (requires confirmation)

Replicate Only

• ✅ Creates new components from template
• ❌ No updates to existing components
• ❌ No deletions
• Use Case: Adding new components only
• Risk Level: Low

Update Only

• ❌ No new component creation
• ✅ Updates existing components
• ❌ No deletions
• Use Case: Modifying descriptions without adding/removing
• Risk Level: Low

🔌 Component Types

Each component type supports:

• Creation - Add new components matching template
• Update - Modify descriptions and properties
• Deletion - Remove components not in template (in applicable modes)
• Tagging - Automatic tagging for audit trail
• Tracking - Per-device statistics

Interface Configuration

Type: Network Interface
Examples: Ethernet0/0, GigabitEthernet1/0/1, 100GE1/0/1
Properties:
  - Name (required)
  - Type (ETH, GE, 100GE, etc.)
  - MTU (optional)
  - Description (optional)

Port Configuration

Rear/Front Ports:
  - Name (required)
  - Type (RJ45, LC, ST, etc.)
  - Positions (optional)

Power Ports/Outlets:
  - Name (required)
  - Power Type (IEC 60320-C13, NEMA 5-15P, etc.)
  - Feed Leg (optional)

Console Ports/Server Ports:
  - Name (required)
  - Type (RJ45, Mini-DIN 8, etc.)

Bay Configuration

Module Bays:
  - Name (required)
  - Position (optional)
  - Description (optional)

Device Bays:
  - Name (required)
  - Position (optional)
  - Description (optional)

🏗️ Stack-Aware Interface Renaming

What is Stack-Aware Renaming?

In Virtual Chassis (VC) environments, multiple devices operate as a single logical unit. Stack-aware renaming automatically adjusts interface names based on each device's position in the stack.

Example

Virtual Chassis Setup:

• Device 1 (Position 1): Member 1
• Device 2 (Position 2): Member 2
• Device 3 (Position 3): Member 3

Device Type Template:

Interfaces:
  - GigabitEthernet1/0/1
  - GigabitEthernet1/0/2
  - GigabitEthernet1/0/3
  (etc.)

After Stack-Aware Rename:

Device Position	Original	Renamed To
1	GigabitEthernet1/0/1	GigabitEthernet1/0/1 (unchanged)
2	GigabitEthernet1/0/1	GigabitEthernet2/0/1
3	GigabitEthernet1/0/1	GigabitEthernet3/0/1

Regex Pattern Guide

The script uses regex patterns to identify the stack position in interface names and replace it.

Pattern Structure

(\D+)(\d+)(/.*) $

Groups:

• Group 1: (\D+) - Interface prefix (non-digits) e.g., GigabitEthernet
• Group 2: (\d+) - Stack position digit (gets replaced) e.g., 1
• Group 3: (/.*) - Port path (remains unchanged) e.g., /0/1

Common Vendor Patterns

Vendor	Pattern	Example
Cisco IOS	(\D+)(\d+)(/.*)$	GigabitEthernet1/0/1 → GigabitEthernet2/0/1
Cisco 100GE	(\D+)(\d+)(/.*)$	HundredGigE1/0/1 → HundredGigE2/0/1
Juniper	(\w+)-(\d+)-(\d+)	ge-1-0-0 → ge-2-0-0
Arista	(Ethernet)(\d+)(/.*)$	Ethernet1/1 → Ethernet2/1
HP/Aruba	(Eth)(\d+)(/.*)$	Eth1/1 → Eth2/1
Hyphenated	(\w+)-(\d+)$	eth-1 → eth-2

Testing Your Pattern

1. Go to regex101.com
2. Enter your pattern in the regular expression field
3. Paste your interface name in the test string field
4. Verify that group 2 captures only the position digit

Pattern Troubleshooting

Issue	Cause	Solution
Pattern doesn't match	Wrong anchors or groups	Verify 3 groups, use $ at end
All digits captured	Group 1 too greedy	Use \D+ instead of \w+
Position not replaced	Wrong group number	Ensure position is in group 2
Extra characters included	Group 3 incomplete	Include complete remainder in group 3

⚙️ Configuration Guide

Device Type Selection

• Required: Yes
• Description: Filter devices by device type (optional for specific type, required if filtering)
• Use: Select the device type whose components you want to sync

Device Selection

• Required: Yes
• Description: Select specific devices to update
• Supports: Multiple selection (Ctrl+Click or Shift+Click)
• Tip: Filter by device type first to narrow selection

Operation Mode

• Required: Yes
• Default: Standard Mode
• Options: Safe, Standard, Clean Sync, Replicate Only, Update Only
• Recommendation: Use Safe Mode for first-time sync

Component Selection

• Required: No (at least one must be selected)
• Default: Interfaces only
• Options: Interfaces, Rear Ports, Front Ports, Power Ports, Power Outlets, Console Ports, Console Server Ports, Module Bays, Device Bays
• Note: Select only components you want to sync

Stack-Aware Interface Renaming

• Type: Boolean (Checkbox)
• Default: Unchecked (disabled)
• Required: Regex pattern if enabled
• Use: Virtual Chassis environments
• Prerequisite: Devices must have Virtual Chassis relationships configured

Stack Pattern (Regex)

• Type: Text (Regular Expression)
• Default: (\D+)(\d+)(/.*) $
• Required if: Stack-aware renaming is enabled
• Format: Must contain 3 capture groups
• Example: (\D+)(\d+)(/.*)$

Commit

• Type: Boolean (Checkbox)
• Default: Unchecked (preview mode)
• Important: Always preview changes first (leave unchecked)
• Checked: Saves all changes to database
• Recommendation: Review report before checking

🧪 Testing

See TESTING.md for comprehensive testing procedures including:

• Pre-deployment validation
• Functional testing in development
• Performance testing
• Rollback procedures
• Production deployment checklist

🆘 Troubleshooting

Script Not Appearing in NetBox

Problem: Script doesn't show in Customization > Scripts

Solutions:

1. Verify file placement: /opt/netbox/netbox/scripts/
2. Check file permissions: chmod 644 "Sync Device Components.py"
3. Verify Python syntax: python -m py_compile "Sync Device Components.py"
4. Restart NetBox: docker-compose restart or systemctl restart netbox
5. Check NetBox logs for import errors: docker-compose logs netbox

Import Errors

Problem: "ModuleBay not found" or similar import error

Solution: Your NetBox version may not support this component type

• Module Bays require NetBox 4.0+
• Device Bays require NetBox 4.0+
• Script gracefully handles missing components via try/except
• Check NetBox version: Settings > About

Stack Renaming Not Working

Problem: Interface names not being renamed with stack pattern

Solutions:

1. Verify stack pattern is correct regex
2. Test pattern on regex101.com
3. Ensure devices are part of Virtual Chassis
4. Check device VC positions are set correctly
5. Verify pattern has 3 capture groups

Too Many Changes Reported

Problem: Script reports more changes than expected

Solutions:

1. Use Preview mode first (uncheck Commit)
2. Review report carefully
3. Check if device templates have many components
4. Consider using "Replicate Only" for test
5. Run on fewer devices to verify behavior

Performance Issues

Problem: Script runs slowly or times out

Solutions:

1. Reduce number of selected devices
2. Reduce component types selected
3. Check NetBox database performance
4. Consider running on subset first
5. Check NetBox task timeout settings (default 300s)

📊 Report Output

The script generates a comprehensive CSV report including:

Summary Section

• Operation mode used
• Device type and selection
• Selected components and options
• Execution timestamp

Component Totals

• Global statistics for each component type
• Total created, updated, deleted counts
• Per-device breakdown table

Per-Device Details

• Device name
• Created/updated/deleted counts for each component type
• Quick overview of changes per device

Deleted Components Warning

• List of all deleted components (if any)
• Timestamp of deletion
• Impact assessment:
  • Cables disconnected
  • Descriptions removed
  • IP addresses removed
  • Custom attributes lost

🔐 Safety Features

• Preview Mode: Review changes before committing
• Commit Flag: Must explicitly enable to make changes
• Dry-Run Support: Always run with Preview first
• Deletion Warnings: Clear notifications about destructive operations
• Component Tagging: Track script-created components with 'netbox-script' tag
• Audit Trail: Detailed reports of all changes
• Rollback Info: Deleted component details for manual restoration

📝 Best Practices

1. Always Preview First

   • Uncheck "Commit" for first run
   • Review the report carefully
   • Verify changes before committing

2. Start Small

   • Test on single device first
   • Verify results match expectations
   • Expand to more devices

3. Use Safe Mode

   • First-time sync: use Safe Mode
   • Prevents accidental deletions
   • Preserves custom components

4. Document Changes

   • Save execution reports
   • Track which devices were updated
   • Keep audit trail for compliance

5. Test Stack Patterns

   • Use regex101.com to verify pattern
   • Test on single device first
   • Verify renamed interfaces are correct

6. Backup First

   • Backup NetBox database before large changes
   • Export device configuration first
   • Have rollback plan ready

🤝 Contributing

To contribute improvements:

1. Test thoroughly in development environment
2. Document any new features
3. Maintain backward compatibility
4. Update this README with changes
5. Include test cases

📄 License

MIT License - Feel free to use and modify for your needs

❓ Support

For issues or questions:

1. Check TESTING.md for testing procedures
2. Review Troubleshooting section
3. Check NetBox logs: docker-compose logs netbox | grep Sync
4. Verify NetBox version compatibility
5. Test with Preview mode first

📚 Additional Resources

• NetBox Documentation
• NetBox Custom Scripts
• Django Regex Documentation
• Regex Testing Tool

---

Last Updated: January 2026
Version: 1.2
Status: Production Ready ✅