WatchYourLAN on AWS User Guide

Overview

This image runs WatchYourLAN 2.1.4 on Ubuntu 24.04 LTS. WatchYourLAN is an open source, lightweight network device scanner with a clean web dashboard. It periodically scans the network the instance is attached to, 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 and get an immediate signal when something new appears.

cloudimg packages the official upstream release as a single pinned static binary with real systemd services and a SQLite datastore, so a working dashboard answers within minutes of launch.

What it scans on AWS

This is the honest part, and it matters. WatchYourLAN discovers devices by ARP scanning the network interface of the instance it runs on. On EC2 that interface sits on your VPC subnet, so what it sees is the hosts reachable on that subnet - other instances and network interfaces in the same subnet - or a network you attach to it at layer 2 over a VPN or overlay.

It does not scan arbitrary networks, and it cannot reach across the public internet: ARP is a link-local protocol that never leaves the local broadcast domain. A single instance sitting in an otherwise-empty subnet will legitimately show only a device or two (typically the subnet router). To get a useful inventory, launch it on the subnet whose devices you want to track, or bridge your on-premises network to it over a VPN and point it at that interface.

Secure by default

WatchYourLAN has no built-in login of its own upstream. Exposing a network scanner's dashboard unauthenticated on a public IP would leak your network's topology, so this image closes that gap in two ways:

• The application binds to the loopback interface only (127.0.0.1:8840) and is never exposed directly.
• nginx fronts it on port 80 and enforces HTTP Basic Auth, with a password generated uniquely on this instance's first boot and written to a root-only file. No shared or default login exists anywhere in the image.

What is included:

• WatchYourLAN 2.1.4: the official upstream release binary, verified against a published sha256 checksum at build time
• A SQLite store at /var/lib/watchyourlan/scan.db recording every discovered host and its online/offline history
• nginx on port 80: the dashboard and REST API at / behind HTTP Basic Auth, and an unauthenticated /healthz for load-balancer and uptime probes
• watchyourlan.service, nginx.service and a one-shot watchyourlan-firstboot.service, all enabled
• A per-instance dashboard password generated on first boot and written to /root/watchyourlan-credentials.txt, readable only by root
• A fully patched Ubuntu 24.04 LTS base with unattended security upgrades enabled
• 24/7 cloudimg support

Connecting to your instance

Connect over SSH on port 22 as the default login user for the AMI variant you launched:

ssh ubuntu@<instance-public-ip>

Use the key pair you selected at launch. The dashboard is served over the network as described below.

Prerequisites

An AWS account, an EC2 key pair, and a VPC with a subnet in your target region. m5.large (2 vCPU / 8 GiB RAM) is the recommended instance type; WatchYourLAN itself is lightweight, so this is comfortable headroom.

Security group inbound rules: allow 22/tcp from your management network and 80/tcp from the networks that need the dashboard. Do not expose the dashboard to the whole internet - restrict 80/tcp to your own address ranges. The dashboard is authenticated, but a network inventory tool is exactly the sort of surface you want reachable only by people you trust.

To get a useful inventory, launch the instance onto the subnet whose devices you want to track. If the devices you care about live on premises, connect that network to your VPC over a VPN or AWS Direct Connect first (see Step 8).

Step 1 - Launch from the AWS Marketplace

Subscribe to the listing, choose the Ubuntu 24.04 version, and launch it with Launch through EC2. Pick the m5.large instance type, select your key pair, and choose the subnet whose devices you want WatchYourLAN to inventory. Under the security group, allow 22/tcp and 80/tcp from your own networks only.

Step 2 - Launch from the AWS CLI

If you prefer the CLI, create a security group scoped to your own networks and launch the AMI (replace the placeholders with your values):

aws ec2 create-security-group --group-name watchyourlan-sg \
  --description "WatchYourLAN dashboard + SSH"

# SSH and the dashboard, from YOUR networks only (not 0.0.0.0/0)
aws ec2 authorize-security-group-ingress --group-name watchyourlan-sg \
  --protocol tcp --port 22 --cidr <your-admin-cidr>
aws ec2 authorize-security-group-ingress --group-name watchyourlan-sg \
  --protocol tcp --port 80 --cidr <your-admin-cidr>

