Configuration Blueprints - Autotest Configs

Configuration Blueprints (Autotest) is a collection of automatically tested VyOS configuration examples. Every blueprint goes through a complete automated testing lifecycle on the EVE-NG platform, which guarantees that the configuration actually works.

What Configuration Blueprints Are

Configuration Blueprints are production-ready configuration examples that:

• Are automatically tested in a real EVE-NG lab environment
• Are fully validated through a suite of automated tests
• Are updated regularly as new VyOS versions are released
• Are documented automatically based on test results
• Guarantee working behavior on the specified VyOS versions

Unlike ordinary configuration examples, blueprints are automatically verified at every stage, which delivers highly reliable configurations.

The Automated Testing Process

Each blueprint goes through the following stages:

1. Lab Creation

# Automatic lab creation on the EVE-NG server
- Load topology definition
- Create virtual routers
- Configure network links
- Configure the vyos-oobm proxy host

2. Device Configuration

# Apply configuration on each router
- SSH connection through the vyos-oobm proxy
- Apply the base configuration
- Configure network interfaces
- Configure protocols and services
- Commit and save the configuration

3. Test Execution

# Suite of automated tests
- Connectivity checks (ping, traceroute)
- Routing table validation
- Protocol state checks (BGP, OSPF)
- Service tests (DHCP, DNS, VPN)
- Firewall rule checks
- Performance tests

4. Upgrade and Retesting (Optional)

# Testing on newer versions
- Upgrade VyOS to a newer version
- Re-run all tests
- Validate configuration migration
- Check backward compatibility

5. Documentation Generation

# Automatic documentation generation
- Extract the final configuration
- Collect test results
- Create topology diagrams
- Build the markdown documentation
- Publish to docs

6. Lab Teardown

# Remove the lab (if there were no errors)
- Shut down all devices
- Delete the lab on EVE-NG
- Release resources

Available Blueprint Examples

DHCP Relay through GRE-Bridge

Scenario: DHCP relay across a GRE tunnel between network segments

Topology:

[DHCP Client] --- [VyOS Relay] === GRE Tunnel === [VyOS Server] --- [DHCP Server]
                     |                                    |
                  [Transport Network (ISP/WAN)]

Key components:

• GRETAP encapsulation for L2 connectivity
• DHCP relay agent on the client side
• DHCP server on the server side
• Transport network between the relay and the server

Use cases:

• Service Provider scenarios
• Centralized DHCP management
• DHCP over WAN/Internet
• Multi-site DHCP architectures

Tested on: VyOS 1.4-rolling-202305100734

Full DHCP Relay GRE documentation

Tunnelbroker.net (IPv6)

Scenario: IPv6 connectivity through Hurricane Electric Tunnelbroker

Topology:

[VyOS WAN Router] === IPv6-in-IPv4 Tunnel === [Tunnelbroker HE]
         |
    [IPv6 LAN]
      - Single LAN: /64 prefix
      - Multiple LANs: /48 prefix (multiple /64 subnets)

Key components:

• SIT (Simple Internet Transition) tunnel
• IPv6 addressing and routing
• Router Advertisement for the LAN
• IPv6 firewall rules

Use cases:

• IPv6 connectivity for IPv4-only providers
• Testing IPv6 in production
• Dual-stack networks
• IPv6 for home/SOHO networks

Tested on: VyOS 1.5-rolling-202401130318

Full Tunnelbroker documentation

L3VPN EVPN with VyOS

Scenario: Multi-tenant datacenter L3VPN built on EVPN

Topology:

[PE1] ---- [PE2]
  \         /
   \       /
    [PE3]

Multi-tenant VRFs:
- Blue VRF (VNI 2000)
- Red VRF (VNI 3000)
- Green VRF (VNI 4000)

Key components:

• VXLAN data plane
• BGP EVPN control plane
• VRFs for tenant isolation
• OSPF as the IGP
• Management VRF for OOB access

Use cases:

