Bird-lg-go

An alternative implementation for bird-lg written in Go. Both frontend and backend (proxy) are implemented, and can work with either the original Python implementation or the Go implementation.

The code on master branch no longer support BIRDv1. Branch "bird1" is the last version that supports BIRDv1.

Table of Contents

• Bird-lg-go
  • Table of Contents
  • Build Instructions
    • Build Docker Images
  • Frontend
  • Proxy
  • Advanced Features
    • Display names
    • IP addresses
    • API
    • Telegram Bot Webhook
  • Credits
  • License

Build Instructions

You need to have Go 1.16 or newer installed on your machine.

Run make to build binaries for both the frontend and the proxy.

Optionally run make install to install them to /usr/local/bin (bird-lg-go and bird-lgproxy-go).

Build Docker Images

Use the Dockerfiles in frontend and proxy directory.

Ready-to-use images are available at:

• Frontend: https://hub.docker.com/r/xddxdd/bird-lg-go
• Proxy: https://hub.docker.com/r/xddxdd/bird-lgproxy-go

Frontend

The frontend directory contains the code for the web frontend, where users see BGP states, do traceroutes and whois, etc. It's a replacement for "lg.py" in original bird-lg project.

Features implemented:

• Show peering status (show protocol command)
• Query route (show route for ..., show route where net ~ [ ... ])
• Whois and traceroute
• Work with both Python proxy (lgproxy.py) and Go proxy (proxy dir of this project)
• Visualize AS paths as picture (bgpmap feature)

Configuration can be set in:

• bird-lg.[json/yaml/etc] in current directory
• /etc/bird-lg/bird-lg.[json/yaml/etc]
• Commandline parameter
• Environment variables

Configuration is handled by viper, any config format supported by it can be used.

Config Key	Parameter	Environment Variable	Description
servers	--servers	BIRDLG_SERVERS	server name prefixes, separated by comma
domain	--domain	BIRDLG_DOMAIN	server name domain suffixes
listen	--listen	BIRDLG_LISTEN	address bird-lg is listening on (default "5000")
proxy_port	--proxy-port	BIRDLG_PROXY_PORT	port bird-lgproxy is running on (default 8000)
whois	--whois	BIRDLG_WHOIS	whois server for queries (default "whois.verisign-grs.com"). Start with "/" to specify a local whois binary (e.g. "/usr/local/bin/whois").
dns_interface	--dns-interface	BIRDLG_DNS_INTERFACE	dns zone to query ASN information (default "asn.cymru.com")
bgpmap_info	--bgpmap-info	BIRDLG_BGPMAP_INFO	the infos displayed in bgpmap, separated by comma, start with : means allow multiline (default "asn,as-name,ASName,descr")
title_brand	--title-brand	BIRDLG_TITLE_BRAND	prefix of page titles in browser tabs (default "Bird-lg Go")
navbar_brand	--navbar-brand	BIRDLG_NAVBAR_BRAND	brand to show in the navigation bar (default same as title_brand)
navbar_brand_url	--navbar-brand-url	BIRDLG_NAVBAR_BRAND_URL	the url of the brand to show in the navigation bar (default "/")
navbar_all_servers	--navbar-all-servers	BIRDLG_NAVBAR_ALL_SERVERS	the text of "All servers" button in the navigation bar (default "All Servers")
navbar_all_url	--navbar-all-url	BIRDLG_NAVBAR_ALL_URL	the URL of "All servers" button (default "all")
net_specific_mode	--net-specific-mode	BIRDLG_NET_SPECIFIC_MODE	apply network-specific changes for some networks, use "dn42" for BIRD in dn42 network
protocol_filter	--protocol-filter	BIRDLG_PROTOCOL_FILTER	protocol types to show in summary tables (comma separated list); defaults to all if not set
name_filter	--name-filter	BIRDLG_NAME_FILTER	protocol name regex to hide in summary tables (RE2 syntax); defaults to none if not set
timeout	--time-out	BIRDLG_TIMEOUT	time before backend HTTP request times out, in seconds (default 120)
connection_timeout	--connection-time-out	BIRDLG_CONNECTION_TIMEOUT	time before backend TCP connection times out, in seconds (default 5)
trust_proxy_headers	--trust-proxy-headers	BIRDLG_TRUST_PROXY_HEADERS	trust X-Forwarded-For, X-Real-IP, X-Forwarded-Proto and X-Forwarded-Host headers sent by a reverse proxy (default false)
vrf	--vrf	BIRDLG_VRF	VRF device to bind TCP sockets to (Linux only)

Examples

Example: the following command starts the frontend with 2 BIRD nodes, with domain name "gigsgigscloud.dn42.lantian.pub" and "hostdare.dn42.lantian.pub", and proxies are running on port 8000 on both nodes.

./frontend --servers=gigsgigscloud,hostdare --domain=dn42.lantian.pub --proxy-port=8000

Example: the following docker-compose.yml entry does the same as above, but by starting a Docker container:

services:
  bird-lg:
    # Use xddxdd/bird-lg-go:develop for the latest build from master branch
    image: xddxdd/bird-lg-go:latest
    container_name: bird-lg
    restart: always
    environment:
      - BIRDLG_SERVERS=gigsgigscloud,hostdare
      - BIRDLG_DOMAIN=dn42.lantian.pub
    ports:
      - "5000:5000"