aws ec2 run-instances --image-id <ami-id> --instance-type m5.large \
  --key-name <your-key> --security-groups watchyourlan-sg \
  --subnet-id <the-subnet-you-want-to-inventory>

Step 3 - Connect to your instance

ssh ubuntu@<instance-public-ip>

Step 4 - Confirm the services are running

Two services make up the appliance: WatchYourLAN itself and the nginx reverse proxy. Confirm both are active and check what is listening.

Note the :8840 line: WatchYourLAN is bound to 127.0.0.1, not 0.0.0.0. That is deliberate - it means the dashboard can only be reached through nginx, which enforces authentication. It cannot be bypassed by connecting to port 8840 directly.

systemctl is-active watchyourlan nginx
sudo ss -tlnp | grep -E ':80 |127.0.0.1:8840'

Expected output:

active
active
LISTEN 0      511        127.0.0.1:8840      0.0.0.0:*    users:(("watchyourlan",pid=...))
LISTEN 0      511          0.0.0.0:80        0.0.0.0:*    users:(("nginx",pid=...))
LISTEN 0      511             [::]:80           [::]:*    users:(("nginx",pid=...))

Step 5 - Retrieve your per-instance dashboard password

WatchYourLAN has no login of its own upstream. Because that dashboard exposes your network's device inventory, this image puts it behind HTTP Basic Auth and generates the password on your instance, on its first boot. Nothing in the image knows it and no other instance shares it.

Read it from the root-only credentials file:

sudo cat /root/watchyourlan-credentials.txt

Expected output (your password will differ - it is unique to your instance):

# WatchYourLAN - generated on first boot by watchyourlan-firstboot.service
# These credentials are unique to this VM. Store them somewhere safe.

WATCHYOURLAN_URL=http://<instance-ip>/
WATCHYOURLAN_USERNAME=admin
WATCHYOURLAN_PASSWORD=<generated on your instance at first boot>

When reaching the dashboard from your workstation, use the instance's public IP or DNS name (and, per the note in Prerequisites, only from a network your security group allows).

Step 6 - Confirm the dashboard is protected

Prove the authentication is real: a request with no credentials must be rejected, and the per-instance password must be accepted. This reads the password straight out of the credentials file, which is also the pattern to use in your own scripts:

PW=$(sudo awk -F= '/^WATCHYOURLAN_PASSWORD=/{print $2; exit}' /root/watchyourlan-credentials.txt)
curl -s -o /dev/null -w 'dashboard, no credentials   -> HTTP %{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'dashboard, with credentials -> HTTP %{http_code}\n' -u "admin:$PW" http://127.0.0.1/
curl -s -o /dev/null -w 'healthz (anonymous probe)   -> HTTP %{http_code}\n' http://127.0.0.1/healthz

Expected output:

dashboard, no credentials   -> HTTP 401
dashboard, with credentials -> HTTP 200
healthz (anonymous probe)   -> HTTP 200

/healthz is intentionally anonymous so a load balancer or uptime monitor can probe the instance without credentials. It returns only the string ok and exposes nothing.

Step 7 - Confirm the scanner is discovering devices

WatchYourLAN scans the interface it detected at first boot and records everything it sees. Query the discovered inventory through the authenticated REST API:

PW=$(sudo awk -F= '/^WATCHYOURLAN_PASSWORD=/{print $2; exit}' /root/watchyourlan-credentials.txt)
echo "scanning interface: $(grep IFACES /var/lib/watchyourlan/config_v2.yaml)"
curl -s -u "admin:$PW" http://127.0.0.1/api/all \
  | python3 -c 'import sys,json; d=json.load(sys.stdin); print(f"devices discovered: {len(d)}"); [print(" -", h["IP"], h["Mac"], h["Name"]) for h in d]'

Expected output (your devices will differ - these are whatever is reachable on your subnet):

scanning interface: IFACES: "ens5"
devices discovered: 2
 - 172.31.80.1 12:33:aa:d2:49:03 ip-172-31-80-1.ec2.internal.
 - 172.31.90.251 12:20:66:a0:ce:63 ip-172-31-90-251.ec2.internal.

A freshly launched instance in a quiet subnet may show only the subnet router. That is expected: WatchYourLAN can only see what is reachable at layer 2 from its interface (see Step 8 to widen the view). The count grows as it discovers more of the network it is attached to.

