dpx_vlan_maestro

Hyper-V Network Configuration Automation

PowerShell script that creates virtual switches and VLAN-tagged network adapters for different facility configurations
» Project Here! »
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Reflection
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

DPX_VLAN_MAESTRO is a comprehensive PowerShell automation script for Windows Hyper-V environments. It simplifies the complex process of setting up virtual network infrastructure by creating virtual switches, VLAN-tagged network adapters, and assigning static IP addresses according to facility-specific configurations.

The script supports multiple facility types (4Wall, Aeon Point, Desert, and custom configurations) with dynamic VLAN set loading from external JSON files. It includes robust validation, safety features, and multiple operation modes to handle different network management scenarios.

Key Capabilities:

• Dynamic Configuration: Load VLAN sets from external JSON files without code changes
• Subnet-Aware Validation: Comprehensive IP validation against subnet constraints
• Multiple Modes: Normal setup, IP-only updates, and complete cleanup (nuke all)
• Safety Features: Deep cleanup, adapter reset, and explicit confirmations
• Configuration Summary: Detailed output showing all network settings

author(s): // www.dubpixel.tv - i@dubpixel.tv

Images

FRONT

Features

🔧 Dynamic VLAN Configuration

• Load facility-specific VLAN sets from external JSON files
• Support for multiple facility types (4Wall, Aeon Point, Desert, custom)
• No code changes required to add new configurations

🛡️ Advanced IP Management

• Subnet-aware IP validation with network/broadcast address checking
• Dynamic IP prompting based on configuration templates
• Default value support for common octets
• Comprehensive validation with detailed error messages
• DHCP or Static IP configuration choice

⚙️ Multiple Operation Modes

• Normal Mode: Complete setup (switch + adapters + IPs)
• IP Only Mode: Update IP addresses on existing adapters
• Nuke All Mode: Complete cleanup of all virtual switches

🔍 Safety & Validation

• Deep cleanup of existing configurations
• Adapter binding reset and verification
• Explicit confirmation for destructive operations
• Comprehensive error handling and retry logic

📊 Configuration Summary

• Detailed output showing all network settings
• VLAN assignments with IP addresses and broadcast ranges
• Selected NIC and subnet information

🏗️ Built With

• PowerShell 5.1+
• Windows Hyper-V
• GitHub Copilot (AI-assisted development)

(back to top)

Getting Started

Prerequisites

System Requirements

• Operating System: Windows 10/11 Pro, Enterprise, or Education (Home edition does not support Hyper-V)
• PowerShell: Version 5.1 or higher (included with Windows)
• Hardware: At least one physical network adapter
• Permissions: Administrative privileges required

Hyper-V Setup

1. Enable Hyper-V Feature

   • Open Control Panel → Programs → Turn Windows features on or off
   • Check "Hyper-V" and "Hyper-V Management Tools"
   • Restart computer when prompted

2. Verify Hyper-V Installation

   # Run in PowerShell as Administrator
   Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All

3. Check Hyper-V Services

   # Verify Hyper-V services are running
   Get-Service -Name vmms, vmicvss, vmicguestinterface, vmicheartbeat

Installation

1. Clone the repository

   git clone https://github.com/dubpixel/dpx_vlan_maestro.git

2. Navigate to the PowerShell script directory

   cd dpx_vlan_maestro/src

3. Ensure you have administrative privileges
4. Run PowerShell as Administrator

Running the Script

There are three ways to run the script. Method 1 is recommended as it handles PowerShell execution policies automatically.

Method 1: Using the Batch File (Recommended)

The easiest way to run the script:

1. Navigate to the src folder
2. Right-click on vlan_maestro.bat
3. Select "Run as Administrator"

The batch file automatically bypasses PowerShell execution policy restrictions.

Method 2: PowerShell with Bypass

If you prefer running PowerShell directly:

# Open PowerShell as Administrator, then:
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
.\vlan_maestro.ps1

This temporarily bypasses execution policy for the current session only.