Demo: https://lg.lantian.pub

Proxy

The proxy directory contains the code for the "proxy" for bird commands and traceroutes. It's a replacement for "lgproxy.py" in original bird-lg project.

Features implemented:

• Sending queries to BIRD
• Sending "restrict" command to BIRD to prevent unauthorized changes
• Executing traceroute command on Linux, FreeBSD and OpenBSD
• Source IP restriction

Configuration can be set in:

• bird-lgproxy.[json/yaml/etc] in current directory
• /etc/bird-lg/bird-lgproxy.[json/yaml/etc]
• Commandline parameter
• Environment variables

Configuration is handled by viper, any config format supported by it can be used.

Config Key	Parameter	Environment Variable	Description
bird_socket	--bird	BIRD_SOCKET	socket file for bird (default "/var/run/bird/bird.ctl")
bird_restrict_cmds	--bird-restrict-cmds	BIRDLG_BIRD_RESTRICT_CMDS	restrict bird commands to show protocols and show route only (default true)
listen	--listen	BIRDLG_LISTEN / BIRDLG_PROXY_PORT	listen address (default "8000")
allowed_ips	--allowed	ALLOWED_IPS	IPs or networks allowed to access this proxy, separated by commas; allow all if not set
traceroute_bin	--traceroute-bin	BIRDLG_TRACEROUTE_BIN	traceroute binary file
traceroute_flags	--traceroute-flags	BIRDLG_TRACEROUTE_FLAGS	traceroute flags, supports multiple flags separated with space
traceroute_raw	--traceroute-raw	BIRDLG_TRACEROUTE_RAW	whether to display traceroute outputs raw (default false)
traceroute_max_concurrent	--traceroute-max-concurrent	BIRDLG_TRACEROUTE_MAX_CONCURRENT	max concurrent traceroute requests allowed (default 10)
vrf	--vrf	BIRDLG_VRF	VRF device to bind TCP sockets to (Linux only)

Traceroute Binary Autodetection

If traceroute_bin or traceroute_flags is not set, then on startup, the proxy will try to traceroute 127.0.0.1 with different traceroute binaries and arguments, in order to use the most optimized setting available, while maintaining compatibility with multiple variants of traceroute binaries.

Traceroute binaries will be autodetected in the following order:

1. If traceroute_bin is set:
   1. [traceroute_bin] -q1 -N32 -w1 127.0.0.1 (Corresponds to Traceroute on Debian)
   2. [traceroute_bin] -q1 -w1 127.0.0.1 (Corresponds to Traceroute on FreeBSD)
   3. [traceroute_bin] 127.0.0.1 (Corresponds to Busybox Traceroute)
2. mtr -w -c1 -Z1 -G1 -b 127.0.0.1 (MTR)
3. traceroute -q1 -N32 -w1 127.0.0.1 (Corresponds to Traceroute on Debian)
4. traceroute -q1 -w1 127.0.0.1 (Corresponds to Traceroute on FreeBSD)
5. traceroute 127.0.0.1 (Corresponds to Busybox Traceroute)

Examples

Example: start proxy with default configuration, should work "out of the box" on Debian 9 with BIRDv1:

./proxy

Example: start proxy with custom bird socket location:

./proxy --bird /run/bird.ctl

Example: the following docker-compose.yml entry does the same as above, but by starting a Docker container:

services:
  bird-lgproxy:
    # Use xddxdd/bird-lgproxy-go:develop for the latest build from master branch
    # Use xddxdd/bird-lgproxy-go:latest-mtr to use MTR instead of Traceroute
    image: xddxdd/bird-lgproxy-go:latest
    container_name: bird-lgproxy
    restart: always
    volumes:
      - "/run/bird.ctl:/var/run/bird/bird.ctl"
    ports:
      - "192.168.0.1:8000:8000"

You can use source IP restriction to increase security. You should also bind the proxy to a specific interface and use an external firewall/iptables for added security.

Advanced Features

Display names

The server parameter is composed of server name prefixes, separated by comma. It also supports an extended syntax: It allows to define display names for the user interface that are different from the actual server names.

For instance, the two servers from the basic example can be displayed as "Gigs" and "Hostdare" using the following syntax (as known from email addresses):

./frontend --servers="Gigs<gigsgigscloud>,Hostdare<hostdare>" --domain=dn42.lantian.pub

IP addresses

You may also specify IP addresses as server names when no domain is specified. IPv6 link local addresses are supported, too.

For example:

./frontend --servers="Prod<prod.mydomain.local>,Test1<fd88:dead:beef::1>,Test2<fe80::c%wg0>" --domain=

These three servers are displayed as "Prod", "Test1" and "Test2" in the user interface.

API

The frontend provides an API for running BIRD/traceroute/whois queries.

See API docs for detailed information.

Telegram Bot Webhook

The frontend can act as a Telegram Bot webhook endpoint, to add BGP route/traceroute/whois lookup functionality to your tech group.

See Telegram docs for detailed information.

Credits

• Everyone who contributed to this project (see Contributors section on the right)
• Mehdi Abaakouk for creating the original bird-lg project
• Bootstrap as web UI framework

License

GPL 3.0