Batfish

Search the Marketplace for Batfish on Ubuntu 24.04 and choose your VM size.

Attach a network security group (NSG) that allows TCP 22 (SSH) from your management network and TCP 9996 (the Batfish API) from the workstations, CI runners and automation that will query it.

Batfish holds your device configurations, so treat 9996 as an administrative port and do not open it to the internet. Front it with TLS in production (see Step 10).

az vm image terms accept --urn sac1647283583153:batfish-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-rg \
  --name batfish-01 \
  --image sac1647283583153:batfish-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az network nsg rule create \
  --resource-group my-rg \
  --nsg-name batfish-01NSG \
  --name allow-batfish \
  --priority 1010 \
  --protocol Tcp --destination-port-ranges 9996 \
  --source-address-prefixes <your-mgmt-cidr> \
  --access Allow

SSH in as azureuser:

ssh azureuser@<vm-ip>

First boot generates this VM's secrets, proves the gate, starts Batfish and runs the bundled analysis. It completes in well under a minute.

Check that everything is up, and confirm that the only externally reachable ports are SSH and the gate:

systemctl is-active batfish.service nginx.service batfish-firstboot.service ss -lntp grep BATFISH_HEAP_OPTS /etc/default/batfish curl -s http://127.0.0.1:9996/nginx-health

All three services report active. The socket list shows exactly one routable Batfish-related listener, nginx on 0.0.0.0:9996, with the JVM itself on 127.0.0.1:19996 and nothing else. The heap line shows the bound that first boot computed for this machine.

Every secret on this appliance is generated on this VM, on its first boot. Nothing is baked into the image, and no two VMs share a credential. Read the credentials file:

sudo ls -l /root/batfish-credentials.txt
sudo cat /root/batfish-credentials.txt

BATFISH_API_KEY is what a pybatfish client presents. BATFISH_USERNAME and BATFISH_PASSWORD are an HTTP Basic credential for curl and any generic HTTP client.

Now prove that the appliance refuses everything else:

BF_URL=http://127.0.0.1:9996/v2/networks
KEY=$(sudo grep -m1 '^BATFISH_API_KEY=' /root/batfish-credentials.txt | cut -d= -f2-) DEFAULT_KEY=00000000000000000000000000000000
ANON=$(curl -s -o /dev/null -w '%{http_code}' "$BF_URL")
DEF=$(curl -s -o /dev/null -w '%{http_code}' -H "X-Batfish-Apikey: $DEFAULT_KEY" "$BF_URL")
MINE=$(curl -s -o /dev/null -w '%{http_code}' -H "X-Batfish-Apikey: $KEY" "$BF_URL") printf 'anonymous -> HTTP %s\n' "$ANON" printf 'published default API key -> HTTP %s\n' "$DEF" printf 'your own per VM API key -> HTTP %s\n' "$MINE" test "$ANON" = 401 && test "$DEF" = 401 && test "$MINE" = 200 && echo GATE_PROOF_OK

The first two return 401, and only the third returns 200. The published default key is refused deliberately. A pybatfish client that has not been given a key sends exactly that value, so an unconfigured client cannot reach your network data by accident.

The appliance ships upstream's own example network: 13 Cisco IOS devices and 2 hosts across three autonomous systems, with external BGP announcements. A batfish-demo command uploads it and analyses it through the gate with a stock pybatfish client.

First boot has already run this once. Run it again whenever you want to confirm that the service is healthy end to end.

sudo batfish-demo

The command parses the snapshot, reports any parse or conversion issues, lists the devices Batfish modelled, and evaluates every BGP session in the network. UNIQUE_MATCH means the two ends agree and the session will establish. Anything else is a finding you want to know about before deployment.

The log of the first-boot run is kept at /var/log/batfish-firstboot-demo.log:

sudo tail -20 /var/log/batfish-firstboot-demo.log

Install the client, and pin it to the same version as the server so that the client and service question sets match:

pip install pybatfish==2025.7.7.2423

Then point a Session at the appliance. This is the whole client-side configuration: an address, the port, and the API key you read in Step 5:

from pybatfish.client.session import Session bf = Session( host="<vm-ip>", port=9996, api_key="<paste BATFISH_API_KEY from Step 5>", ) bf.set_network("my-network") bf.init_snapshot("/path/to/my/configs", name="candidate", overwrite=True) print(bf.q.initIssues().answer().frame()) print(bf.q.bgpSessionCompatibility().answer().frame())