Method 3: One-Line Execution

Run directly from any command prompt (as Administrator):

powershell -ExecutionPolicy Bypass -File ".\vlan_maestro.ps1"

Execution Policy Notes

• Windows restricts PowerShell script execution by default for security
• The -ExecutionPolicy Bypass flag allows the script to run without changing system-wide settings
• Administrative privileges are required for Hyper-V operations
• The batch file handles this automatically

Configuration

⚙️ Click to expand configuration guide

VLAN Sets Configuration

VLAN configurations are stored in src/vlan_sets.json. The script automatically loads all facility configurations from this file.

Adding a New Facility

{
  "vlanSets": {
    "YourFacilityName": {
      "vlans": [
        {"Name": "Server_VLAN", "VlanId": 100},
        {"Name": "Client_VLAN", "VlanId": 200},
        {"Name": "Management", "VlanId": 999}
      ],
      "ipBase": "10.{vlan}.{third}.{fourth}",
      "ipPrompts": ["third", "fourth"],
      "ipDefaults": {"third": 10},
      "subnet": "255.255.255.0"
    }
  }
}

Subnet Notation Examples

The script supports both dotted decimal and CIDR notation for subnet masks:

// Dotted decimal notation
"subnet": "255.252.0.0"    // /14 subnet

// CIDR notation  
"subnet": "/14"            // Equivalent to 255.252.0.0

// Other common examples
"subnet": "255.255.255.0"  // /24 (Class C)
"subnet": "255.255.252.0"  // /22 
"subnet": "255.254.0.0"    // /15

Configuration Parameters

• vlans: Array of VLAN objects with Name and VlanId properties
• ipBase: IP address template using placeholders:
  • {vlan} - Replaced with the VLAN ID
  • {third} - Third octet (user prompted)
  • {fourth} - Fourth octet (user prompted)
• ipPrompts: Array of octets the user will be prompted to enter
• ipDefaults: Optional default values for prompted octets
• subnet: Subnet mask - supports both formats:
  • Dotted decimal: "255.252.0.0" (recommended)
  • CIDR notation: "/14" (automatically converted)

IP Configuration Examples

Facility	IP Template	Result (vlan=100, third=5, fourth=10)
Standard	10.{vlan}.{third}.{fourth}	10.100.5.10
Desert	192.168.{vlan}.{fourth}	192.168.100.10
Custom	172.16.{third}.{vlan}	172.16.5.100

Usage

Prerequisites

• Windows 10/11 with Hyper-V enabled
• PowerShell with administrative privileges
• Network adapter(s) available for virtual switch creation

Script Features

Subnet-Aware IP Validation

The script validates all IP addresses against subnet constraints:

• Checks for network and broadcast address conflicts
• Displays detailed validation results
• Shows network and broadcast ranges for each IP
• Prevents invalid configurations before applying changes

Configuration Summary

At completion, the script displays:

• Selected network adapter
• Subnet mask information
• All VLAN assignments with IP addresses
• Broadcast address ranges

Safety Features

• Comprehensive warnings about network disruption
• Deep cleanup of existing configurations
• Adapter binding reset and verification
• Explicit confirmation for destructive operations

Script Workflow

1. Select VLAN Set

   • Script automatically loads all available VLAN sets from vlan_sets.json
   • Choose from any configured facility (4Wall, Aeon Point, Desert, or custom sets)
   • Each set contains predefined VLAN configurations

2. Select Mode

   • Normal Mode: Creates virtual switch, adapters, and assigns IPs
   • IP Only Mode: Skips creation, only assigns IP addresses to existing adapters
   • Nuke All Mode: Removes all virtual switches except default/built-in ones (with confirmation)

3. Normal Mode Steps

   • Select physical network adapter from list
   • Enter virtual switch name (defaults to "vLanSwitch")
   • Script creates virtual switch and VLAN adapters with delays