• Datacenter multi-tenancy
• Cloud service providers
• Enterprise WAN segmentation
• Network function virtualization (NFV)

Tested on: VyOS 1.4/1.5-rolling

Full L3VPN EVPN documentation

WireGuard VPN

Scenario: A modern VPN built on the WireGuard protocol

Key components:

• WireGuard interface configuration
• Public/private key management
• Peer configuration
• Routing through the VPN tunnel
• Firewall rules for the VPN

Use cases:

• Site-to-Site VPN (a faster alternative to IPsec)
• Remote Access VPN
• Container-to-container encryption
• IoT device connectivity

Tested on: VyOS 1.4/1.5-rolling

OpenVPN with LDAP

Scenario: Enterprise Remote Access VPN with LDAP authentication

Key components:

• OpenVPN server configuration
• LDAP backend integration
• Certificate management (PKI)
• Client configuration generation
• RADIUS authentication (optional)

Use cases:

• Enterprise Remote Access
• Active Directory integration
• Centralized user management
• Multi-factor authentication (MFA) ready

Tested on: VyOS 1.4/1.5-rolling

Full OpenVPN LDAP documentation

Testing Architecture

EVE-NG Platform

Configuration Blueprints use EVE-NG (Emulated Virtual Environment - Next Generation) to build virtual labs:

EVE-NG advantages:

• Emulation of a real network topology
• Support for many network operating systems (VyOS, Cisco, Juniper)
• A graphical interface for visualization
• An API for automation
• Snapshot and restore functionality

vyos-oobm Proxy Host

A dedicated out-of-band management host used for:

• SSH proxying to reach lab devices
• Running automation scripts
• Collecting logs and test results
• Coordinating test execution

Test Framework

The automated testing system includes:

# Example test case structure
class DHCPRelayGRETest:
    def setup_lab(self):
        # Create the EVE-NG lab
        pass

    def configure_devices(self):
        # Apply configurations
        pass

    def test_connectivity(self):
        # Ping tests
        assert ping(source, destination) == 0

    def test_dhcp_lease(self):
        # DHCP lease verification
        assert client.has_ip_address()

    def test_routing(self):
        # Routing table checks
        assert route_exists(destination)

    def cleanup_lab(self):
        # Remove the lab
        pass

Differences from Configuration Examples

How to Use Blueprints

1. Choose a Blueprint

Identify the scenario that matches your requirements:

• DHCP Relay GRE: Centralized DHCP over WAN
• Tunnelbroker: IPv6 connectivity
• L3VPN EVPN: Datacenter multi-tenancy
• WireGuard: A modern, fast VPN
• OpenVPN LDAP: Enterprise Remote Access

2. Check the VyOS Version

Each blueprint is tested on a specific VyOS version. Make sure your version is compatible:

show version
# Compare against "Tested on" in the blueprint documentation

3. Adapt the Configuration

Replace the parameters in the configuration with your own:

• IP addresses and subnets
• Interface names
• VNI/VLAN IDs
• AS numbers (for BGP)
• Keys and certificates

4. Apply in Stages

Apply the configuration in blocks:

configure

# Block 1: Interfaces
set interfaces ethernet eth0 address '10.0.1.1/24'
commit

# Block 2: Protocols
set protocols ospf area 0
commit

# Block 3: Services
set service dhcp-server ...
commit

save

5. Verify Each Stage

Use the verification commands from the documentation:

# Connectivity
ping 10.0.1.1

# Routing
show ip route

# Protocol status
show protocols ospf neighbor

# Service status
show dhcp server leases

6. Monitoring and Troubleshooting

If something is not working:

# Logs
show log

# Debug mode
set system syslog global facility all level debug
commit

# Packet capture
monitor traffic interface eth0

Best Practices for Blueprints

1. Version Control

Keep the configuration in Git:

# On the VyOS router
show configuration commands | save /config/backup.conf

