lanowl

Setting it up

Devices: inventory.yaml

Every device lanowl watches is described once, in config/inventory.yaml: how it is watched, how much it matters, and what lanowl may do with it besides watching. An address that is not in the inventory is never probed, and the model's tools refuse it too.

The dashboard writes it too: the first-run setup picks devices from your router's DHCP list, and Settings โ†’ Devices adds and changes them one by one (Settings).

groups:
  network: {majority_down_critical: true}
  cameras: {majority_down_critical: true}
  servers: {majority_down_critical: false}

devices:
  - ip: 192.168.88.10
    name: "Home server"
    group: servers
    criticality: critical
    kind: linux
    credentials: server
    manage: [logs, updates, upgrade, reboot, restart, config, security, backup]
    restart: {units: [mosquitto]}
    checks:
      - {type: icmp}
      - {type: tcp, port: 22}
      - {type: tcp, port: 1883, name: "MQTT"}

Watching needs only ip, name and checks. Everything from kind down is optional.

Watching

Field What it does
ip The address lanowl probes.
name What every message and the dashboard call it. You can rename a device on the dashboard too; the inventory's name is kept underneath.
group Devices that share fate: a switch's cameras, the servers. Groups decide what counts as one incident.
criticality How much it matters: critical, high, warning, low or info. See below.
checks How it is watched. A device is up while any of its checks answers. Default: one ping.
mac Its MAC address. A device that DHCP moves to another address is followed.
depends_on The address of what it is reached through, or wan. When that is down, this one is not a second alert: the parent's names it.
expect_offline sun: off at night by design (solar gear). day: off in daylight (a dusk-to-dawn light). Needs site.lat and site.lon.
debounce_fails Misses in a row before it is down, for this device alone (default cadence.debounce_fails, 2). A site behind a tunnel wants 5.
role ap: rebooting it holds the alerts of the devices on its Wi-Fi. wan-gateway: never rebooted while the internet runs through it. Anything else is a label on the device's sheet.
note A line shown on the device's sheet.

Criticality

Criticality When it goes down
critical A ๐Ÿ”ด alert at once, and a ๐ŸŸข when it is back.
high Reported in the next digest, once.
warning Reported in the next digest, once.
low, info Mentioned once in the next digest. Never makes the network "degraded".

A device that answers but whose named service check fails (degraded) is a warning. More in How alerts work.

Checks

Check What it asks Options
{type: icmp} A ping. timeout_ms, count
{type: tcp, port: 22} Does the port accept a connection? port, timeout_ms, name
{type: http, port: 80} Does / on that port answer? Any reply below 500 counts, a login page included. HTTPS on ports 443 and 8443. port, timeout_ms, name
{type: snmp} An SNMP read of its uptime. A failed SNMP read never makes a device degraded. community
{type: arp} The router ARP-pings it: is it on the wire? For gear that ignores ping and listens on no port. Needs the MikroTik API and the test policy. iface (default bridge-lan), count
{type: link, iface: ether5} Is the router port it hangs off up? The fastest honest signal for a device on its own port. Needs a MikroTik. iface
{type: lease} Does it hold a DHCP lease on the router? Slow: a lease outlives the device by hours. The last resort. Needs mac.

A check with a name is a service: it gets its own line on the dashboard, and when it fails while the device answers, the device is "degraded" rather than down.

A device on weak Wi-Fi is better given patience than taken out of monitoring: more time and more pings, {type: icmp, timeout_ms: 2500, count: 3}, turn a 30% loss into an answer.

Groups

groups:
  cameras: {majority_down_critical: true}

With majority_down_critical, more than half of a group going dark at once is one ๐Ÿ”ด alert about the group ("suspect a single upstream cause"), not one message per device. Devices explained by a depends_on parent do not count towards the majority.

depends_on

  - ip: 192.168.88.21
    name: "Cam Front door"
    depends_on: 192.168.88.2      # the PoE switch

When the PoE switch is down, its cameras are still drawn down on the dashboard, but they are not alerts of their own: the switch's alert says "dark with it: Cam Front door, โ€ฆ". A device behind the internet (a VPS) takes depends_on: wan. Chains work: a remote site's camera depends on the site's router, which depends on the VPS that carries the tunnel.