4. IP Configuration

   • Script prompts for IP method: DHCP (automatic) or Static IP (manual octet entry)
   • For Static IP: Script prompts for required IP octets based on VLAN set configuration
   • For DHCP: All virtual adapters are configured for automatic IP assignment
   • Defaults are shown if defined in vlan_sets.json
   • IP addresses are built from the ipBase template (e.g., 10.{vlan}.{third}.{fourth})
   • Common patterns:
     • Standard: 10.<vlan_id>.<3rd_octet>.<4th_octet>
     • Desert: 192.168.<vlan_id>.<4th_octet>
     • Custom: Any combination defined in JSON

5. Nuke All Mode

   • Removes all user-created virtual switches and their VLAN adapters
   • Preserves default/built-in switches (like "Default Switch")
   • Requires explicit confirmation by typing "YES"

6. Completion

   • Script assigns static IPs to all virtual adapters (in Normal/IP-only modes)
   • Displays progress and completion status

📋 Click to expand usage examples

Scenario 1: Complete Setup (Normal Mode)

Setting up a new Hyper-V host with AeonPoint VLAN configuration:

PS C:\DPX_VLAN_MAESTRO\src> .\vlan_maestro.ps1

# ASCII art title and warning messages display...

Available VLAN sets:
1. 4Wall (6 VLANs)
2. AeonPoint (10 VLANs)
3. Desert (13 VLANs)
4. ExampleFacility (3 VLANs)
Enter choice (1-4): 2
Using AeonPoint VLAN set (10 VLANs).

Select mode:
1. Normal (create switch and adapters, then IP)
2. IP only (skip creation, only assign IPs)
3. Nuke all (remove all virtual switches except default)
Enter choice (1, 2, or 3, press Enter for Normal): 1

Listing available network adapters:
1. Ethernet - Intel(R) I350 Gigabit Network Connection
2. Ethernet 2 - Realtek PCIe GbE Family Controller
Select the NIC by number (1-2): 1
Selected NIC: Ethernet

Enter virtual switch name (press Enter for default: vLanSwitch):
Using switch name: vLanSwitch

Checking for existing virtual switches bound to 'Ethernet'...
Creating virtual switch 'vLanSwitch'...
Adding virtual adapter '10_Server_A'...
Setting VLAN ID 10 for '10_Server_A'...
# ... continues for all VLANs ...

Enter the third octet for IP addresses (press Enter for default: 13): 20
Enter the fourth octet for IP addresses: 100

Setting IP 192.168.101.100 for '101_Server_A'...
✓ Successfully set IP 192.168.101.100 for '101_Server_A'
# ... continues for all adapters ...

Script completed.

Result: All Desert VLANs configured with static IPs like 192.168.101.100, 192.168.102.100, etc.

---

Scenario 1.5: DHCP Configuration

Using DHCP for automatic IP assignment instead of static IPs:

PS C:\DPX_VLAN_MAESTRO\src> .\vlan_maestro.ps1

# ... VLAN set and mode selection ...

IP Configuration Method:
1. Static IP (configure custom IP addresses)
2. DHCP (use automatic IP assignment)

Choose IP method (1 for Static, 2 for DHCP, press Enter for Static): 2
Using DHCP for IP configuration.

Setting DHCP for '101_Server_A'...
Enabling DHCP for '101_Server_A'...
✓ Successfully enabled DHCP for '101_Server_A'
# ... continues for all adapters ...

Script completed.

Result: All VLAN adapters configured for DHCP - network will assign IPs automatically.

---

Scenario 2: IP Address Update Only

Changing IP addresses on existing VLAN adapters without recreating them:

PS C:\DPX_VLAN_MAESTRO\src> .\vlan_maestro.ps1

Available VLAN sets:
1. 4Wall (6 VLANs)
2. AeonPoint (10 VLANs)
3. Desert (13 VLANs)
Enter choice (1-4): 3
Using Desert VLAN set (13 VLANs).

