Skip to content

Network Configuration

This guide covers BIRD (BGP routing) and WireGuard (VPN) configuration management.

BIRD Configuration

BIRD is used for BGP routing on core, IXP, and VLT servers to announce AS215011 routes.

Configuration Files

BIRD configurations are Jinja2 templates under templates/config/{group}/.../bird/:

templates/config/
├── core/coreams01/bird/bird.conf.j2      # core (applied manually — see warning below)
├── ixp/{hostname}/bird/
│   ├── bird.conf.j2
│   └── peerlab.conf.j2                    # optional, present on some IXP hosts
├── vlt/bird/bird.conf.j2                  # shared across all VLT hosts
└── shared/bird/bird.service              # systemd unit (all hosts)

Templated and rendered

BIRD configs are Jinja2 templates. make render renders them — injecting the host's IPv6 address from Terraform output, secrets, and inventory vars — into .rendered/{hostname}/bird/bird.conf. make sync-bird deploys the rendered file, never the template directly.

Update BIRD Configuration

  1. Edit the template (pick the right scope):
  2. IXP host: templates/config/ixp/{hostname}/bird/bird.conf.j2
  3. All VLT hosts: templates/config/vlt/bird/bird.conf.j2
vim templates/config/ixp/ixpams01/bird/bird.conf.j2
  1. Render and sync to the servers: 
    make sync-bird

This renders the templates and runs playbooks/sync-bird.yml against the ixp and vlt groups (prompts for your BECOME / sudo password).

!!! warning "Core BIRD is manual" sync-bird does not target coreams01. make sync-config rsyncs the rendered core config to /home/nxthdr/bird/, but applying it to /etc/bird/bird.conf and reloading is a manual step on the core host (sudo cp + sudo birdc configure).

  1. Verify the change: 
    ssh nxthdr@ams01.ixp.infra.nxthdr.dev
sudo birdc show status
sudo birdc show protocols all

BIRD Playbook Details

The sync-bird playbook (playbooks/sync-bird.yml):

  1. Creates the /etc/bird directory
  2. Copies the rendered .rendered/{hostname}/bird/bird.conf → /etc/bird/bird.conf
  3. Copies the rendered peerlab.conf if it exists
  4. Copies templates/config/shared/bird/bird.service → systemd
  5. Reloads the systemd daemon
  6. Enables and reloads the BIRD service

Target hosts: ixp, vlt (not core — see the warning above)

Common BIRD Operations

Check BIRD status: 

ssh nxthdr@ams01.core.infra.nxthdr.dev
sudo birdc show status

View BGP sessions: 

sudo birdc show protocols

View routing table: 

sudo birdc show route

Reload BIRD configuration: 

sudo birdc configure

Restart BIRD service: 

sudo systemctl restart bird

WireGuard Configuration

WireGuard VPN tunnels connect IXP servers to the core server.

Configuration Files

WireGuard configurations are Jinja2 templates under templates/config/{group}/{hostname}/wireguard/:

templates/config/
├── core/coreams01/wireguard/
│   ├── wg0.conf.j2
│   └── wg1.conf.j2
└── ixp/{hostname}/wireguard/
    └── wg0.conf.j2          # some IXP hosts also have wg1.conf.j2

Templated and rendered

WireGuard configs are Jinja2 templates (they reference keys from secrets.yml and inventory vars). make render writes them to .rendered/{hostname}/wireguard/, and make sync-wireguard deploys the rendered .conf files.

Update WireGuard Configuration

  1. Edit the template: 

    vim templates/config/core/coreams01/wireguard/wg0.conf.j2

  2. Render and sync to the servers: 

    make sync-wireguard

This renders the templates and deploys the rendered configs to the core and ixp groups (prompts for your BECOME password).

  1. Verify the tunnel: 
    ssh nxthdr@ams01.core.infra.nxthdr.dev
sudo wg show

WireGuard Playbook Details

