ansible-role-pathvector

An Ansible role to install and configure Pathvector & Bird (Bird2 or Bird3) from official CZ.NIC repositories with automatic UniFi detection and support.

Features

• Installs Bird2 or Bird3 from official CZ.NIC repositories
• Automatic OS detection (Debian/Ubuntu) with proper repository configuration
• Automatic detection of UniFi vs standard Debian systems
• Persistent UniFi on-boot scripts that survive firmware updates (via unifi-on-boot)
• Shadow Gateway Support: Automatically handled by unifi-on-boot (v1.1.0+) which syncs all /data/on_boot.d/ scripts to the shadow gateway
• Cron Mode: Ensures services are running and enabled without full re-installation
• Standard APT installation for Debian/Ubuntu systems
• BGP AS-path prepend optimization script
• Support for mixed infrastructure (UniFi + Debian in same playbook)
• Config validation: Validates Bird configuration after generation
• Deploy-only mode: Deploy configuration without installing packages

Requirements

• Supported Systems:
  • Debian 11 (Bullseye), 12 (Bookworm)
  • Ubuntu 22.04 (Jammy), 24.04 (Noble)
  • UniFi devices with 2.x-5.x firmware and unifi-on-boot installed for /data/on_boot.d/ support
• Ansible: 2.9+
• Python: 3.6+ (with requests, ipaddress, ruamel.yaml for prepend script)

Installation

ansible-galaxy role install unredacted.pathvector

Quick Start

Basic Usage

---
- hosts: routers
  become: yes
  roles:
    - unredacted.pathvector

The role automatically detects if it's running on a UniFi system or standard Debian/Ubuntu.

Configuration Files

Place your Pathvector configuration files in your playbook's files/ directory:

playbook/
└── files/
    ├── router1.yml
    ├── router2.yml
    └── unifi-gateway.yml

Files should be named after the inventory hostname (e.g., router1.yml for host router1).

Example Configuration

# files/router1.yml
asn: 65001
router-id: 192.168.1.1

source4: 203.0.113.1
source6: 2001:db8::1

prefixes:
  - 203.0.113.0/24
  - 2001:db8::/32

rtr-server: rtr.rpki.cloudflare.com:8282

templates:
  upstream:
    interpret-communities: true
    filter-max-prefix: true
    filter-rpki: true
    filter-bogon-routes: true
    filter-bogon-asns: true

peers:
  cogent:
    asn: 174
    template: upstream
    neighbors:
      - 38.140.0.1
      - 2001:550:1::1

Role Variables

Bird Configuration

bird_version: "bird2"                          # Choose "bird2" or "bird3"
bird_install_from_official: true               # Install from CZ.NIC official repos
bird_gpg_key_url: "https://pkg.labs.nic.cz/gpg"  # CZ.NIC GPG key URL

Common Variables

pathvector_config_path: "/etc/pathvector.yml"  # Config destination
pathvector_debug: false                        # Enable debug output
pathvector_run_script: false                   # Run prepend optimization
pathvector_script_flags: ""                    # Prepend script flags
pathvector_deploy_only: false                  # Deploy config only (skip install)
pathvector_skip_install: false                 # Skip package install (repos still configured)

UniFi-Specific Variables

pathvector_unifi_script_name: "20-unifi-pathvector-setup.sh"  # On-boot script name
pathvector_unifi_run_immediately: false                       # Install immediately
pathvector_unifi_autostart_services: false                    # Auto-start bird service

Note: This role requires unifi-on-boot (v1.1.0+) to be installed on your UniFi devices. The on-boot script will check for this dependency and exit with an error if not found. Shadow gateway sync is handled automatically by unifi-on-boot.

Repository Configuration

pathvector_pgp_key_url: "https://repo.pathvector.io/pgp.asc"
pathvector_repo_url: "https://repo.pathvector.io/apt/"
pathvector_repo_dist: "stable"
pathvector_repo_component: "main"

Repository Sources

• Bird: Official CZ.NIC Labs packages from https://pkg.labs.nic.cz/
  • GPG Key fingerprint: 9C71 D59C D4CE 8BD2 966A 7A3E AB6A 3031 2401 9B64
• Pathvector: Official packages from https://repo.pathvector.io/

How It Works

For UniFi Systems

1. Deploys a persistent on-boot script to /data/on_boot.d/
2. Copies your configuration to /data/on_boot.d/pathvector.yml
3. On boot, the script:
   • Verifies unifi-on-boot is installed (exits with error if not)
   • Installs bird2 and pathvector (if needed)
   • Copies config from persistent storage to /etc/ (only if changed, using SHA256 checksums)
   • Runs pathvector generate
   • Validates the generated Bird configuration with bird -p
   • Triggers unifi-on-boot to sync to shadow gateway
   • Logs to /var/log/unifi-pathvector-setup.log

Shadow Gateway

Shadow gateway sync is handled by unifi-on-boot (v1.1.0+), which automatically rsync --deletes the entire /data/on_boot.d/ directory to the shadow gateway at 169.254.254.3 after running all scripts. This ensures the shadow has an identical set of scripts and configurations.

Cron Mode

The script supports a --cron flag which is lighter weight:

• Checks if Bird is running and enabled
• Restarts/Enables if necessary
• Does NOT attempt to install packages or modify config
• Useful for periodic health checks

For Debian/Ubuntu Systems

1. Adds CZ.NIC official Bird repository (configures based on OS release)
2. Adds Pathvector repository
3. Installs chosen Bird version (bird2 or bird3) and pathvector packages
4. Deploys configuration to /etc/pathvector.yml
5. Starts and enables bird service

Advanced Usage

Install Bird3 instead of Bird2

- hosts: routers
  become: yes
  roles:
    - unredacted.pathvector
  vars:
    bird_version: "bird3"

Use Distribution's Bird Package

- hosts: routers
  become: yes
  roles:
    - unredacted.pathvector
  vars:
    bird_install_from_official: false  # Will use distro's bird2 package

Run Installation Immediately on UniFi

- hosts: unifi_devices
  become: yes
  roles:
    - unredacted.pathvector
  vars:
    pathvector_unifi_run_immediately: true
    pathvector_unifi_autostart_services: true

Deploy Config Only (Skip Package Install)

- hosts: routers
  become: yes
  roles:
    - unredacted.pathvector
  vars:
    pathvector_deploy_only: true

Enable Prepend Optimization

- hosts: routers
  become: yes
  roles:
    - unredacted.pathvector
  vars:
    pathvector_run_script: true
    pathvector_script_flags: "--prepends 2,1,0 --ignore router1.yml"

Mixed Infrastructure

# Works automatically with both UniFi and Debian hosts
- hosts: all_routers
  become: yes
  roles:
    - unredacted.pathvector

Troubleshooting

Enable Debug Mode

pathvector_debug: true

License

GPL-3.0

Author

Zach - Unredacted