pybatfish always sends its key in the X-Batfish-Apikey header, which is exactly what the gate checks, so no client-side changes, wrappers or proxies are needed.

For other HTTP clients, the same key is also accepted as Authorization: Bearer <key> or in X-Api-Key. The HTTP Basic credential from Step 5 works too. Run the following on the appliance, where it reads its own credentials file:

BF_USER=$(sudo grep -m1 '^BATFISH_USERNAME=' /root/batfish-credentials.txt | cut -d= -f2-)
BF_PASS=$(sudo grep -m1 '^BATFISH_PASSWORD=' /root/batfish-credentials.txt | cut -d= -f2-)
curl -sf -u "${BF_USER}:${BF_PASS}" http://127.0.0.1:9996/v2/networks && echo BASIC_AUTH_OK

Reachability is where Batfish earns its keep. Ask it where a packet would actually go, and it returns every equal-cost path, hop by hop, with a disposition for each:

from pybatfish.datamodel.flow import HeaderConstraints answer = bf.q.traceroute( startLocation="@enter(as2dept1[GigabitEthernet1/0])", headers=HeaderConstraints(dstIps="1.0.2.1", srcIps="2.34.201.10"), ).answer().frame() for trace in answer.iloc[0]["Traces"]: print(trace.disposition, " -> ".join(hop.node for hop in trace.hops))

Run that against the bundled example on the appliance itself:

sudo /opt/batfish/pybatfish-venv/bin/python - "$(sudo grep -m1 '^BATFISH_API_KEY=' /root/batfish-credentials.txt | cut -d= -f2-)" <<'PYEOF' import sys, logging logging.getLogger("pybatfish").setLevel(logging.ERROR) from pybatfish.client.session import Session from pybatfish.datamodel.flow import HeaderConstraints bf = Session(host="127.0.0.1", port=9996, api_key=sys.argv[1]) bf.set_network("sac-example") bf.set_snapshot("example") answer = bf.q.traceroute( startLocation="@enter(as2dept1[GigabitEthernet1/0])", headers=HeaderConstraints(dstIps="1.0.2.1", srcIps="2.34.201.10"), ).answer().frame() n = 0 for _, row in answer.iterrows(): for trace in row["Traces"]: n += 1 print(f"path {n}: {trace.disposition}, {len(trace.hops)} hops") print(" " + " -> ".join(hop.node for hop in trace.hops)) print(f"{n} equal-cost paths, AS2 access switch to AS1 edge") print("ipOwners:", len(bf.q.ipOwners().answer().frame()), "addresses inventoried") print("undefinedReferences:", len(bf.q.undefinedReferences().answer().frame()), "defects found") PYEOF

Batfish computes the dataplane on demand and returns all four equal-cost paths from the AS2 access switch out to the AS1 edge, seven hops each.

ipOwners inventories every address in the snapshot. undefinedReferences finds structures that a configuration refers to but never defines. This is a class of latent defect that static analysis catches and a ping never will.

Batfish reads a snapshot, a directory of the configuration files your devices already produce. The minimum layout is a configs/ subdirectory containing one file per device, named however you like:

my-snapshot/ configs/ core-sw-01.cfg edge-rtr-01.cfg fw-01.conf

Collect those with whatever you already use: RANCID, Oxidized, NAPALM, your vendor's own archive, or a git repository of golden configurations. Then pass the directory to init_snapshot().

Optional subdirectories let you model more: hosts/ for host JSON, iptables/ for host firewalls, batfish/isp_config.json to model upstream ISPs, and an external_bgp_announcements.json to inject routes your peers advertise. The bundled example shows all of these:

find /usr/share/batfish/example-snapshot -type f | sort

List the questions available to you:

ls /usr/share/batfish/questions/stable/ | head -40

Batfish never touches your live devices. It reads text and reasons about it, so running it against a candidate configuration change is safe.

The gate speaks plain HTTP, so the appliance works immediately on a VM address. For production, terminate TLS in the same nginx server block. First back up the site file and test the configuration:

sudo cp /etc/nginx/sites-available/batfish.conf /root/batfish.conf.bak
sudo nginx -t

Add your certificate and key, change listen 9996; to listen 9996 ssl;, and reload nginx. Leave the auth_basic and auth_basic_user_file directives and the proxy_set_header X-Batfish-Apikey line exactly as they are. They are the gate, and nginx refuses to start without them.

Then point clients at https:// and set ssl=True on the Session. An Azure Application Gateway or Front Door in front of the VM works equally well.