The sync-wireguard playbook (playbooks/sync-wireguard.yml):

  1. Copies the rendered .rendered/{hostname}/wireguard/*.conf → /etc/wireguard/ (mode 0600)
  2. Restarts wg-quick@wg0.service
  3. Restarts wg-quick@wg1.service

Target hosts: core, ixp

Common WireGuard Operations

Check tunnel status: 

ssh nxthdr@ams01.core.infra.nxthdr.dev
sudo wg show

Restart WireGuard interface: 

sudo systemctl restart wg-quick@wg0

View WireGuard logs: 

sudo journalctl -u wg-quick@wg0 -f

Test connectivity through tunnel: 

ping6 <remote_tunnel_ip>

Generate WireGuard Keys

To create new WireGuard keys:

# Generate private key
wg genkey

# Generate public key from private key
echo "<private_key>" | wg pubkey

Store the private key in secrets/secrets.yml:

make edit-secrets

Add: 

wireguard_private_key_wg0: "<private_key>"

Use in config: 

PrivateKey = {{ secrets.wireguard_private_key_wg0 }}

Network Topology

Core to IXP Tunnels

┌─────────────┐                    ┌─────────────┐
│  coreams01  │◄──── WireGuard ────►│  ixpams01   │
│  (Core)     │      Tunnel         │  (IXP)      │
└─────────────┘                    └─────────────┘
      │                                    │
      │ Announces                          │ Peers with
      │ 2a06:de00:50::/44                 │ other ASes
      │                                    │
      └────────────────────────────────────┘
           Traffic flows through AS215011

Prefix Announcements

  • Core services: 2a06:de00:50::/44
  • Announced by core to IXP servers

  • IXP servers propagate to Internet via BGP

  • Probing infrastructure: 2a0e:97c0:8a0::/44

  • Announced by VLT servers
  • Enables unicast/anycast measurements

Firewall Configuration

Docker Firewall Rules

By default, Docker networks are isolated. To allow external access:

ssh nxthdr@ams01.core.infra.nxthdr.dev
sudo ip6tables -I DOCKER-USER -d 2a06:de00:50:cafe:100::/80 -j ACCEPT

This allows traffic to the DMZ network.

Manual Configuration

This firewall rule is not managed by the infrastructure code and must be applied manually.

View Current Rules

ssh nxthdr@ams01.core.infra.nxthdr.dev
sudo ip6tables -L DOCKER-USER -n -v

Troubleshooting

BIRD Not Starting

Check logs: 

sudo journalctl -u bird -n 50

Common issues: - Syntax error in config: sudo bird -p -c /etc/bird/bird.conf - Port already in use: sudo netstat -tulpn | grep 179 - Missing dependencies: sudo apt install bird2

WireGuard Tunnel Down

Check interface status: 

sudo wg show
sudo ip link show wg0

Common issues: - Firewall blocking UDP port: sudo ufw allow 51820/udp - Incorrect endpoint: Check Endpoint in config - Key mismatch: Verify public/private key pairs

Restart tunnel: 

sudo systemctl restart wg-quick@wg0

BGP Session Not Establishing

Check BIRD logs: 

sudo birdc show protocols all peer_name

Common issues: - Incorrect neighbor IP - AS number mismatch - Firewall blocking TCP port 179 - Peer not configured on remote side

Test connectivity: 

ping6 <peer_ipv6>
telnet <peer_ipv6> 179

Routes Not Propagating

Check export filters: 

sudo birdc show route export peer_name

Verify static routes: 

sudo birdc show route protocol static_routes

Check kernel routing table: 

ip -6 route show

Best Practices

  1. Test BIRD config syntax before deploying: 

    sudo bird -p -c /etc/bird/bird.conf

  2. Monitor BGP sessions after changes: 

    sudo birdc show protocols

  3. Keep WireGuard keys secure in Ansible Vault

  4. Document peering arrangements in comments

  5. Use BGP communities for route tagging and filtering

  6. Set up monitoring for tunnel and BGP session status

Next Steps