Step 8 - Open the dashboard

Browse to http://<instance-public-ip>/ and sign in with admin and the password from Step 5. The dashboard is the device inventory: one row per host, showing its name, interface, IP, MAC, hardware vendor, when it was last seen, whether you have flagged it as Known, and whether it is currently Online.

Step 9 - Inspect a device

Click a device's IP to open its detail view. Here you see everything WatchYourLAN knows about the host, run an on-demand port scan against it, send a Wake-on-LAN packet, or remove it from the inventory.

Step 10 - Curate your inventory

Use Edit on the dashboard to switch into management mode. You can rename hosts to something meaningful, tick the Known flag on devices you recognise so unfamiliar newcomers stand out, and bulk-remove stale entries with Delete selected. Flagging your known devices is what turns WatchYourLAN into an early-warning system: once the machines you expect are marked Known, anything unmarked is something new on the network.

Step 11 - Review the settings

Select Config to review the active settings. This confirms the secure-by-default posture at a glance: Host is 127.0.0.1 and Port is 8840, so the application is bound to loopback and only reachable through the authenticating nginx proxy. From here you can also enable optional integrations - push notifications via Shoutrrr, or metrics export to InfluxDB and Prometheus.

Step 12 - Widen the scan to an on-premises network

To inventory devices that are not on the instance's own VPC subnet - for example the machines in your office or data centre - give the instance a layer-2 reachable path to that network and point WatchYourLAN at the corresponding interface. In practice that means terminating a VPN or overlay (WireGuard, an AWS Site-to-Site VPN with a software router, ZeroTier, and similar) on the instance, then setting the IFACES value in the config to that interface.

Edit the scanner's interface list on the instance (this is a customer change - run it yourself when you are ready, then restart the service):

$ sudo sed -i 's/^IFACES:.*/IFACES: "wg0"/' /var/lib/watchyourlan/config_v2.yaml
$ sudo systemctl restart watchyourlan

Remember that ARP does not route: WatchYourLAN will only ever see devices in the same broadcast domain as the interface it scans, so the network you attach must be bridged/routed to the instance at the link layer, not merely reachable over IP.

Step 13 - Rotate the dashboard password

The password is generated per instance, so you rarely need to change it - but if you want to set your own, replace the nginx Basic Auth entry (this is a customer change; run it yourself):

$ sudo htpasswd -B /etc/nginx/.watchyourlan.htpasswd admin
New password:
Re-type new password:
$ sudo systemctl reload nginx

The username stays admin. The credentials file in /root still shows the original generated password after this, so note your new one separately.

Security

• The dashboard is authenticated and loopback-bound. WatchYourLAN listens only on 127.0.0.1:8840; nginx is the only thing exposed, and it requires the per-instance password. Keep it that way - do not reconfigure the app to bind 0.0.0.0.
• Scope the dashboard with your security group. A network inventory tool reveals your topology. Restrict 80/tcp to your own address ranges rather than 0.0.0.0/0, and consider fronting it with TLS (a load balancer or a reverse proxy with a certificate) if you reach it across untrusted links.
• The image ships no scan data and no known password. The build wipes the SQLite store and the Basic Auth file before capture; your instance generates a fresh empty database and a fresh password on its first boot.
• Keep the base patched. Unattended security upgrades are enabled; apply WatchYourLAN releases as they ship.

Maintenance

• Service control: sudo systemctl restart watchyourlan and sudo systemctl restart nginx.
• Logs: journalctl -u watchyourlan -f follows the scanner; sudo tail -f /var/log/nginx/access.log follows the proxy.
• Data: the SQLite store lives at /var/lib/watchyourlan/scan.db; back it up if you want to preserve discovered-device history across a rebuild.
• Scan interval and interface: both live in /var/lib/watchyourlan/config_v2.yaml (TIMEOUT and IFACES); restart the service after editing.

Support

cloudimg provides 24/7 technical support by email and chat. We help with deployment, scoping the scan to the right subnet, bridging on-premises networks over a VPN, rotating credentials, and upgrade planning.

All product and company names are trademarks or registered trademarks of their respective holders. WatchYourLAN is published under the MIT License. Use of the name identifies the software and does not imply affiliation with or endorsement by the WatchYourLAN project.