Al
Networking Azure

Alice-LG on Ubuntu 24.04 on Azure User Guide

| Product: Alice-LG on Ubuntu 24.04 LTS on Azure

Overview

Alice-LG is the looking glass that internet exchanges and network operators put in front of their route servers. It turns raw BGP state into a browser interface where anyone can search a prefix, open a neighbour, and read exactly what that peer announced, what was accepted, what was rejected and why, complete with AS paths, next hops and BGP communities.

Alice-LG is a frontend only. It speaks HTTP to a backend API rather than BGP itself, which means an Alice-LG installed on its own has nothing to display. The cloudimg image solves that by shipping the whole looking glass stack on one VM: Alice-LG, the birdwatcher API it consumes, and a BIRD 2 route server for birdwatcher to read, wired to a small self contained demo topology. The result is an appliance whose interface is already showing a real BGP neighbour, real accepted prefixes and real filtered prefixes the moment first boot finishes, so you can confirm the product works before you point it at production. Repointing it at your own route servers is a configuration change, covered in Step 9.

Alice-LG has no user accounts of its own, and a looking glass discloses routing topology, so the image puts nginx in front of it with HTTP Basic Auth and a unique password generated on the first boot of your VM. Backed by 24/7 cloudimg support.

What is included:

  • Alice-LG 6.2.0 built from the pinned upstream release tag, running as the alice-lg systemd service with its React frontend compiled into the binary
  • birdwatcher 2.2.5, the HTTP API that translates BIRD state into JSON for Alice-LG, bound to loopback only
  • BIRD 2.14 from the Ubuntu archive, acting as the demo route server whose state the looking glass renders
  • A second BIRD 2 instance in its own network namespace, peered with the route server over a private link, so the looking glass has a real BGP neighbour and real prefixes on day one
  • An import policy that deliberately rejects some of those prefixes, with human readable rejection reasons, so the Filtered view is populated too
  • nginx on port 80 with per VM HTTP Basic Auth (user alice) protecting the whole interface and API
  • Alice-LG on 127.0.0.1:7340 and birdwatcher on 127.0.0.1:29184, never exposed to the network directly
  • An unauthenticated /healthz endpoint for Azure Load Balancer health probes
  • A dependency licence report shipped in the image at /usr/share/doc/cloudimg-alice-lg/DEPENDENCY-LICENCES.txt
  • 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point; Alice-LG is light on resources and scales with the number of route servers and the size of their tables. NSG inbound: allow 22/tcp from your management network and 80/tcp from wherever your operators browse from. Add 443/tcp once you put your own domain and TLS certificate in front (see Step 10). A looking glass exposes routing topology, so treat port 80 as sensitive and restrict it to trusted ranges.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Alice-LG by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create and Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name alice-lg \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name alice-lg --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the looking glass stack is running

The appliance is a chain: nginx terminates the browser connection and applies the password gate, Alice-LG renders the interface, birdwatcher turns BIRD state into JSON, and BIRD holds the routing table. All four have to be up.

systemctl is-active bird.service cloudimg-bird-demo-peer.service birdwatcher.service alice-lg.service nginx.service

Every line reports active. You can also confirm the binding posture: only nginx is on a routable address, and BGP is confined to the private demo link.

ss -tln | grep -E ':(80|179|7340|29184)'

Alice-LG shows on 127.0.0.1:7340 and birdwatcher on 127.0.0.1:29184, both loopback only. BGP shows on 10.255.0.1:179, which is the private link inside this VM, never a public address. Only port 80 is bound on 0.0.0.0.

The bird, demo peer, birdwatcher, alice-lg and nginx services all active, with Alice-LG and birdwatcher bound to loopback and BGP confined to the private demo link

Step 5 - Retrieve your looking glass password

Alice-LG has no login of its own, so nginx protects it with HTTP Basic Auth. The username is alice and a unique password is generated on the first boot of your VM and written to a root only file:

sudo cat /root/alice-lg-credentials.txt

The file gives you the URL, the username and the password. No credential of any kind ships inside the image, so this password exists only on your VM.

Step 6 - Sign in to the looking glass

Open the ALICE_LG_URL from the previous step in a browser, or simply http://<vm-public-ip>/. Your browser prompts for the HTTP Basic Auth credentials; enter alice and the password you just read.

The landing page lists the route servers this looking glass knows about, with the BIRD version each one is running.

The Alice-LG landing page listing the bundled demo route server and the BIRD version it reports

You can prove the gate from the shell before you open a browser. Without credentials the interface returns 401, and with the per VM password it returns 200:

curl -s -o /dev/null -w 'no credentials: %{http_code}\n' http://127.0.0.1/

curl -s -o /dev/null -w 'with password: %{http_code}\n' -u 'alice:<ALICE_LG_PASSWORD>' http://127.0.0.1/

