hyperglass Ubuntu 24.04

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet and subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is the recommended size. For NSG inbound rules, allow 22/tcp from your management network and 80/tcp from wherever your looking glass audience is. For a public looking glass, that is the internet. The appliance also needs outbound SSH (22/tcp) to your routers, because that is how hyperglass collects output.

hyperglass serves plain HTTP on port 80. A looking glass is a public web page, so terminate TLS in front of it with your own domain before you advertise it (see the last step).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for hyperglass by SecureAnyCloud, and select Create. On the Basics tab, 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 select Review + create, and then Create.

Step 2 - Deploy from the Azure CLI

To deploy with the Azure CLI instead of the portal, run the following commands:

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:hyperglass:default:latest
az vm create \
  --resource-group <your-rg> \
  --name hyperglass \
  --image sac1647283583153:hyperglass:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
# Open the HTTP port so visitors can reach the looking glass
az vm open-port --resource-group <your-rg> --name hyperglass --port 80 --priority 900

Step 3 - Retrieve the per-VM operator credentials

Nothing secret is baked into the image. On the first boot, a one-shot service (hyperglass-firstboot.service) generates an operator password unique to your instance and writes it into an nginx credentials file. The service also records the password in /root/hyperglass-credentials.txt, which only root can read.

The looking glass itself is anonymous by design and needs no credentials. These credentials protect the operator-only appliance administration page at /admin/.

SSH in as azureuser and read them:

sudo cat /root/hyperglass-credentials.txt

# hyperglass — per-VM credentials, generated on first boot by
# hyperglass-firstboot.service. These are unique to THIS VM. Store them safely. hyperglass.url=http://203.0.113.10/ hyperglass.admin.url=http://203.0.113.10/admin/ hyperglass.admin.user=sac-admin hyperglass.admin.pass=****************************
# Canonical keys consumed by the sac smoke verifier + guide substitution: HYPERGLASS_ADMIN_USER=sac-admin HYPERGLASS_ADMIN_PASSWORD=<set-at-first-boot>

Step 4 - Confirm the services are running

for s in redis-server hyperglass nginx; do printf '%-16s %s\n' "$s" "$(systemctl is-active $s)"; done

redis-server active hyperglass active nginx active

Only nginx is publicly reachable. The application and Redis both listen on loopback:

sudo ss -ltnp | grep -E ':(80|8001|6379)\s'

Step 5 - Open the looking glass

Browse to http://<your-vm-public-ip>/. The hyperglass interface shows a Location selector that lists the devices you have configured, a Query Type selector, and a Target field.

Confirm that it also answers from the command line:

curl -s -o /dev/null -w 'looking glass: HTTP %{http_code}\n' http://127.0.0.1/

looking glass: HTTP 200

The image ships with a single sample device so that hyperglass starts and the interface is complete before you configure anything. The device is 192.0.2.1, an address from the IETF documentation range that is never routed, with REPLACE_ME credentials. It cannot reach any real network. Step 7 replaces it.

curl -s http://127.0.0.1/api/devices | python3 -m json.tool

[ { "id": "example_router", "name": "Example Router", "group": "Example Site" } ]

Step 6 - Query from the API

The same HTTP API serves everything the web interface does, so you can script queries or drive them from monitoring.

List the query types your devices expose:

curl -s http://127.0.0.1/api/queries | python3 -m json.tool

[ "BGP Community", "Traceroute", "Ping", "BGP AS Path", "BGP Route" ]

Read the looking glass parameters:

curl -s http://127.0.0.1/api/info | python3 -m json.tool

{ "name": "Looking Glass", "organization": "Example Network", "primary_asn": 65001, "version": "2.0.4" }

A query is a POST to /api/query with the device id, the directive id and the target. Every response, success or failure, uses the same envelope: output, level and keywords.

Until you add a real router, a query against the shipped sample device returns a clean, well-formed timeout rather than a hang or a stack trace. This is the correct behavior for a device that does not answer:

curl -s -m 60 -H 'Content-Type: application/json' \
  -d '{"queryLocation":"example_router","queryTarget":"1.1.1.0/24","queryType":"__hyperglass_cisco_ios_bgp_route__"}' \
  http://127.0.0.1/api/query | python3 -c 'import json,sys; r=json.load(sys.stdin); print("level:", r["level"]); print("output:", str(r["output"]).split(chr(10))[0])'