# Copy to git repository
scp vyos@router:/config/backup.conf ./configs/
git add configs/backup.conf
git commit -m "Add VyOS config for blueprint X"

2. Testing in a Lab

Before production deployment:

• Deploy the blueprint in a test environment
• Verify every function
• Run load tests
• Validate failover scenarios

3. Documenting Changes

Maintain a changelog for the adapted configuration:

## Changes from the original blueprint

### DHCP Relay GRE Blueprint
- Changed GRE source: 10.0.10.10 → 192.168.1.1
- Changed DHCP pool: 192.168.0.0/24 → 172.16.50.0/24
- Added firewall rules for production environment

4. Monitoring in Production

Set up monitoring for key metrics:

# SNMP for monitoring
set service snmp community public authorization ro
set service snmp community public network 192.168.1.0/24

# Syslog to a centralized system
set system syslog host 192.168.1.100 facility all level info

5. Backup Strategy

# Regular configuration backup
set system task-scheduler task backup-config executable path '/config/scripts/backup.sh'
set system task-scheduler task backup-config interval '1d'

# backup.sh
#!/bin/vbash
source /opt/vyatta/etc/functions/script-template
run show configuration commands | save /config/backups/config-$(date +%Y%m%d).conf

CI/CD Integration

Blueprint configurations can be integrated into a CI/CD pipeline:

GitLab CI Example

# .gitlab-ci.yml
stages:
  - validate
  - test
  - deploy

validate_config:
  stage: validate
  script:
    - vyos-validate-config config.conf
  only:
    - branches

test_lab:
  stage: test
  script:
    - python3 run_eve_ng_test.py --blueprint dhcp-relay-gre
  only:
    - main

deploy_production:
  stage: deploy
  script:
    - ansible-playbook -i inventory vyos-deploy.yml
  when: manual
  only:
    - main

GitHub Actions Example

# .github/workflows/vyos-test.yml
name: VyOS Blueprint Test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate VyOS Config
        run: |
          docker run --rm -v $PWD:/config vyos/vyos:latest \
            /opt/vyatta/bin/vyatta-config-loader /config/blueprint.conf

Troubleshooting Blueprints

Common Issues

1. The Configuration Does Not Apply

# Check the syntax
configure
load /config/blueprint.conf
commit
# If there is an error, review the details

# Check for deprecated commands
show system commit

2. Connectivity Issues

# Interface status
show interfaces

# Routing
show ip route
show ipv6 route

# ARP/NDP
show arp
show ipv6 neighbors

# Packet capture
monitor traffic interface eth0 filter "icmp"

3. A Protocol Does Not Come Up

# BGP
show bgp summary
show bgp neighbors

# OSPF
show ip ospf neighbor
show ip ospf database

# Debug
debug bgp
debug ospf

4. A Service Does Not Work

# DHCP
show dhcp server statistics
show dhcp server leases
show log | match dhcp

# DNS
show dns forwarding statistics

# VPN
show vpn ipsec sa
show vpn wireguard

VyOS Versions and Compatibility

Blueprints are tested on specific rolling release versions:

Recommendation: Use the LTS version (VyOS 1.4 Sagitta) for production and a rolling release for testing new features.

Additional Resources

Documentation

• VyOS Configuration Examples - All configuration examples
• VyOS Official Blueprints
• EVE-NG Documentation

Tools

• VyOS Ansible Collection - Automation
• VyOS API - REST API
• Netmiko - SSH automation

Community

• VyOS Forum - Community support
• VyOS Slack - Real-time chat
• GitHub Issues - Bug reports

Conclusion

Configuration Blueprints (Autotest) provide highly reliable, automatically tested VyOS configuration examples for complex network scenarios. Using blueprints guarantees:

• Working configurations on the specified versions
• Time savings on testing and debugging
• Best practices from the VyOS developers
• Regular updates with new VyOS versions

For production deployments, we recommend using blueprints as a starting point and adapting them to your specific requirements while preserving their architectural principles.