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 provisions shadow gateways (HA) at 169.254.254.3
• 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)

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

UniFi-Specific Variables

pathvector_unifi_script_name: "01-unifi-pathvector-setup.sh"  # On-boot script name
pathvector_unifi_run_immediately: false                       # Install immediately
pathvector_unifi_autostart_services: false                    # Auto-start bird service
unifi_on_boot_version: "1.0.0"                                # Version of unifi-on-boot for shadow gateway

Note: This role requires unifi-on-boot to be installed on your UniFi devices for boot script persistence across firmware upgrades. The old udm-boot / udm-boot-2x packages from unifios-utilities do not survive firmware upgrades.

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:
   • Installs bird2 and pathvector (if needed)
   • Copies config from persistent storage to /etc/
   • Runs pathvector generate
   • Logs to /var/log/unifi-pathvector-setup.log
4. Shadow Gateway: The script automatically checks for a shadow gateway at 169.254.254.3. If found:
   • Copies itself and the config to the shadow gateway
   • Installs unifi-on-boot if missing
   • Runs the setup on the shadow gateway

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

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