Select mode:
1. Normal (create switch and adapters, then IP)
2. IP only (skip creation, only assign IPs)
3. Nuke all (remove all virtual switches except default)
Enter choice (1, 2, or 3, press Enter for Normal): 2

Enter the fourth octet for IP addresses: 50

Setting IP 192.168.101.50 for '101_Server_A'...
✓ Successfully set IP 192.168.101.50 for '101_Server_A'
# ... continues for all adapters ...

Script completed.

Result: IPs updated to 192.168.101.50, 192.168.102.50, etc. without recreating switches.

---

Scenario 3: Complete Cleanup (Nuke All)

Removing all virtual switches before decommissioning or rebuilding:

PS C:\DPX_VLAN_MAESTRO\src> .\vlan_maestro.ps1

Available VLAN sets:
1. 4Wall (6 VLANs)
2. AeonPoint (10 VLANs)
3. Desert (13 VLANs)
Enter choice (1-4): 1

Select mode:
1. Normal (create switch and adapters, then IP)
2. IP only (skip creation, only assign IPs)
3. Nuke all (remove all virtual switches except default)
Enter choice (1, 2, or 3, press Enter for Normal): 3

NUKE ALL MODE: Removing all virtual switches except default switches...
WARNING: This will remove ALL user-created virtual switches and their VLAN adapters!
Are you sure you want to continue? Type 'YES' to confirm: YES

Removing switch 'vLanSwitch' and all its adapters...
Removing adapter '10_Server_A'...
# ... continues for all adapters and switches ...
Skipping default/built-in switch 'Default Switch'

Nuke all operation completed.

Result: All user-created switches removed, system returned to clean state.

---

Scenario 4: Custom Facility Setup

Using a custom VLAN set defined in vlan_sets.json:

// Added to vlan_sets.json:
"StudioB": {
  "vlans": [
    {"Name": "15_Control", "VlanId": 15},
    {"Name": "25_Audio_Dante", "VlanId": 25},
    {"Name": "35_Video_NDI", "VlanId": 35}
  ],
  "ipBase": "10.{vlan}.5.{fourth}",
  "ipPrompts": ["fourth"],
  "ipDefaults": {},
  "subnet": "255.255.255.0"
}

PS C:\DPX_VLAN_MAESTRO\src> .\vlan_maestro.ps1

Available VLAN sets:
1. 4Wall (6 VLANs)
2. AeonPoint (10 VLANs)
3. Desert (13 VLANs)
4. ExampleFacility (3 VLANs)
5. StudioB (3 VLANs)
Enter choice (1-5): 5
Using StudioB VLAN set (3 VLANs).

# ... select mode, NIC, switch name ...

Enter the fourth octet for IP addresses: 10

Setting IP 10.15.5.10 for '15_Control'...
Setting IP 10.25.5.10 for '25_Audio_Dante'...
Setting IP 10.35.5.10 for '35_Video_NDI'...

Script completed.

Result: Custom facility configured with fixed third octet (5) as defined in JSON.

Troubleshooting

🔧 Click to expand troubleshooting guide

Common Issues and Solutions

"Failed while adding virtual Ethernet switch connections"

Problem: The selected network adapter is already bound to another virtual switch. Solution:

1. Run the script in "Nuke All" mode first to clean up existing switches
2. Or manually remove conflicting switches using Hyper-V Manager
3. Ensure no other virtual switches are using the selected adapter

"Inconsistent parameters PolicyStore PersistentStore and Dhcp Enabled"

Problem: DHCP settings conflict during IP assignment. Solution: The script handles this automatically, but if it persists:

1. Manually disable DHCP on the adapter first
2. Run the script in IP-only mode
3. Check that the adapter isn't in a transitional state

"Adapter not found after creation"

Problem: Hyper-V adapters take time to appear in the system. Solution: The script includes retry logic, but if it fails:

1. Wait 30-60 seconds after switch creation
2. Check Hyper-V Manager to verify adapters were created
3. Run in IP-only mode to assign IPs to existing adapters

