BGPalerter on Ubuntu 24.04 on Azure User Guide

Overview

BGPalerter is a self hosted, open source BGP and RPKI monitoring and alerting daemon from NTT. It connects to the real time BGP stream and continuously watches your prefixes and autonomous systems for visibility loss, prefix hijacks, unexpected more specific announcements, RPKI invalid routes and ROA misconfiguration, so you learn about a routing incident affecting your network in minutes rather than hours. Alerts are delivered through simple reports to a rotating log file, email, Slack, syslog, HTTP webhooks, Kafka and more, all driven by plain YAML configuration.

The cloudimg image installs the official BGPalerter binary at /usr/local/bin/bgpalerter, running as the bgpalerter service with its built in REST status API bound to loopback 127.0.0.1:8011, behind nginx on port 80. nginx is ready for your TLS certificate.

Secure by default, no default login: BGPalerter's status API ships with no authentication of its own. This image never exposes it unauthenticated. The daemon binds the API to loopback only and it is served through nginx: GET /health is an unauthenticated liveness endpoint for load balancer probes, while /status and every other path require HTTP Basic Auth (username cloudimg). A bgpalerter-firstboot.service oneshot generates a unique password on each VM's first boot, writes it to a root only file and to an nginx htpasswd, resolves the instance URL and writes a root only info note, then disables itself. No two VMs share a password and none is baked into the image.

Always current: on first boot the appliance downloads the newest BGPalerter release binary (falling back to the baked version if the network is unavailable), so every launch runs current software rather than the version frozen at build time.

Note on the interface: BGPalerter is a headless daemon. It has no web UI; you drive it through its REST status API and its YAML configuration files (config.yml and prefixes.yml), and it emits alerts through the reports you enable. This guide uses curl against the status API and edits the YAML files directly.

What is included:

• BGPalerter (verified at 2.0.1) as the official self contained binary
• bgpalerter.service with its REST status API bound to 127.0.0.1:8011
• nginx reverse proxy on port 80: public /health, password protected /status
• bgpalerter-firstboot.service for the first boot password, binary refresh and info note
• A unique per VM status API password generated on first boot, in a root only 0600 file
• Ubuntu 24.04 LTS base, fully patched
• 24/7 cloudimg support, 24h response SLA

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet with a subnet. BGPalerter is lightweight and CPU friendly. Recommended VM size: Standard_B2s (2 vCPU, 4 GB RAM) is sufficient for most networks; use a larger size only if you monitor a very large number of prefixes. BGPalerter needs outbound access to the RIPE RIS live stream (wss://ris-live.ripe.net) to receive BGP data, so allow outbound HTTPS/WSS from the VM.

Step 1: Deploy from the Azure Portal

Search the Marketplace for BGPalerter on Ubuntu 24.04, choose your VM size, and attach an NSG that allows TCP 22 (SSH) from your management network and TCP 80 / 443 (the status API) from the networks that need to query it. Front port 80 with TLS in production (see the HTTPS section below). No inbound port is required for BGPalerter to monitor: it makes an outbound connection to the BGP data stream.

Step 2: Deploy from the Azure CLI

RG="bgpalerter-prod"; LOCATION="eastus"; VM_NAME="bgpalerter-01"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/bgpalerter-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az network vnet create -g "$RG" --name bgp-vnet --address-prefix 10.90.0.0/16 --subnet-name bgp-subnet --subnet-prefix 10.90.1.0/24
az network nsg create -g "$RG" --name bgp-nsg
az network nsg rule create -g "$RG" --nsg-name bgp-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp
az network nsg rule create -g "$RG" --nsg-name bgp-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 443 --access Allow --protocol Tcp
az vm create -g "$RG" --name "$VM_NAME" --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name bgp-vnet --subnet bgp-subnet --nsg bgp-nsg --public-ip-sku Standard

Step 3: Connect via SSH

ssh azureuser@<vm-ip>

Step 4: Verify the services are running

BGPalerter's status API listens on loopback 127.0.0.1:8011 and nginx fronts it on port 80. The health endpoint is public; the status API requires your password.

sudo systemctl start bgpalerter nginx 2>/dev/null || true
sudo systemctl is-active bgpalerter nginx
ss -tln | grep -E ':80 |127.0.0.1:8011'
curl -s http://127.0.0.1/health

You should see both services active, the two listening sockets (the status API bound to loopback, nginx on port 80), and ok from the public health endpoint.

Step 5: Read your per VM status API password

The password was generated on this VM's first boot and stored in a root only file. Read it and keep it secret: it authenticates every status API request. Confirm that unauthenticated requests are rejected.

sudo cat /root/bgpalerter-info.txt
echo "unauthenticated /status -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/status)"

The info note holds STATUS_API_PASSWORD and the instance URLs, is owned root:root with mode 0600, and an unauthenticated call to /status returns 401 because nginx enforces authentication.

Step 6: Query the status API

Load the password into a shell variable and query the status API through nginx with HTTP Basic Auth. BGPalerter returns a JSON document describing the health of its components (the RIS connectors and the RPKI data). A healthy daemon returns HTTP 200.

export BGP_PW=$(sudo grep '^STATUS_API_PASSWORD=' /root/bgpalerter-info.txt | cut -d= -f2-)
echo "authenticated /status -> HTTP $(curl -s -o /dev/null -w '%{http_code}' -u cloudimg:$BGP_PW http://127.0.0.1/status)"
curl -s -u cloudimg:$BGP_PW http://127.0.0.1/status | jq .

The authenticated call returns 200 and a JSON object reporting each connector and the RPKI status. This is the endpoint you point an external monitor or dashboard at (over HTTPS, with the password).

Step 7: Monitor your own network

Out of the box the appliance ships a placeholder prefixes.yml that monitors a documented example autonomous system so the daemon runs immediately. Replace it with your own prefixes and ASNs. BGPalerter can generate the watch list for you from an ASN: it discovers the prefixes that AS originates and writes them into prefixes.yml.

cd /var/lib/bgpalerter
sudo systemctl stop bgpalerter
sudo -u bgpalerter /usr/local/bin/bgpalerter generate -a <YOUR_ASN> -o prefixes.yml -i -m
sudo systemctl start bgpalerter

The -i flag includes RPKI/ROA monitoring for the generated prefixes and -m includes monitoring the ASN itself. Review the generated prefixes.yml, then restart the service. You can also edit prefixes.yml by hand to add or remove prefixes; each entry has a description, an asn and monitoring options.

Step 8: Configure alerting

By default BGPalerter writes alerts to a rotating log file under /var/lib/bgpalerter/logs/. Watch it to see alerts as they are raised.

ls -1 /var/lib/bgpalerter/logs/
sudo tail -n 20 /var/lib/bgpalerter/logs/reports-$(date -u +%Y-%m-%d).log 2>/dev/null || echo "no alerts logged yet (this is normal on a quiet network)"

To deliver alerts to email, Slack, syslog, an HTTP webhook, Kafka and more, edit the reports: section of /var/lib/bgpalerter/config.yml and restart the service. Each report type has a template in the file. For example, to add email alerts uncomment and complete the reportEmail block with your SMTP server and recipients, then:

sudo systemctl restart bgpalerter

Step 9: Enable HTTPS

nginx fronts the status API on port 80 and is ready for TLS. Point a DNS record at the VM, then obtain a certificate with certbot and let it configure nginx for port 443.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

After issuance, restrict the NSG so only 443 (and 22 from your management network) is reachable, and query the status API over https://your-domain.example.com/status with the password.

Persistence, first boot and updates

The configuration (config.yml, prefixes.yml) and the alert logs live on the OS disk under /var/lib/bgpalerter/ and are captured into the image, so a VM launched from this image is ready immediately. The first boot service generates the per VM status API password, refreshes the BGPalerter binary to the latest release, then disables itself so subsequent reboots are unaffected. The OS ships fully patched with unattended security upgrades enabled.

Support

Every cloudimg deployment includes 24/7 support with a 24 hour response SLA. Contact support@cloudimg.co.uk for help with deployment, configuration or scaling.

This is a repackaged open source software product with additional charges for cloudimg support services. BGPalerter is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.