The credentials file with the password masked, the Basic Auth gate returning 401 without credentials and 200 with the per VM password, and the looking glass API reporting the live neighbour

Step 7 - Read the route server and its neighbours

Select the route server in the left hand column. Alice-LG shows every BGP session, its state, how long it has been up, and how many routes it received and filtered. The bundled demo peer appears here as AS 65001 in state up.

The Alice-LG neighbours view showing the demo BGP session established with AS 65001, its uptime, and its received and filtered route counters

The same information is available from the shell, straight out of BIRD:

sudo birdc show protocols demo_peer_as65001

The session reports Established. The routes it carried are in the route server's table:

sudo birdc show route protocol demo_peer_as65001

The demo BGP session reporting Established, and the three documentation prefixes the route server accepted from it

Step 8 - Read accepted and filtered routes

Click the neighbour to open its routes. This is the view operators live in: Alice-LG shows the prefixes the peer announced, splits them into accepted and filtered, and for each filtered prefix explains why it was rejected. The reasons come from BGP large communities that the route server's import policy attaches, which Alice-LG resolves into readable text.

The Alice-LG routes view showing three filtered prefixes with their rejection reasons above three accepted prefixes, each with AS path, gateway and interface

The accepted routes table showing the three documentation prefixes the demo peer announced, with AS path 65001 and their next hop

The filtered set is equally visible from the shell:

sudo birdc show route filtered protocol demo_peer_as65001

The rejected prefixes held by the route server, and the private link plus network namespace the demo session runs over

The global search box at the top searches every route server at once, which is how an operator answers "is my prefix visible here" in one step.

The Alice-LG global prefix search returning the announcing neighbour and route server for a searched prefix

You can drive the same query from the API, which is useful for monitoring:

curl -sS -u 'alice:<ALICE_LG_PASSWORD>' -w '\nHTTP %{http_code}\n' 'http://127.0.0.1/api/v1/routeservers'

A correct credential returns the route server list and HTTP 200; a wrong one returns HTTP 401 and no data, which is the same gate your browser hits.

Step 9 - Point Alice-LG at your own route servers

The bundled demo topology exists so the appliance proves itself on day one. In production you point Alice-LG at your real route servers instead. Each route server needs a backend API that Alice-LG can read: birdwatcher for BIRD, or the GoBGP and OpenBGPD backends Alice-LG also supports.

Alice-LG's configuration lives in one file:

sudo cat /etc/alice-lg/alice.conf

Each route server is a pair of sections. Add one pair per route server, pointing api at that route server's birdwatcher endpoint, and remove or keep the bundled demo-rs-v4 source as you prefer:

[source.rs1-lon]
name = rs1.lon.example.net (IPv4)
group = LON

[source.rs1-lon.birdwatcher]
api = http://rs1.lon.example.net:29184/
type = single_table
main_table = master4

Set type to match how that route server's BIRD is configured: single_table for a single table configuration, which is what arouteserver generates, or multi_table if each peer has its own table. Then restart Alice-LG:

sudo systemctl restart alice-lg.service

Confirm it came back and is serving:

systemctl is-active alice-lg.service

If a new route server does not appear, check that its birdwatcher endpoint is reachable from this VM and that the routes_table_filtered and routes_filtered modules are enabled in that birdwatcher's configuration, otherwise the Filtered view stays empty.

Once you are reading your own route servers, and only then, you can stop the bundled demo topology. Run this after your own sources are confirmed working, because it removes the local route server that the demo-rs-v4 source reads:

sudo systemctl disable --now cloudimg-bird-demo-peer.service bird.service birdwatcher.service

Remove the [source.demo-rs-v4] sections from /etc/alice-lg/alice.conf at the same time, then restart Alice-LG, otherwise the interface keeps a route server entry it can no longer reach.

Step 10 - Add your own domain and TLS

The image serves plain HTTP on port 80 behind the password gate. For anything reachable beyond a trusted management network, terminate TLS with your own certificate. Point a DNS record at the VM, obtain a certificate, and add a 443 server block to /etc/nginx/sites-available/cloudimg-alice-lg that proxies to the same http://alice_lg upstream and keeps the auth_basic lines. Test and reload:

sudo nginx -t

Many operators also swap the Basic Auth gate for their existing SSO by putting an authenticating proxy in front. Whatever you choose, do not remove the gate and expose Alice-LG directly: it has no authentication of its own, and the interface reveals your peering topology.

Server Components

Component Version Purpose
Alice-LG 6.2.0 The looking glass web interface and its JSON API
birdwatcher 2.2.5 HTTP API that turns BIRD state into JSON for Alice-LG
BIRD 2.14 The routing daemon whose state is displayed
nginx 1.24 Reverse proxy and per VM HTTP Basic Auth gate
Ubuntu 24.04 LTS Base operating system

