# Configuration Blueprints - Autotest Configs

> Configuration Blueprints - VyOS configuration examples validated through a full EVE-NG lifecycle: lab, testing, and auto-generated documentation.

Source: https://opennix.org/en/docs/vyos/examples/vyos-blueprints/


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

```bash
# 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

```bash
# 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

```bash
# 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)

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

### 5. Documentation Generation

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

### 6. Lab Teardown

```bash
# 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](/docs/vyos/examples/dhcp-relay-gre/)

### 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](/docs/vyos/examples/tunnelbroker-ipv6/)

### 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](/docs/vyos/examples/l3vpn-evpn/)

### 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](/docs/vyos/examples/openvpn-ldap/)

## 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:

```python
# 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

| Aspect | Configuration Examples | Configuration Blueprints |
|--------|----------------------|-------------------------|
| **Testing** | Manual testing | Automated testing |
| **Verification** | Best-effort | Guaranteed working |
| **Updates** | Manual | Automatic with new VyOS releases |
| **Documentation** | Static | Auto-generated from tests |
| **VyOS versions** | Generic | Specific tested versions |
| **Complexity** | Simple to advanced | Advanced scenarios only |
| **Maintenance** | Community | Automated system |

## 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:

```bash
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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```markdown
## 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:

```bash
# 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

```bash
# 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

```yaml
# .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

```yaml
# .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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

| Blueprint | VyOS 1.4 (Sagitta) | VyOS 1.5 (Circinus) | Notes |
|-----------|-------------------|---------------------|-------|
| DHCP Relay GRE | 1.4-rolling-202305+ | 1.5-rolling-202401+ | Kea DHCP in 1.5 |
| Tunnelbroker | 1.4-rolling | 1.5-rolling-202401+ | IPv6 changes |
| L3VPN EVPN | 1.4-rolling | 1.5-rolling | FRR updates |
| WireGuard | 1.4-rolling | 1.5-rolling | Stable |
| OpenVPN LDAP | 1.4-rolling | 1.5-rolling | Stable |

**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](/docs/vyos/examples/) - All configuration examples
- [VyOS Official Blueprints](https://docs.vyos.io/en/latest/configexamples/index.html#configuration-blueprints-autotest)
- [EVE-NG Documentation](https://www.eve-ng.net/index.php/documentation/)

### Tools
- [VyOS Ansible Collection](https://galaxy.ansible.com/vyos/vyos) - Automation
- [VyOS API](https://docs.vyos.io/en/latest/automation/vyos-api.html) - REST API
- [Netmiko](https://github.com/ktbyers/netmiko) - SSH automation

### Community
- [VyOS Forum](https://forum.vyos.io/) - Community support
- [VyOS Slack](https://slack.vyos.io/) - Real-time chat
- [GitHub Issues](https://github.com/vyos/vyos-build/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.