"Permission denied" or "Access denied"

Problem: Script not run with administrative privileges. Solution:

1. Right-click PowerShell and select "Run as Administrator"
2. Verify you're in an elevated prompt (should show "Administrator:" in title)

Hyper-V Not Available

Problem: Hyper-V features not enabled or not supported. Solution:

1. Verify you're using Windows 10/11 Pro/Enterprise/Education
2. Enable Hyper-V in Windows Features
3. Restart computer
4. Run: Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All

"Cannot bind to adapter"

Problem: Network adapter is in use by another application or service. Solution:

1. Close applications using the adapter
2. Disable VPN clients temporarily
3. Check for conflicting virtual switches
4. Use "Nuke All" mode to clean up

IP Validation Errors

Problem: IP addresses conflict with network or broadcast addresses. Solution: The script will show detailed validation errors. Choose different IP octets that don't match:

• Network address (first usable IP in subnet)
• Broadcast address (last IP in subnet)

Script Hangs or Freezes

Problem: Long delays during adapter creation. Solution: This is normal behavior. The script includes intentional delays to ensure proper Hyper-V operation. Wait for completion - it may take 2-3 minutes for full setup.

Debug Mode

For additional troubleshooting, you can add debug output by modifying the script to show more verbose information about each step.

Getting Help

If you encounter issues not covered here:

1. Check the Issues page
2. Create a new issue with your error messages and system details
3. Include your Windows version, Hyper-V status, and script output

Reflection

What We Learned

• Deep cleanup is essential: Removing existing VLAN configurations before creating new ones prevents conflicts and ensures clean setups
• Hyper-V timing matters: Network adapters need time to initialize properly - delays are crucial for reliability
• JSON configuration is powerful: External configuration files allow facility-specific setups without code changes
• Validation prevents disasters: Subnet-aware IP checking catches configuration errors before they cause network issues
• Safety features build trust: Comprehensive warnings and confirmations prevent accidental network disruption

What We Like

• Dynamic configuration loading: No code changes needed for new facilities
• Comprehensive validation: Prevents invalid network configurations
• Multiple operation modes: Normal, IP-only, and nuke-all cover all use cases
• Detailed progress feedback: Users know exactly what's happening
• Configuration summary: Clear overview of all network settings

What We Could Do Differently

• GUI interface: Python/Tkinter wrapper to avoid PowerShell execution issues
• Configuration validation: Pre-flight checks on JSON configuration files
• Backup/restore: Save existing configurations before making changes
• Network testing: Automated connectivity verification after setup
• Logging: Comprehensive logging for troubleshooting and auditing

Current Version

v1.94 - Latest stable release with DHCP/Static IP choice and subnet-aware validation features.

Roadmap

✅ Completed Features

• Virtual switch and VLAN adapter creation with delays
• Static IP assignment with validation
• External JSON configuration loading
• Deep cleanup of existing configurations
• Nuke All mode with safety confirmations
• Subnet-aware IP validation
• Configuration summary output
• Dynamic IP prompting with defaults
• Multiple facility support (4Wall, Aeon Point, Desert, custom)
• DHCP vs Static IP configuration choice

🔄 In Progress

• Python/Tkinter GUI wrapper for PowerShell execution
• Configuration file validation
• Automated network connectivity testing

📋 Planned Features

• Export Powershell script for re-use later w/o utility
• Backup/restore functionality for network configurations
• Comprehensive logging and audit trails
• Dry-run mode for testing configurations
• Network performance monitoring
• Integration with network management tools

See the open issues for a full list of proposed features (and known issues).

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors:

License

Distributed under the UNLICENSE License. See LICENSE.txt for more information.

Contact

Joshua Fleitell - i@dubpixel.tv

Project Link: https://github.com/dubpixel/dpx_vlan_maestro

Acknowledgments

• **Everyone on the Coachella Screens Team that helped & contributed to the original notion document & scripts (tim sean & ben)

(back to top)