Filesystem Layout

Path Purpose
/usr/local/bin/alice-lg The Alice-LG binary, with the frontend compiled in
/usr/local/bin/birdwatcher The birdwatcher API binary
/etc/alice-lg/alice.conf Alice-LG configuration, including the route server sources
/etc/birdwatcher/birdwatcher.conf birdwatcher configuration
/etc/bird/bird.conf The demo route server's BIRD configuration
/etc/bird/cloudimg-demo-peer.conf The demo BGP peer's BIRD configuration
/etc/nginx/sites-available/cloudimg-alice-lg The nginx site, including the auth gate
/etc/nginx/snippets/cloudimg-alice-lg-listen.conf The nginx listener, opened at first boot
/root/alice-lg-credentials.txt Per VM URL, username and password (root only)
/usr/share/doc/cloudimg-alice-lg/DEPENDENCY-LICENCES.txt Dependency licence report

Managing the services

systemctl status alice-lg.service --no-pager

Restart the interface after a configuration change with sudo systemctl restart alice-lg.service. birdwatcher and BIRD are managed the same way. BIRD also accepts a live reconfiguration without dropping sessions:

sudo birdc configure

On startup

alice-lg-firstboot.service runs once on the first boot of your VM. It waits for the looking glass to be serving real route data, generates the per VM Basic Auth password, writes it to /root/alice-lg-credentials.txt, opens the nginx listener on port 80, and then proves the whole path end to end before writing its sentinel at /var/lib/cloudimg/alice-lg-firstboot.done. Until it has run, nginx listens on loopback only and holds an empty password file, so the image cannot serve anyone and no credential ships inside it.

cloudimg-lg-fabric.service recreates the private link and network namespace that the demo BGP session runs over. It runs on every boot and holds no state.

Backups

Alice-LG is a viewer over live route server APIs, so there is no application database to back up. What is worth keeping is your configuration:

sudo tar czf ~/alice-lg-config-backup.tar.gz /etc/alice-lg/alice.conf /etc/bird

Do not add /root/alice-lg-credentials.txt or /etc/nginx/.alice-lg.htpasswd to a backup archive. Both hold this VM's password, they are regenerated per VM rather than restored, and copying them creates a credential bearing file outside the paths that protect the originals.

Troubleshooting

The browser asks for a password and never accepts it. Confirm the username is alice and re read the password with sudo cat /root/alice-lg-credentials.txt. The password is unique to the VM and is not recoverable from anywhere else; if it has been lost, regenerate it by removing /var/lib/cloudimg/alice-lg-firstboot.done and sudo systemctl start alice-lg-firstboot.service.

The interface loads but shows no route servers. Check systemctl is-active alice-lg.service birdwatcher.service. If birdwatcher is down, Alice-LG has no data source. Check sudo journalctl -u birdwatcher.service -n 40 --no-pager.

A route server appears but its neighbours list is empty. That route server's birdwatcher can reach BIRD but no BGP session is up on it. Verify with sudo birdc show protocols on that route server.

Routes appear with no prefix. birdwatcher parses BIRD's text output, so a route server whose BIRD prints sub second timestamps produces routes birdwatcher cannot fully parse. Set timeformat route "%Y-%m-%d %H:%M:%S"; in that BIRD's configuration, as the bundled demo route server does.

The Filtered tab is always empty for your own route server. BIRD only keeps rejected routes when the channel sets import keep filtered on;, and birdwatcher only exposes them when the routes_filtered and routes_table_filtered modules are enabled.

Security recommendations

  • Keep the HTTP Basic Auth gate. Alice-LG has no authentication of its own, and the interface reveals your peering topology, your members and their prefixes.
  • Restrict port 80 in the NSG to the networks your operators browse from, and put TLS in front before exposing it more widely.
  • Leave Alice-LG and birdwatcher on loopback. They are reachable only through nginx by design; exposing birdwatcher would hand out route server state with no authentication at all.
  • Rotate the Basic Auth password by regenerating /etc/nginx/.alice-lg.htpasswd with htpasswd, and keep /root/alice-lg-credentials.txt root only.
  • Unattended security upgrades are enabled on the base image and continue to run on your VM.

Support

cloudimg provides 24/7 support for this image. Contact support@cloudimg.co.uk or visit www.cloudimg.co.uk.

Alice-LG and birdwatcher are open source projects of the Alice-LG community, distributed under the BSD 3 Clause licence. BIRD is a project of CZ.NIC, distributed under the GNU General Public License version 2. cloudimg is not affiliated with, endorsed by, or sponsored by the Alice-LG project or CZ.NIC. All trademarks are the property of their respective owners.