WatchYourLAN on Ubuntu 24.04 on Azure User Guide

Overview

WatchYourLAN is a lightweight, self-hosted network IP scanner with a modern web dashboard. It periodically arp-scans your local network, discovers every device it can see, and records each host's MAC address, IP address, name and vendor along with a full online and offline history, so you always know what is connected. New or unknown devices are surfaced immediately, and every host is queryable through a clean web UI and a REST API. The cloudimg image installs the pinned WatchYourLAN 2.1.4 static binary, runs it under systemd with its SQLite datastore, and, because WatchYourLAN ships no login of its own, is secure by default: the scanner binds only to the loopback interface and nginx fronts it on port 80 with HTTP Basic Auth, with a unique password generated on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• WatchYourLAN 2.1.4 (single static Go binary) running as the watchyourlan systemd service
• Periodic arp-scan discovery of every host on the VM's primary network interface
• A SQLite datastore at /var/lib/watchyourlan/scan.db recording hosts and their online/offline history
• The WatchYourLAN web UI and REST API bound to 127.0.0.1:8840 (loopback only, never exposed directly)
• nginx fronting the UI on :80 with HTTP Basic Auth and a unique password generated on first boot
• watchyourlan.service + nginx.service as systemd units, enabled and active
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point; WatchYourLAN is very light on resources. NSG inbound: allow 22/tcp from your management network, 80/tcp for the web UI, and 443/tcp if you add TLS. WatchYourLAN scans the network the VM is attached to, so deploy it on the VNet/subnet whose hosts you want to see. It serves plain HTTP on port 80; for production-adjacent use, terminate TLS in front of it with your own domain (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for WatchYourLAN 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 -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name watchyourlan \
  --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 watchyourlan --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active watchyourlan.service nginx.service

Both report active. WatchYourLAN serves its web UI and REST API on the loopback connector 127.0.0.1:8840; nginx fronts the UI on port 80 with HTTP Basic Auth. WatchYourLAN's SQLite datastore lives at /var/lib/watchyourlan/scan.db.

Step 5 - Retrieve your web UI password

Because WatchYourLAN has no built-in login, cloudimg protects its web UI and REST API with nginx HTTP Basic Auth. The username is admin and a unique password is generated on the first boot of your VM and written to a root-only file:

sudo cat /root/watchyourlan-credentials.txt

This file contains WATCHYOURLAN_USERNAME, WATCHYOURLAN_PASSWORD and the WATCHYOURLAN_URL to open in a browser. The password is stored on disk only as a bcrypt hash in /etc/nginx/.watchyourlan.htpasswd, so no plaintext password ships in the image. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe.

Step 7 - Confirm authentication is enforced

Because a password is set on first boot, an unauthenticated request to the web UI returns HTTP 401, so nobody reaches your dashboard without the password. The following reads the per-VM password from the credentials file and proves the round-trip - unauthenticated is rejected, and the correct password authenticates:

PW=$(sudo grep '^WATCHYOURLAN_PASSWORD=' /root/watchyourlan-credentials.txt | cut -d= -f2-)
echo "unauth: $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/)"
echo "authed: $(curl -s -o /dev/null -w '%{http_code}' -u admin:$PW http://127.0.0.1/)"

It prints unauth: 401 then authed: 200. The REST API sits behind the same Basic Auth; for example the discovered hosts are available at /api/all and the running version at /api/version.

Step 8 - Sign in to the web UI

Browse to http://<vm-public-ip>/. Your browser prompts for a username and password: enter admin and the password from Step 5. WatchYourLAN opens on its dashboard - the table of every host it has discovered on your network, each row showing the host's name, IP address, MAC address, hardware vendor and whether it is currently online. On a freshly deployed cloud VM the table starts small and fills in as the periodic scan runs; on a busy LAN it lists every device on the subnet.

Step 9 - Inspect a discovered host

Click any host to open its detail page, where WatchYourLAN shows that device's identity - name, IP, MAC and vendor - alongside the record of when it has been seen. This is where you name and annotate the devices you recognise, so unknown arrivals stand out.

Step 10 - Review the scan history

Open the History page to see how many hosts have been online over time. This timeline is what turns WatchYourLAN from a one-off scan into a continuous record of who is on your network and when.

Step 11 - Review the configuration page

Open the Config page to see the active settings - the interface being scanned, the scan interval, the theme and the datastore in use. These are the settings cloudimg writes on first boot; the interface is detected automatically from the VM's default route.

Step 12 - How scanning works

WatchYourLAN scans the VM's primary network interface on a fixed interval (120 seconds by default) using arp-scan, and records everything it finds in its SQLite datastore. Because it runs continuously, hosts that appear or disappear are captured in the history, and any new device on the subnet shows up on the next scan. On a solo cloud VM the scanner naturally sees only a handful of neighbours; deploy it on a subnet with the devices you care about to get the full picture.

You can trigger an immediate rescan from the web UI, or from the authenticated REST API:

PW=$(sudo grep '^WATCHYOURLAN_PASSWORD=' /root/watchyourlan-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w '%{http_code}\n' -u admin:$PW http://127.0.0.1/api/all

It prints 200, confirming the hosts API is reachable behind the Basic Auth proxy.

Maintenance

• Password: the web UI password is set on first boot and stored as a bcrypt entry in /etc/nginx/.watchyourlan.htpasswd. To change it, run sudo htpasswd -B /etc/nginx/.watchyourlan.htpasswd admin and then sudo systemctl reload nginx.
• Scanned interface / interval: cloudimg writes the detected interface and defaults into /var/lib/watchyourlan/config_v2.yaml. Edit that file (or use the Config page in the UI) and run sudo systemctl restart watchyourlan to change the interface, scan interval (TIMEOUT) or history retention (TRIM_HIST).
• Datastore: all WatchYourLAN state lives in /var/lib/watchyourlan/scan.db; back up that file to preserve your host history.
• Upgrades: WatchYourLAN is a single static binary at /usr/local/bin/watchyourlan; to upgrade, download a newer pinned release, verify its checksum, replace the binary and run sudo systemctl restart watchyourlan. Your datastore is preserved.
• TLS: WatchYourLAN is fronted by nginx on plain HTTP port 80; add TLS (for example certbot with your own domain) before exposing it beyond a trusted network.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.