level: danger output: Request timed out. (TCP connection to device failed.

Step 7 - Add your own routers

This step turns the appliance into your looking glass. Edit the devices file:

$
sudo nano /etc/hyperglass/devices.yaml

Replace the sample entry with your own router. A minimal Cisco IOS device looks like this:

devices: - name: Core Router LON1 description: London core router address: 198.51.100.7 platform: cisco_ios port: 22 group: London credential: username: lookingglass password: "your-router-password"
# The built-in Ping and Traceroute directives issue
# ping {target} repeat 5 source {source4}
# so every device must declare the source addresses its own router should
# send probes from. These are usually the router's loopback addresses. attrs: source4: "198.51.100.7" source6: "2001:db8:100::7" # Inherit every built-in directive for this platform: BGP Route, # BGP Community, BGP AS Path, Ping and Traceroute. directives: - builtins: true

Use a dedicated, least-privilege, read-only account on the router. A looking glass needs to run only show commands. Key-based authentication is supported instead of a password:

credential: username: lookingglass key: /etc/hyperglass/keys/router.pem

Supported platform values are cisco_ios, cisco_xr, cisco_nxos, juniper, arista_eos, bird, frr, huawei, mikrotik, nokia_sros, openbgpd, tnsr and vyos.

After you configure a real router, visitors pick it, choose a query type and enter a target:

hyperglass then returns the router's own output, rendered:

Apply the change. hyperglass derives its interface from your configuration, so this command rebuilds the interface and restarts the service:

sudo hyperglass-apply

Confirm that hyperglass parsed your device:

sudo hyperglass-cli devices

Branding lives in /etc/hyperglass/config.yaml: set org_name, site_title and primary_asn to your own, then run sudo hyperglass-apply again.

Step 8 - Understand the abuse controls

A looking glass is deliberately public, and it runs commands on your routers on behalf of anonymous visitors. This image therefore ships its protections switched on instead of leaving them to you.

Non-public targets are refused. The image rejects queries aimed at private, loopback, link-local, multicast or reserved address space before it contacts your router, so nobody can use your looking glass to map your private network:

curl -s -H 'Content-Type: application/json' \
  -d '{"queryLocation":"example_router","queryTarget":"10.0.0.0/8","queryType":"__hyperglass_cisco_ios_bgp_route__"}' \
  http://127.0.0.1/api/query | python3 -m json.tool

{ "output": "10.0.0.0/8 is not valid. ('10.0.0.0/8' is in private address space. This looking glass only accepts publicly routable targets.)", "level": "warning", "keywords": [ "private address space", "'10.0.0.0/8' is in private address space. This looking glass only accepts publicly routable targets.", "10.0.0.0/8" ] }

Visitors see the same refusal in the interface:

A hyperglass input plugin at /etc/hyperglass/plugins/sac_public_targets.py implements this policy. To allow address space that you legitimately route, such as CGNAT, add it to the ALLOW_EXTRA list at the top of that file and run sudo hyperglass-apply.

Query submission is rate-limited to 12 requests per minute per source address, with a burst of 5. Beyond that, the server returns HTTP 429. Tune the limit in /etc/nginx/conf.d/hyperglass-limits.conf and reload nginx with sudo nginx -t && sudo systemctl reload nginx.

Identical queries are cached for 120 seconds in Redis instead of being re-run against your routers. To change the duration, edit cache.timeout in /etc/hyperglass/config.yaml.

Step 9 - The operator-only administration page

The looking glass is anonymous, but the appliance administration page at /admin/ is not. The per-VM credentials from Step 3 protect it. The page summarizes this instance, where its configuration lives, and the abuse controls in force.

Anonymous access is refused:

curl -s -o /dev/null -w 'anonymous /admin/ -> HTTP %{http_code}\n' http://127.0.0.1/admin/

anonymous /admin/ -> HTTP 401

With the per-VM credentials, the page opens:

curl -s -o /dev/null -w 'authenticated /admin/ -> HTTP %{http_code}\n' -u "sac-admin:<HYPERGLASS_ADMIN_PASSWORD>" http://127.0.0.1/admin/

authenticated /admin/ -> HTTP 200

To change the operator password, write the new one on stdin so that it never reaches your shell history or the system journal:

$ printf '%s\n' 'your-new-password' | sudo htpasswd -i -B /etc/nginx/hyperglass.htpasswd sac-admin Updating password for user sac-admin

Step 10 - Enable HTTPS with your own domain

Point a DNS record such as lg.example.net at the VM's public IP, then run:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain> -m <your-email> --agree-tos --redirect -n

Certbot edits the nginx site in place and installs a renewal timer. The rate limiting and the /admin/ protection stay in force because they live in the same server block.

Administration and support

The following table lists common administration tasks and their commands.

Task Command

Service status systemctl status hyperglass

Application logs journalctl -u hyperglass -f

Edit routers sudo nano /etc/hyperglass/devices.yaml

Edit branding and query settings sudo nano /etc/hyperglass/config.yaml

Apply configuration changes sudo hyperglass-apply

Inspect parsed devices sudo hyperglass-cli devices

Inspect parsed settings sudo hyperglass-cli params

Clear the query cache sudo hyperglass-cli clear-cache

Operator credentials sudo cat /root/hyperglass-credentials.txt

hyperglass is published under the BSD 3-Clause Clear licence. This is a repackaged open-source product, and SecureAnyCloud charges for support services, not for the software. Our engineers provide 24/7 support for deployment, upgrades, TLS termination, router onboarding, custom query directives and scaling. Contact sales@secureanycloud.com.

Deploy on Azure

Launch hyperglass Network Looking Glass on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com