Managing

What lanowl may do with a device besides watching it, each only where its kind can, and only with a login in secrets.yaml:

    kind: linux                   # what it is
    credentials: server           # its login, by name, in secrets.yaml
    manage: [updates, reboot, restart, backup]
    restart: {units: [mosquitto]}
Feature What lanowl does Switched on by
logs Reads its own log every hour; the owl tells what is not routine (MikroTik, OpenWrt, ESXi, UniFi, Linux). A Linux machine by lanowl's key: its auth log every two minutes too, with hostlog.enabled devwatch.enabled (on unless switched off)
updates Checks its updates every morning updates.enabled
upgrade May propose installing them actions.enabled
reboot May propose a reboot actions.enabled
restart May propose restarting one of its listed services actions.enabled
config Tells what changed in its configuration configwatch.enabled
security Reviews what it exposes, every day exposure.enabled
backup Backs it up, monthly and before updates backups.enabled

Anything that changes a device is only ever a proposal that you approve. Which kind can do what: Device kinds and features. A kind lanowl does not know is a YAML file of your own: Device kinds of your own.

Feature options

A feature's options sit under its own name on the device:

    restart: {units: [mosquitto, jellyfin]}     # what it may restart, and nothing else
    backup:  {paths: [etc, home]}               # what a backup by password takes
    reboot:  {risk: "the cameras record to it", hold_min: 10, also_hold: [192.168.88.21]}
    upgrade: {risk: "the internet is down while it installs", hold_min: 12, also_hold: [wan]}
    logs:    {public: true, about: "the VPN hub on the internet", trusted: ["10.8.0.0/24"]}
Option Meaning
restart.units The systemd units it may restart. Nothing else can be restarted.
backup.paths What a Linux machine's backup copies. Required over a password login; over lanowl's key a default list of configuration paths is used. In the dashboard it is the backup: paths field of the device form, shown once backup is ticked.
reboot.risk, upgrade.risk A line shown with the proposal: what you lose while it runs.
hold_min How long its alerts are held while it restarts (default 5 minutes).
also_hold Other addresses held with it, or wan for the internet.
reboot.ha_button Reboot it by pressing a Home Assistant button entity, such as its smart plug's.
logs.about A sentence for the owl about what this machine is.
logs.public It is on the internet: the scanners' constant knocking is filtered out. Linux by lanowl's key, in the two-minute auth log (hostlog).
logs.trusted Networks a login may come from without being news. Linux by lanowl's key, in the two-minute auth log (hostlog); the hourly read of the other devices leaves logins to the owl.

A reboot through a Home Assistant button works for any device, but it still needs a kind (generic is enough), manage: [reboot], and Home Assistant's address and token (access.ha_url, tokens.homeassistant):

  - ip: 192.168.88.23
    name: "Cam Garage"
    kind: generic
    manage: [reboot]
    reboot: {ha_button: button.garage_cam_plug_restart}
    checks: [{type: icmp}]

Scanning its ports

scan needs no kind and no login: may lanowl scan this device's ports? It decides the monthly vulnerability scan (nmap asks which software answers, on every site) and the owl's own port scans. The setup asks it for each device you pick (off for cameras, smart-home gear and phones, on for the rest); a device's settings change it later.

    scan: false                   # some cheap cameras and smart plugs hang under a version scan

Without scan, the device follows its group: the groups in updates.scan.deny_groups (security and iot by default) are left out, the rest scanned. lanowl's own machine and an address on none of your sites' networks are never scanned. More in Updates, backups and the security review.

Devices you add from the dashboard

Once lanowl reads a router's DHCP, the dashboard lists the devices on each site's network that nobody watches. Watch writes one into this file, with its MAC so lanowl follows it when DHCP moves it, and pings it at once. Known marks one as belonging there. Settings โ†’ Devices adds any device by hand, and asks for its login right there: a user and a password, or lanowl's ssh key.

Checking it

lanowl --check reads this file the way a start does and lists, per device, each feature as โœ“ on, โ—‹ switched off in config.yaml, or โœ— cannot, with the reason. A change of kind, manage or login type takes a restart; a changed password does not.

Edit this page on GitHub.