autobird

A REST API for managing BIRD2 routing daemon configuration, designed for hosting providers.

Features

• Floating IPs — Route any prefix to any next-hop IP. Easily move IPs between servers or locations.
• Core Router Sessions — Define iBGP sessions to peer routers directly in the config file
• Route Reflector — Serve as the core iBGP route reflector with configurable cluster ID and per-session RR client designation
• Downstream BGP Sessions — Configure BGP sessions for customers with:
  • Per-customer ASN and allowed prefix lists
  • Strict prefix filtering with configurable min/max lengths
  • RTBH (Remotely Triggered Black Hole) support via /32 and /128 with large community
  • Optional tagging of accepted downstream routes with a configurable large community
  • BFD support
  • Import limits
• Route tagging — Optionally mark all floating routes and all accepted downstream routes with distinct large communities
• Full BIRD2 management — Owns the entire bird.conf with organized config snippets
• Graceful reload — Applies changes via birdc configure
• SQLite state — Persists all configuration in a local database

Quick Start

Install from .deb

dpkg -i autobird_*.deb

The Debian package creates /etc/autobird/autobird.yaml on first install if it is missing and keeps the evolving reference config at /usr/share/autobird/autobird.example.yaml. Package upgrades leave your live config alone instead of asking dpkg to merge it.

Configure

Edit /etc/autobird/autobird.yaml:

asn: 64512
api:
  listen: "127.0.0.1:8080"
  api_key: "your-secure-api-key"
rtbh:
  enabled: true
  community: "0:666:0"    # 0 = use own ASN
communities:
  floating: "0:100:10"    # tag all floating routes
  downstream: "200950:3:nnn"  # nnn expands to the downstream ASN

If you want the complete set of available options, copy from /usr/share/autobird/autobird.example.yaml and merge what you need into /etc/autobird/autobird.yaml.

Start

systemctl start autobird

API Reference

All endpoints require Authorization: Bearer <api_key> header.

Status

Method	Path	Description
GET	/api/v1/status	Get BIRD daemon status
POST	/api/v1/sync	Regenerate all configs from DB and reload BIRD

Floating IPs

Method	Path	Description
GET	/api/v1/floating	List all floating routes
POST	/api/v1/floating	Create a floating route
GET	/api/v1/floating/{id}	Get a floating route
PUT	/api/v1/floating/{id}	Update a floating route
DELETE	/api/v1/floating/{id}	Delete a floating route

Create/Update body:

{
  "name": "customer1-v4",
  "prefix": "203.0.113.0/24",
  "next_hop": "10.0.0.1"
}

next_hop is advertised as the BGP NEXT_HOP for the originated prefix. Autobird does not require the local RR to have direct forwarding adjacency to that address.

BGP Sessions

Method	Path	Description
GET	/api/v1/bgp/sessions	List all BGP sessions
POST	/api/v1/bgp/sessions	Create a BGP session
GET	/api/v1/bgp/sessions/{id}	Get a BGP session
PUT	/api/v1/bgp/sessions/{id}	Update a BGP session
DELETE	/api/v1/bgp/sessions/{id}	Delete a BGP session

Create/Update body:

{
  "name": "customer1",
  "peer_asn": 65001,
  "peer_ip": "10.0.0.2",
  "local_ip": "10.0.0.1",
  "ipv4": true,
  "ipv6": true,
  "bfd": true,
  "rr_client": false,
  "multihop": 0,
  "max_prefix_v4": 100,
  "max_prefix_v6": 50,
  "password": "",
  "enabled": true
}

Allowed Prefixes

Method	Path	Description
GET	/api/v1/bgp/sessions/{id}/prefixes	List allowed prefixes
POST	/api/v1/bgp/sessions/{id}/prefixes	Add an allowed prefix
DELETE	/api/v1/bgp/sessions/{id}/prefixes/{prefixID}	Remove an allowed prefix

Create body:

{
  "prefix": "203.0.113.0/24",
  "min_length": 24,
  "max_length": 24
}

min_length and max_length default to the prefix length if omitted (exact match only).

BIRD Config Structure

autobird generates the following file layout:

/etc/bird/
├── bird.conf                          # Main config (managed by autobird)
└── autobird.d/
    ├── floating/
    │   ├── float_1.conf               # Static route per floating IP
    │   └── float_2.conf
    ├── nullroute/
    │   └── null_1.conf               # Static blackhole route per nullroute
    └── bgp/
        ├── bgp_1.conf                 # BGP session + filters per customer
        └── bgp_2.conf

Generated files stay mode 0640 and directories stay 0750, but autobird assigns them to the BIRD-readable group configured in bird.read_group (default: bird). Override that value if your distribution runs BIRD under a different group.

The generated main config also keeps both protocol kernel stanzas isolated with import none and export none, so autobird does not push its routing table into the host kernel unless you add your own kernel export policy in extra_config.

Route Reflector

When cluster_id is set in the configuration, autobird operates as an iBGP route reflector. BGP sessions where the peer ASN matches the local ASN are treated as iBGP sessions with import all and an export filter that rejects directly connected interface routes (RTS_DEVICE) while still exporting reflected BGP routes and managed static objects. Sessions with rr_client: true get the rr client directive, causing the route reflector to propagate routes between clients.

Core Router Sessions (config-driven)

Define iBGP sessions to other core routers directly in the YAML config under routers:

cluster_id: "10.0.0.2"
routers:
  - name: core1
    peer_ip: "10.0.0.1"
    local_ip: "10.0.0.2"
    ipv4: true
    ipv6: true
    bfd: true
    rr_client: true
  - name: core2
    peer_ip: "10.0.0.3"
    local_ip: "10.0.0.2"
    ipv4: true
    ipv6: true
    bfd: true
    rr_client: true

These sessions are written directly into bird.conf and use import all / export all. They are not managed via the API.

API-managed iBGP Sessions

You can also create iBGP sessions through the API by setting peer_asn to match your own ASN and rr_client: true.

RTBH Support

When RTBH is enabled, downstream customers can announce /32 (IPv4) or /128 (IPv6) prefixes with the configured large community to trigger blackhole routing. The prefix must fall within one of the customer's allowed prefix ranges.

Example: if customer is allowed 203.0.113.0/24, they can send 203.0.113.5/32 with community (64512, 666, 0) to blackhole that IP.

If communities.downstream is set, autobird also adds that large community to accepted downstream routes, including accepted RTBH blackholes. For downstream communities, the third field can be nnn, which autobird expands to the downstream peer ASN. If communities.floating is set, autobird adds that large community to every floating route it originates.

Extra Configuration

Use extra_config in the YAML to add upstream BGP sessions, OSPF, or any other BIRD configuration:

extra_config: |
  protocol bgp upstream1 {
      local as 64512;
      neighbor 198.51.100.1 as 65000;
      ipv4 {
          import all;
          export where source = RTS_STATIC || source = RTS_BGP;
      };
  }

Building

make build          # Build binary
make test           # Run tests
make package        # Build .deb (requires nfpm)

License

Proprietary — Calibour Limited