Looking Glass

Configuration

Add the looking-glass block under environment in your Ze config:

environment {
    looking-glass {
        enabled true
        server main {
            ip 0.0.0.0
            port 8443
        }
    }
}

Environment variable overrides: ze.looking-glass.listen=ip:port, ze.looking-glass.enabled=true, ze.looking-glass.tls=false, ze.looking-glass.token=<token>, ze.looking-glass.certificate=<name>.

TLS is on by default

The looking glass binds 0.0.0.0 and publishes route data and session state, so it serves HTTPS unless you turn TLS off. Two rules apply:

• Write tls false (or set ze.looking-glass.tls=false) to serve plaintext, for example behind a proxy that terminates TLS.
• With no certificate and no blob storage there is no self-signed certificate to serve. If you wrote tls true, Ze reports the error and does not start the looking glass. If you wrote nothing and took the default, Ze serves plaintext and prints a warning that names ze init as the remedy.

Serve your own certificate

A visitor to a public looking glass has not installed your root, so a self-signed certificate gives them a browser warning. Set certificate to the name of a pki { certificate <name> } entry and the listener serves that leaf and every intermediate the entry holds:

environment {
    looking-glass {
        enabled     true
        certificate lan
    }
}

Optional bearer token

A looking glass is normally public and read-only, so token is off by default. Set it to require a bearer token on every route. Ze compares the token constant-time over SHA-256 digests. A request with no token, a wrong token, or an Authorization header that is not Bearer <token> gets 401.

When the looking-glass block is absent, no HTTP server is started and no resources are consumed.

Web UI

The HTMX web UI is available at https://<host>:<port>/lg/ (http:// when you set tls false). No authentication is required unless you set token.

Navigation uses a single-page tab layout with HTMX fragment swapping. The real htmx.min.js (v4.0.0) is embedded, and the peers page also loads hx-sse.min.js, htmx 4's SSE extension.

Birdwatcher REST API

The looking glass exposes a birdwatcher-compatible JSON API for integration with tools like Alice-LG.

All API responses use Content-Type: application/json with birdwatcher-convention snake_case field names (not Ze's standard kebab-case).

The per-peer route counts on /protocols/bgp come from the bgp-rib plugin's Adj-RIB-In and Adj-RIB-Out sizes, merged into show bgp: routes_received and routes_imported are both the Adj-RIB-In size (Ze retains only accepted routes, so there is no distinct pre-policy received count here), and routes_exported is the Adj-RIB-Out size. routes_filtered is always 0: Ze does not retain import-filtered routes (unlike BIRD's "import keep filtered"), so the /routes/filtered/{name} endpoint also returns an empty list.

Ze emits the four counts on every peer, whatever it knows. When it has no source, each count is 0 and routes_counts_available is false. That happens when the bgp-rib plugin is not loaded, and on every BMP-monitored peer. A client that must tell "no routes" from "unknown" reads routes_counts_available, never a count of 0 on its own. The normative statement is Birdwatcher compatibility, Section 7.2.

Alice-LG Integration

To use Ze as a data source for Alice-LG, point Alice-LG's birdwatcher source configuration at the looking glass API:

sources:
  - name: "Ze Router"
    type: birdwatcher
    birdwatcher:
      api: "https://ze-host:8443/api/looking-glass"

Security

The looking glass is designed for public IXP deployment. It is read-only, and open unless you set token. Security measures include:

• Strict input validation on all query parameters (character allowlists, length limits).
• Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff headers.
• X-Ze-Version names the exact build. Write environment { hide-version true; } to keep it off the looking glass and the web interface together.
• SSE connection limit (100 concurrent clients).
• All HTML output rendered through templ, which escapes every interpolated value. The two SVG graph builders stay in Go and escape their labels with template.HTMLEscapeString.
• The Content-Security-Policy is default-src 'self', so no page carries an inline script or an inline event handler. A test refuses one in any .templ source of the package.
• No direct RIB or plugin imports; all data accessed via command dispatcher.

When TLS is enabled, the server uses TLS 1.2 minimum. It reads its own certificate leaf, resolved against the same PKI store the web UI reads, and serves a self-signed certificate when that leaf is unset.