Both read through the shared HTTP helper but were missing from the web list of inspectable kinds, so no Inspect button showed. Home Assistant's reader was named listEntities, which the inspect route doesn't recognise; it now also answers to read. Test and INTEGRATIONS.md updated. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
119 KiB
Integration & DNS provider access requirements
What credential to create in each target system, and the minimum access it needs, when adding an integration or DNS provider in Homelab Manager (Integrations → Add integration, or DNS → Add provider). All credentials are entered in-app and encrypted at rest — nothing is read from environment variables.
Every adapter listed here except UniFi, Nginx Proxy Manager, Home Assistant and the UPS performs write actions (starting/stopping things, editing DNS records, etc.), not just reads — a read-only credential will fail as soon as you use one of those actions, even if the dashboard views themselves load fine. (UniFi, Nginx Proxy Manager, Home Assistant and the UPS only ever read.)
Integrations
Reading one now
Every integration has a Read now button on the Integrations page (operators and administrators; the pages of Media managers, Download clients, Hetzner Robot, Hetzner Cloud, Game servers, AdGuard Home, Technitium DNS, Grafana and Speedtest Tracker have it too, on each card). POST /api/integrations/{id}/read-now answers { kind, ok, error, at, latencyMs }:
kind: "stored"— the integration has a reading that is kept (everything but the ones below): it is read the way its schedule reads it, stored, and the alerts are worked out again at once. A read that fails says why and leaves what was stored as it was.kind: "live"— Proxmox, Synology, Tailscale, Gitea, Semaphore, Uptime Kuma, Proxmox Backup Server, osTicket, phpIPAM and Nginx Proxy Manager keep nothing: their pages and the health pass read them live every time. Here it asks whether the integration answers (the question Test asks, with what is saved) and brings its Working/Failing mark up to date; the alerts, which read it live, are worked out again at the next look.- Not too often: the same integration is not read again within 20 seconds (HTTP 429,
Retry-After) — some systems limit how often they may be asked. One that is switched off cannot be read (HTTP 400); one that is not there is a 404. - Which kinds have a stored reading is one list in
server/src/services/integrationSyncs.ts, which also decides what happens when an integration is added, changed (a new address or credentials, or switched on) or deleted: it is read at once, and what was read is forgotten on delete. A new kind with a schedule is added there.
History of the figures
The numbers an integration reports — queries a day and how many were blocked (AdGuard Home, Technitium), items in the queue and wanted-but-missing (Sonarr, Radarr, Prowlarr), download and upload speed (qBittorrent, SABnzbd), photos, videos, library size and disk (Immich), documents and the inbox (Paperless-ngx), users, files and free space (Nextcloud), devices and addresses (NetBox), failed runs (n8n), rules firing (Grafana), targets down and alerts (Prometheus), failed sign-ins (Authentik), the library (Jellyfin) and the estimated monthly cost and server count (Hetzner Cloud) — are kept over time, so a page can show how a figure has moved instead of only what it is now. Each of those pages has a Show the history button on every integration's card: a small chart for each figure with where it stands, how it changed over the stretch (up 2,398, down 1.5 points), its lowest and highest, over 24 hours, 7, 30 or 90 days or a year.
- How: every five minutes the stored reading of each enabled integration (the one its sync already keeps) is looked at, and about every quarter of an hour a reading of each figure is kept — for five weeks; beyond that its hours (four months) and days (about two years) as an average with a lowest and highest, the way the servers' trends are kept. Nothing is asked of the integration for this.
- A gap is a gap: a reading that is more than 45 minutes old (the integration could not be read) is not recorded, so a stretch when it was unreachable is empty on the chart, not a flat line. A figure the integration could not give — a number that is null, not zero — is left out.
- Not covered: the integrations that already keep a history of their own (UPS, Home Assistant, speedtest, who is streaming from Jellyfin, the storage of Proxmox and Synology) and those that are only read live when a page is opened (Proxmox, Synology, Tailscale, Gitea, Semaphore, Uptime Kuma, Proxmox Backup Server, osTicket, phpIPAM, Nginx Proxy Manager): there is nothing stored to take figures from. Asked for history of one of those, the endpoint says
kept: false. - Starting: history begins when this was added; nothing is made up for the time before. A figure appears after its first reading.
- API:
GET /api/integrations/:id/figures?days=7(any signed-in user; 1 to 365 days) answers{ kept, days, figures: [{ key, label, unit, latest, readAt, points, first, low, high }] }. The extractors, one for each kind, are inserver/src/services/integrationFigures.ts.
Checking what an integration can read
On the Integrations page an administrator has an Inspect button on each integration that reads through the shared HTTP helper (Authentik, Immich, Jellyfin, NetBox, Nextcloud, Paperless-ngx, Prometheus, Hetzner Cloud, Hetzner Robot, Speedtest Tracker, Fragnet, Sonarr, Radarr, Prowlarr, Lidarr, Readarr, qBittorrent, SABnzbd, AdGuard Home, Technitium DNS, Grafana, n8n and Home Assistant). It runs the integration's reader once and shows:
- what was asked — each request, its path (with the names of the query parameters, not their values), the status, how long it took and how many bytes;
- what came back — the shape of each JSON answer to three levels: the names of the fields and the kind of each (
string,number,array(12) of { … }), with a?on a field that only some items of a list have. Never a value, never a token, so the report can be copied into a message; - what the reader made of it, in the same way, and where that is empty — a field that is null, an empty text, an empty list, or null in every item of a list. A reader that expects a field the system names differently ends up here.
It is for the readers written from documentation (see "Not verified" on each integration): put what came back beside what is empty and a mismatch is plain. Something being empty is often right — no containers, nothing wrong — so it is a list to look at, not a verdict. Each inspection is in the audit log; nothing is stored. Only an administrator can run it, and it times out after 90 seconds.
Tailscale
- Config fields: Tailnet, API key
- Auth: Bearer token against
api.tailscale.com - Actions used: list devices, remove a device, authorize/deauthorize a device
- Required access: An API access token (or OAuth client) with Devices Core: Read + Write — create one under the admin console → Settings → Keys. Read-only isn't enough since remove/authorize are write calls.
Proxmox VE
- Config fields: Proxmox URL, API token ID, API token secret, allow self-signed certificate
- Auth:
PVEAPIToken=<tokenId>=<tokenSecret>header - Actions used: list nodes/VMs/LXCs, read guest config and live status, read node host stats and storage usage, start/stop/reboot/shutdown a guest, list, take, roll back to and delete a guest's snapshots, read backup job schedules and recent
vzdumptask history - Required access: A dedicated API token (Datacenter → Permissions → API Tokens) with a role granting VM.Audit + VM.PowerMgmt (e.g.
PVEVMAdmin) on the VMs/LXCs to manage, plus Sys.Audit and Datastore.Audit on the node(s) for the host CPU/RAM/storage cards to populate. A token scoped to VM management only will still work for the guest list and power actions — it'll just show an error on the per-node hardware card instead of failing outright. Backup job schedules and run history need that same Sys.Audit — no separate permission to grant if the node-stats card already works. - Snapshots (Infrastructure → Proxmox → click a guest → Snapshots): everyone signed in sees a guest's snapshots (oldest first, a branch indented, with memory marked); an operator can take one (a name — or one made from the time,
hlm-YYYYMMDD-HHMMSS— a description, and for a running VM whether to keep its memory so a rollback brings it back running); rolling back and deleting are an administrator's, each behind a confirmation, because a rollback throws away everything the guest has done since and Proxmox removes the snapshots taken after the one chosen. Proxmox does each as a task: the page waits up to 20 s and says how it went, or that it is still going and looks again. Every one is in the audit log and the change log (A snapshot was taken of guest 100 on pve1). The token needs VM.Snapshot (take, delete) and VM.Snapshot.Rollback (roll back) as well as VM.Audit — thePVEVMAdminrole has them; a token without them lists the snapshots and gets Proxmox's own refusal when it tries the rest. Checked against Proxmox's published API description and a pretend Proxmox, not a live host. - Notes: self-signed certificates are supported via the "Allow self-signed certificate" checkbox — common for an internal PVE host. An address that says
http://(a reverse proxy in front of Proxmox) is spoken to over plain HTTP.
Synology DSM
- Config fields: Synology DSM URL, Username, Password, allow self-signed certificate
- Auth: DSM session login (
SYNO.API.Auth), session id reused until it expires - Actions used: read-only — storage/volume/disk health, system info, network info. No writes.
- Required access: A DSM user account that can view Storage Manager and System Information (a regular admin-group account is simplest; a dedicated read-only user works too since nothing is ever changed). 2FA/OTP on the account is not supported — use an account without it enabled, or DSM's application-specific password if your setup requires 2FA elsewhere.
- Notes: works over plain HTTP or HTTPS depending on the URL you enter; self-signed certs supported.
Semaphore (Ansible Semaphore / Semaphore UI)
- Config fields: Semaphore URL, API token
- Auth: Bearer token
- Actions used: list projects, list templates, run a template (creates a task — optionally with a
limitof hosts and a note saying who started it from Homelab Manager), read a task's status - Required access: A user API token with access to every project you want visible, and permission to run templates in those projects — a viewer/guest-level project role can list templates but will fail on "Run", so the account needs at least the operator-equivalent role Semaphore's own project permissions define.
Gitea
- Config fields: Gitea URL, API token
- Auth:
Authorization: token <token>header - Actions used: list repos, list Actions workflow runs, re-run failed jobs in a run
- Required access: A personal access token with
reposcope (read access to repos, including private ones you want tracked) and Actions read/write — generate it under the account → Settings → Applications → Generate New Token, with therepositoryandwrite:repository/Actions permission groups enabled (exact grouping depends on your Gitea version's token scope UI). Read-only Actions access isn't enough since re-running jobs is a write call.
Dockhand
- Config fields: Dockhand URL, API token
- Auth: Bearer token against Dockhand's own API
- Actions used: list environments/containers, check for image updates, start/stop/restart a container
- Required access: A Dockhand API token belonging to a user with access to every environment (Docker host) you want visible, with permission to start/stop/restart containers and trigger update checks in each — not just view them.
- Suggested checks: each container's image and published ports are also used to suggest an endpoint check on the app's own health address (MONITORING.md). Ports are read from whatever shape Dockhand's container list carries them in (Docker's own,
"0.0.0.0:8080->80/tcp"strings or inspect's map) — not checked against a live Dockhand; if none is read, the Docker host's listening ports from its agent stand in. - Container health: on the 15-minute health pass the app also reads every container's state and status text and raises alerts for what is broken — see Docker containers that are broken. A Docker host that Dockhand cannot read (its Hawser agent is down) is an alert too, and its containers' alerts are held, not cleared. The Docker page shows each container's problem and has a Leave alone button.
- Vulnerability scans: every fifteen minutes the app also reads what Dockhand's scans have stored —
GET /api/vulnerabilities/count?env=for each environment, andGET /api/vulnerabilities?env=&severity=critical&limit=100only where that count is above zero (needs the images: view permission). Nothing is scanned from here. Critical findings are a warning per Docker host — and so are high ones once a host has as many as a number you set (Also warn when a Docker host has this many high vulnerabilities, off by default) — (a setting turns the critical one off — see MONITORING.md); the Docker page lists them. Written from Dockhand's source and OpenAPI file, not tried against a live Dockhand — its published docs show the lists at the top level of the answer, its code puts the counts undersummary; the reader follows the code and reads nothing it does not find as unknown. - Image age: the same pass reads each Docker host's images and containers (
GET /api/images?env=,GET /api/containers?env=&all=true) and keeps, for every image a running container uses, when it was built (Docker's ownCreated). Matched by the name the container gives (Docker Hub'sdocker.io/library/and a missing:latestare not a difference) or by id. With Warn about running Docker images that were built more than … days ago set (Settings → Notifications; off by default), a host with such images is a warning — whatever the scans of them said. The Docker vulnerabilities view shows each host's oldest running images either way. Written from Dockhand's documented list (Id,RepoTags,Created), not tried against a live Dockhand; an image whose date cannot be found is not judged.
Uptime Kuma
- Config fields: Uptime Kuma URL, username (leave blank — see below), API key, and the optional Login username and Login password (for mirroring maintenance windows) with a checkbox to keep maintenance windows in step with Uptime Kuma's schedule
- Auth: HTTP Basic, with the API key as the password and the username left empty. Uptime Kuma has no
conventional REST API — the dashboard talks to it over Socket.IO — so this integration reads its
Prometheus-metrics endpoint (
GET /metrics) instead and parses that. On installs from before the API-key feature existed (Uptime Kuma < 1.23), that endpoint instead checks your real dashboard login, so put your Uptime Kuma username and password in those two fields rather than leaving the username blank. - Required access: In Uptime Kuma, go to Settings → API Keys → Add API Key, and paste the value it shows you (once — it isn't shown again) into this integration's "API key" field. No other permission is needed; the metrics endpoint is read-only.
- What you get: every monitor's status (up/down/pending/maintenance), response time, uptime over 24 hours/30 days, and certificate days remaining where applicable. A monitor is linked to one of your servers when its target — an IP, or a TCP/HTTP hostname — matches that server's own address or hostname; monitors with no single network target (groups, push monitors, keyword checks with a complex URL) are shown unmatched rather than guessed at. Uptime Kuma's tags aren't read, since the metrics endpoint doesn't reliably distinguish a tag from any other label.
- Maintenance import ("Import now"): the Maintenance page can read which monitors are currently in maintenance in Uptime Kuma and start (or extend) a maintenance window here for the matching server, for a duration you pick — the metrics endpoint only exposes current status, not a window's schedule.
- Maintenance schedule ("Sync schedule"): Uptime Kuma shares its maintenance windows only over the live
Socket.IO connection its own dashboard uses, and that connection takes a login username and password —
an API key is not accepted there. Fill in the optional Login username and Login password on the
integration to use it. Be aware that a Uptime Kuma login can change anything in Uptime Kuma (it has no
read-only accounts), so create a dedicated account for this. An account with two-factor authentication
cannot be used. The password is stored encrypted like every other credential here, and is used for nothing
but this. The login is sent as Uptime Kuma's own
loginevent overws://orwss://to the same address as the integration, so use anhttps://address if it crosses anything but a trusted network.- For each window Uptime Kuma reports (its running time slot and the next one), the app finds the monitors it covers and matches each monitor's address to something here: a server (the monitor's host is one of its IP addresses, its hostname or its short name — the same matching the Uptime Kuma page uses), an integration or a DNS provider (the monitor's host is the host of the address it was added with, as the same name or the same IP). It then makes a maintenance window on each match. A window that hasn't started shows as Scheduled and silences nothing yet.
- Matching is exact. Nothing is worked out through DNS, so a website that only resolves to the same address
as a reverse proxy does not put the proxy into maintenance. A monitor that matches nothing is listed in the
result as
name (address)so you can see why. The usual cause is that Uptime Kuma watches a thing by a different address than the one it was added with here (a Proxmox host added by its LAN address but monitored over Tailscale). Add that address under Address aliases on the Maintenance page, saying which server, integration or DNS provider it belongs to; matching stays exact, and an alias applies to every sync. Monitors that are not in Uptime Kuma's metrics (paused ones) and hosted services outside your network can't be matched and are left alone. - A window on an integration silences that integration's alerts, including "integration down" for that type of service — see the Maintenance page for the full list.
- Tick Keep maintenance windows in step with Uptime Kuma's schedule to run this automatically every 15 minutes. Without it, the Sync schedule button does the same once.
- Windows are capped at 31 days, and only slots starting within two weeks are mirrored. A window Uptime Kuma holds in maintenance "until switched off" (the manual kind) is mirrored 45 minutes at a time and renewed on each pass, so it lapses by itself if Uptime Kuma becomes unreachable.
- A window you end or cancel here is not brought back by a later sync. One that is removed or switched off in Uptime Kuma is removed here (a running one is ended at once).
- Monitors that match no server (groups, push monitors, hosts the app doesn't know) are listed as unmatched in the result and silence nothing. A window on a group monitor does not extend to its children here.
- Verified against the Uptime Kuma 1.23 and 2.0 source and against a stand-in server speaking the same protocol; not yet run against a live Uptime Kuma.
Duplicati
Duplicati is different from the other integrations: this app never calls Duplicati, and no password for it is kept. Duplicati can tell a URL how each operation went (its own send-http-url option), so each machine running it is a source with a secret address, and its reports come in.
That works on every Duplicati version, needs no login handshake and leaves nothing to leak from this side.
-
Set up (Backups → Duplicati → Add a machine, administrators): give the machine a name and, if you like, the server it runs on. You are shown, once, an address of the form
https://<this app>/api/duplicati-report/hlm_d_…and the three options to add in Duplicati under Settings → Default options → Advanced options (so every job on that machine reports):--send-http-url=https://<this app>/api/duplicati-report/hlm_d_… --send-http-result-output-format=Json --send-http-level=Allsend-http-level=Allmatters: by default Duplicati only reports problems, and a backup that quietly stops reporting could not be told from one that works. The plain-text format is also read, but JSON carries the name of the job and the figures reliably. How Duplicati posts it does not matter: by default it sends a form-encoded body (message=<the text, URL-encoded>, the message beginning "Duplicati Backup report for "), which is unwrapped — the field may have another name (send-http-message-parameter-name) and have others beside it; the text or JSON posted as the body as it is (send-http-json-urls, a message set by hand) is read too. The job's name and the operation are taken from that first line when the result does not say them. In the text form the warnings and errors are read from theirWarnings: [ … ]andErrors: [ … ]lists. For one job only, add the same options to that job's advanced options instead. -
What is read from each report: the operation (only Backup counts — a compact, repair or test is set aside), the result (
Success,Warning,Error,Fatal), the job's name, when it began and ended, the duration, the size of what was examined, the files added, changed and deleted, the number of warnings and errors, the first message and what the warnings said (JSON format only; up to twenty, each cut at 500 characters, kept with the run). A job is learned from its first report, by name; the same name on another machine is another job. -
The address is the access. It is a long random token (stored only as a SHA-256 hash, shown once); all it allows is to say how a backup went. It answers a wrong token with "not found", limits requests per address, and takes POST or PUT. Removing the machine ends it.
-
Not verified against every Duplicati version — the report fields are read defensively from Duplicati's published output (the results at the top or under
Data, the job's name amongExtra). A report the app cannot read is answered "OK (not a report this app can read)" and the page does not learn from it. -
Why a machine has no jobs. "Last heard" only says something arrived on the address. Each machine's card on the page also says what the last report was — a backup (with the job and how it ended), another operation that was set aside (compact, repair, test … only a Backup makes a job), or one that could not be read with the reason (no
ParsedResult, not valid JSON …) — and how many of each have come since the machine was added. Administrators can open What was sent to see the first 600 characters of an unreadable report, to see its form; others see the reason but not the text. A machine with no job yet and only set-aside reports is told to check--send-http-level=All. -
Warnings in a row. One run with warnings is common; the page and an alert say when the last three runs in a row all finished with warnings (Warnings 4 runs in a row; alert key
duplicati-streak:<job>). It is on for every job and a button turns it off for one that always has a few (Stop streak alerts); it is not raised for a job that already alerts on every warning run, nor for one that has failed or is overdue (their own alerts say that). -
How much room the backups take. Duplicati says how big the backups are where they are kept (
BackendStatistics.KnownFileSize) and, for some kinds of storage, how much room there is (TotalQuotaSpace). Both are read (the plain-text form too) and the size is kept with every run. The Stored column on the page shows it with the growth over the last 180 days — +3.4 GB a month, not growing, size goes up and down — only once there are five readings over a week, and nothing is claimed from less. Where the room is known it also says full in about N days, and when that is within the disk forecast window (Settings → Alerts, 14 days by default; 0 switches it off) and the growth is steady (a straight line fits at least 0.8) it is an alert (duplicati-growth:<job>; critical at three days or less). A storage that does not say how much room it has is never forecast to fill: the growth is shown, nothing more. Compacting makes the size drop now and then, which lowers the fit and keeps a jagged size from raising a false alarm. -
What it does with them — alerts,
/metrics, the history — is in MONITORING.md.
Proxmox Backup Server
- Config fields: Proxmox Backup Server URL, API token ID, API token secret, allow self-signed certificate
- Where it shows: Backups → Proxmox backups → Proxmox Backup Server tab, next to the Backup coverage tab (
/backups?view=pbs; the old/pbsaddress goes there). - Auth:
PBSAPIToken=<tokenId>:<tokenSecret>header — note the colon between the token id and secret; Proxmox VE's own token header uses=there instead, so a PVE token/secret pair copied verbatim into this integration's fields will still format correctly (the adapter supplies the colon itself) as long as the id/secret values themselves are right. - Actions used: read-only — list datastores and their usage, read every stored snapshot's verification status, read the PBS host's own CPU/RAM/disk. No writes; nothing here can prune, delete, or re-verify a backup.
- Required access: A dedicated API token (Configuration → Access Control → API Token) belonging to a user with
Datastore.Audit on the datastore(s) to show, and Sys.Audit for the node status card to populate. A token
scoped to just
Datastore.Auditon one datastore will still work — other datastores it can't read are shown with an error rather than failing the whole page. - What you get, and why it's separate from the Proxmox VE integration: Proxmox VE (the "Proxmox" integration
above) already shows whether the last
vzdumppush to PBS succeeded, but has no visibility at all into PBS's own backup verification — whether the data PBS actually stored still passes an integrity check, run separately by PBS's verify jobs. This integration reads that directly from PBS (verification.stateon each stored snapshot), and a daily check (mirroring the Proxmox backup-failure check) sends a notification when a snapshot has failed verification or a datastore couldn't be read at all — the "Notify on" section in Settings → Notifications has a dedicated toggle for it, sharing the same daily reminder time as the other daily checks. - Not verified against a live instance — built from PBS's own published API documentation (endpoints, the
PBSAPITokenheader format, and the datastore/snapshot field names all cross-checked there), but nobody has run it against a real Proxmox Backup Server yet. If a datastore comes back empty or with the wrong fields, tell us what your instance actually returned and we'll adjust.
osTicket
- Config fields: Database host, Database port (optional, default 3306), Database name, Database username,
Database password, Table prefix (optional, default
ost_— only needed if you changed it at install time) - Auth: a plain MySQL/MariaDB connection (host/port/database/username/password) — not HTTP, and not osTicket's own API.
- Why this one reads the database directly: osTicket's official REST API only supports creating tickets
(
POST /api/tickets.json) — there is no documented endpoint to list or read existing ones (osTicket's own developer docs say as much: "For now, only ticket creation is supported..."). Listing tickets therefore means reading osTicket's own MySQL/MariaDB database directly, the same way osTicket's own admin panel does internally. This makes it the only integration in this app that isn't a REST API. - Actions used: read-only — a single
SELECTjoining the ticket, status, priority, department, staff, team, and requester tables for every ticket whose status is in the "open" state. Nothing in this part can create, update, or close a ticket — opening tickets is the separate, optional API described below. - Required access: a MySQL/MariaDB user with read-only (
SELECT) access to the osTicket database only — never reuse osTicket's own application database user, which has full read/write access. Create one with something like:(narrow the host part —CREATE USER 'homelab_manager'@'%' IDENTIFIED BY 'a-strong-password'; GRANT SELECT ON osticket.* TO 'homelab_manager'@'%'; FLUSH PRIVILEGES;'%'— to this app's actual server address if your MySQL/MariaDB setup allows it, and make sure the database's own network/firewall rules allow that connection in the first place; this integration connects over plain TCP, unencrypted, so it's meant for a same-host or same-LAN database, not one reachable over the internet). - What you get: every currently-open ticket's number, subject, status, priority, department, assigned staff member or team (or "Unassigned"), requester name/email, source, created/last-activity/due dates, and two flags osTicket already tracks natively — overdue and awaiting our reply (i.e. the customer replied last and nobody on staff has answered yet) — which are the two things most worth a glance on a dashboard.
- A reliability note on subject/priority specifically: those two fields aren't columns on osTicket's main
ticket table — osTicket normalizes them into its dynamic custom-fields system, and reads them back here from
ost_ticket__cdata, a cache table osTicket's own admin panel also uses for ticket lists (faster than joining the generic form-fields tables). osTicket's own GitHub issue tracker documents that cache occasionally going stale or briefly missing right after a custom-field change; this integration's query is written so a ticket with no matching cache row still shows up in the list, just with an empty subject/priority instead of being silently dropped. - Not verified against a live instance — built from osTicket's own published database schema and developer
docs (table/column names, the ticket status
stateclassification, and the cdata-cache mechanism all cross-checked there), but this could not be run against a real osTicket database in this environment either (no MySQL/MariaDB server was available to test against). If a query comes back empty, errors on a missing column, or a field looks wrong, tell us what happened and we'll adjust — this one has had less real-world exposure than every other integration listed here.
Optional: opening tickets for alerts (Alert settings → Alert tickets)
- Config fields: Ticket API address (optional), Ticket API key (optional, stored encrypted like the database password), Allow self-signed certificate (ticket API). Leave them empty and the integration works as before.
- Auth: osTicket's own HTTP API:
POST <address>/api/tickets.jsonwith the key in anX-API-Keyheader. - Make the key in osTicket: Admin Panel → Manage → API Keys → Add. Tie it to the IP address osTicket sees this app's requests come from (behind Docker or a reverse proxy that is the host's or proxy's address, not the container's — check osTicket's log if it refuses) and tick Can create tickets. osTicket refuses a key from any other address, which is the most common reason a test ticket fails.
- What is sent: one ticket per problem — name and email you set under Alert settings → Alert tickets, a subject, the
problem's text and a link back to this app, optionally a help topic and priority id — with
autorespondoff (the "user" is this app, so an acknowledgement would only bounce) and osTicket's own staff alert on or off as you choose. - What the API can't do: close, reopen, or comment on a ticket — osTicket's API has no such endpoint. Closing one is a separate, optional thing, described next, and it does not use the API.
- Checked against a real osTicket for a test ticket (the API key with its IP restriction, creating the ticket, and the
message arriving exactly as written, line breaks and non-ASCII characters included). It was built from osTicket's
published API documentation and tested against a stand-in server too, and the real one showed two mistakes the stand-in
hid: the text first arrived with every space as
%20, then as base64. osTicket takes the message's type from adata:prefix but uses everything after the first comma exactly as it is, decoding nothing, so the text is sent raw. A ticket opened for a real alert has been seen working too; a summary ticket (many problems at once) has not been seen on a real osTicket yet. If osTicket rejects a ticket, "Send a test ticket" shows the reason it gave.
Optional: closing the ticket when you close the alert (the Also close the osTicket ticket tick box in the Close drawer on the Alerts page)
osTicket's API cannot close a ticket, so this is the one place in the app that writes to another application's database. Read the next paragraphs before switching it on.
- Config fields: Database username for closing tickets (optional) and its password (optional, stored encrypted). They are separate from the read-only login above, on purpose: closing is granted to one account and never widens what reading may do. Leave them empty and nothing here ever runs.
- Make the login in MySQL/MariaDB, with only what closing needs (replace
osticketand the prefix if yours differ):CREATE USER 'homelab_close'@'%' IDENTIFIED BY 'a-strong-password'; GRANT SELECT ON osticket.ost_ticket_status TO 'homelab_close'@'%'; GRANT SELECT ON osticket.ost_thread TO 'homelab_close'@'%'; GRANT SELECT ON osticket.ost_event TO 'homelab_close'@'%'; GRANT SELECT, UPDATE (status_id, closed, lastupdate, updated, isanswered, isoverdue) ON osticket.ost_ticket TO 'homelab_close'@'%'; GRANT INSERT ON osticket.ost_thread_entry TO 'homelab_close'@'%'; GRANT INSERT ON osticket.ost_thread_event TO 'homelab_close'@'%'; FLUSH PRIVILEGES; - What a close writes — what osTicket's own Close does, in one transaction (all or none): the ticket's status becomes a closed one (the one called Closed, else the first closed status), its closed and last update times are set and it is no longer marked answered or overdue; a note in the ticket's thread says Closed from Homelab Manager by with the reason you gave; and a "closed" event is recorded so the ticket's history reads like any other. Nothing else is touched, and nothing is ever deleted.
- What it checks first: that the tables and columns it writes to are there (written for osTicket 1.14–1.18); a different osTicket is refused with the list of what is missing, before anything is written. It closes only a ticket that is open, and only if its status is still what it was when it was read — a ticket somebody else closes at the same moment is left as they left it. A ticket that was opened as part of a summary ticket (many problems at once) is not closed from here, because it covers other alerts.
- Test closing (Alert settings → Alert tickets, next to Send a test ticket; administrators): signs in with the login, checks the tables and columns, and then tries every write a close makes inside a transaction that is rolled back — so a missing grant is found there and not on the first real ticket. Nothing stays (a counter or two inside the database moves on).
- Closing several alerts at once: pick them on the Alerts page and choose Close; when some of them have a ticket that can be closed from here, the drawer offers Also close N osTicket tickets (with their numbers), and it is closed one ticket after another, each written on its alert's incident and in the audit log as above. One that cannot be closed does not stop the others: the alerts are closed all the same and the message says how many tickets were closed, were already closed, or could not be (with the first reason). Summary tickets and an osTicket with no closing login are counted and left open. Undo opens the alerts again but cannot reopen the tickets — the message says so.
- What the alert shows: the ticket badge says (closed) once it has been closed from here, and the Close drawer says so instead of offering it again. If the ticket cannot be closed, the alert is still closed and you are told why; the reason is also written on the incident and in the audit log (
alert_ticket/close_ticket,close_ticket_failed). - Not verified against a live osTicket — and this is the least verified part of the app. There was no MySQL/MariaDB server to run it on; it is built from osTicket's published schema and tried only against a pretend database that answers the exact statements it sends. For opening tickets, a real osTicket showed two mistakes that a stand-in server had hidden, and the same can happen here (a column that is called something else in your version, a status or event that is set up differently). That is what Test closing is for: run it first, and try the first real close on a ticket that does not matter. If something is wrong the error says what; tell me and I'll adjust.
phpIPAM
- Config fields: phpIPAM URL, API app ID, App token
- Auth: the
tokenheader (andphpipam-token, in case your version expects that name instead), set to a static per-app code. In phpIPAM, go to Administration → API, create (or edit) an API app, and set its App security to "SSL with App token" (or "App token" if the install isn't served over HTTPS). Saving it shows the app's code once — that's what goes in this integration's "App token" field, and the app's own short id (chosen when you created it) goes in "API app ID". phpIPAM's other auth method — logging in as a real user to get a short-lived token — isn't supported; use an App-token app instead. - Required access: the API app just needs read access to whichever sections/subnets you want imported.
- What it does: this is import-only, not a full integration page — on the IP Addresses page, "Sync from phpIPAM" reads every subnet and the addresses in each, and adds or updates an IPAM entry per address (label from its hostname or description, the subnet's own description as its location, description/note/MAC folded into notes), the same way "Sync from Tailscale"/"Sync from Proxmox" already work: an address you entered by hand, or that a different sync source owns, is never overwritten.
- Not verified against a live instance — built from phpIPAM's own published API documentation
(endpoints, the
tokenheader, and the address/subnet field names all cross-checked there), but nobody has run it against a real phpIPAM yet. If a sync comes back empty or with the wrong fields, tell us what your instance actually returned and we'll adjust.
UniFi (Network application)
- Config fields: controller URL; either an API key, or a username and password; optionally one site; two checkboxes — self-hosted Network application and allow self-signed certificate.
- Two ways in:
- API key (UniFi Network 9 or later). In the controller, Settings → Control Plane → Integrations → Create API key. Used with the official Integration API: on a UniFi OS console (UDM, Cloud Gateway,
Cloud Key Gen2+) at
https://<console>/proxy/network/integration/v1/…, on a self-hosted Network application athttps://<host>:8443/integration/v1/…. The form is found by asking, so the URL is just the console's address; tick self-hosted only to skip the first guess. - Username and password (any version, including ones from before API keys). Create a local user in the controller with read-only access to the site (a Ubiquiti cloud/SSO account, or one with
two-factor, cannot be used). The classic endpoints are used (
/proxy/network/api/s/<site>/…, or/api/s/<site>/…self-hosted), and the session is logged out after each read.
- API key (UniFi Network 9 or later). In the controller, Settings → Control Plane → Integrations → Create API key. Used with the official Integration API: on a UniFi OS console (UDM, Cloud Gateway,
Cloud Key Gen2+) at
- Required access: read only — and, unlike most integrations here, nothing is ever written to the controller.
- What it does: every five minutes (and on Read now) the controller is read and kept: each device's name, model, kind (gateway, switch, access point), state, IP address, MAC address, uptime, firmware (and
whether an update is waiting), and the device it is connected through; and the networks (VLAN, address range) and Wi-Fi names (security, which network) it has set up. Wi-Fi passphrases are never read into the app.
It all appears on Network → Network devices.
- A device is a node in the dependency map, like a server: the connected through link is made into a dependency by itself (an access point needs its switch, the switch needs the gateway), and you can write others by hand (a server needs the switch it is plugged into).
- A device the controller has not seen online for longer than Settings → Notifications → Alert when a network device is offline for (10 minutes) is a critical offline alert about it. What needs it, and what it is connected through if that is down too, is folded under it, like a guest under its host. It can be silenced with a maintenance window, and has runbooks like any target.
- Servers plugged in: the controller's list of what is connected is matched to servers by IP address (exact, and only when one server has that address). A server is then connected through the switch or access point it is on — a dependency made by itself, shown on the server's page and on the Connections map. A key or account that may not read clients costs only this; devices, networks and Wi-Fi names are unaffected.
- If the controller cannot be read for twenty minutes its devices are neither raised nor cleared, and the Alerts page says it could not check; the integration itself is raised as failing like any other.
- Not verified against a live controller — built from Ubiquiti's published Integration API and the long-documented classic API (and tried against a pretend controller that answers the way those documents say), but nobody has run it against real hardware yet. Every field is read defensively, so one a version renames is left blank rather than breaking the read. If a read fails or comes back empty, the Diagnostic Log has what the controller answered; tell us and we'll adjust.
Nginx Proxy Manager
- Config fields: NPM's admin URL (the address of its web page, usually port 81), an email and a password, optionally a second email and password for managing proxy hosts (below), and a checkbox to allow a self-signed certificate.
- Required access: NPM has no API keys: its API is the one its own web page uses, so the app signs in with an email and password (each read signs in again; nothing is kept). Make a dedicated user under
Users and, under its Permissions, give it View only on Proxy Hosts and SSL Certificates — that is all that is read, and this user never writes: reading NPM sends nothing but
GETrequests. - What it does: when Network → Proxy hosts is opened (and for the alerts and the suggested checks, at most once a minute) NPM is asked for its proxy hosts and certificates. Nothing is stored in the database:
what is shown is what NPM said a minute ago.
- Each host shows its names, where it forwards to — and the server that is, when the address (or name) is one of a server's own, exactly — its certificate and whether it is working.
- A certificate that an enabled host uses and that ends within 14 days (critical within 3) or has ended is an expiry alert; a host NPM says could not be set up (its nginx did not accept the configuration) is a monitoring alert. A host that is switched off is left alone. Both link to the Proxy hosts page and can be silenced with maintenance on the integration.
- The hosts it serves are offered as Endpoints → Suggested checks (a web check on the name people use; https when there is a certificate), linked to the server it forwards to.
- If NPM cannot be read, the Alerts page says it could not check, and the integration is raised as failing like any other.
- Managing proxy hosts (optional, administrators only): with a second user in Email of a user that may manage and Password of that user — a user with Manage on Proxy Hosts, without two-factor sign-in (NPM's API can't complete that from here); give it only if you want this — Network → Proxy hosts gets New proxy host and, on each row, Edit, Switch off / on and Delete:
- Make / change (
POST /api/nginx/proxy-hosts,PUT …/{id}): the names, where it forwards to (http or https, a host or address, a port), an existing certificate, and what is switched on — Force HTTPS, HTTP/2, HSTS (and for subdomains), block common exploits, cache assets, websockets. Names are written lower case and must be names NPM takes; a name another host has is NPM's own refusal, shown as it was said. Getting a new certificate is done in NPM. - Only what differs is sent when a host is changed, and a host's access list, locations and custom nginx configuration are never sent, so they stay as they are. NPM quietly turns Force HTTPS and HTTP/2 off for a host with no certificate (and HSTS when HTTPS is not forced), so those combinations are refused here with the reason, and the form does not let them be ticked.
- Switch off / on (
POST …/{id}/disableand…/enable): off, NPM stops serving the names; nothing is lost. Delete (DELETE …/{id}): NPM stops serving them and keeps the record out of sight; the host's first name has to be typed, and the server checks it against the host as NPM has it now, so a page that is minutes old or a wrong id cannot delete another host. - Every call signs in again as the managing user (nothing is kept); the user that reads is never used to write. What this app has read of NPM is read again after a change. Stop managing is under Integrations → edit (removing the two fields, or
DELETE /api/npm/{id}/manage, which keeps the reading user). Written in the audit log: who made, changed, switched or deleted which host (its names and what it forwards to, and which settings changed — never a password).
- Make / change (
- Not verified against a live NPM — built from the API its own web page uses (
/api/tokens,/api/nginx/proxy-hosts?expand=certificate,/api/nginx/certificates, and for managing/api/nginx/proxy-hostswithPOST,PUT,DELETEand…/enable,…/disable) and tried against a pretend one. Every field is read defensively. If a read fails or comes back empty, the Diagnostic Log has what NPM answered.
Home Assistant
- Config fields: Home Assistant's address (with the port, usually 8123), a long-lived access token, and a checkbox to allow a self-signed certificate.
- Required access: read only. Make the token on a user's profile page (Security → Long-lived access tokens); the user needs no more rights than a viewer's. Only
GET /api/andGET /api/statesare used — nothing is ever sent to Home Assistant. - What it does: you choose which entities to watch on Apps → Home Assistant (search by name, then Watch; at most 60 per Home Assistant). Every five minutes (and on Read now) Home Assistant's
entities are read in one call and the watched ones are kept: their state, and for a number a reading for the chart (one at most every two minutes, kept 35 days).
- An entity that has been unavailable or unknown — or has disappeared from Home Assistant — for 15 minutes is an alert. A number past a limit you set (alert when under / over) is an alert. Both are in the Monitoring category, link to the page and can be silenced with maintenance on the integration.
- If Home Assistant cannot be read for twenty minutes the watched entities are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other.
- A service reached at a server's address (the integration's URL) is offered as a suggested dependency on that server.
- Not verified against a live Home Assistant — built from its published REST API and tried against a pretend one. Every field is read defensively. If a read fails, the Diagnostic Log has what it answered.
UPS (NUT or SNMP)
- Config fields: the host (the machine running NUT's
upsd, or the UPS's own network card), a checkbox to read it over SNMP instead of NUT, and optionally the port (3493 for NUT, 161 for SNMP), the UPS's name on the NUT server (the first one it lists when blank) and the SNMP read community (publicwhen blank; stored encrypted). - Required access: read only. NUT:
upsdmust listen on an address this server can reach (LISTENinupsd.conf; the default is only the machine itself) and, ifupsd.users/ACLlimit who may ask, allow this host. OnlyLIST UPSandLIST VAR <ups>are sent — no command, no login. SNMP: version 2c, aGETof the standard UPS-MIB (RFC 1628,1.3.6.1.2.1.33), which most UPSs and their network cards answer; APC-only or other private objects are not used. Nothing is ever set. The host is checked like an endpoint check's: not this machine itself, not the cloud metadata address; your own network is fine. - What it does: every minute the UPS is read and stored — its state, and a point for the charts (every five minutes, and every minute while on battery; kept 35 days): battery charge, runtime left, load, mains
voltage in and out, model and maker. Monitoring → UPS shows it, with the history and the times mains power was lost.
- Alerts (category Monitoring, source UPS; announced and recovered like the other health problems, held back by maintenance on the integration): mains power has failed — running on battery (critical;
NUT
OB, SNMP output source on battery), the battery is nearly empty (critical; NUTLB, SNMP battery low or depleted), the UPS asks for its battery to be replaced (warning; NUTRB), and a load of 90 % or more, or an overload (warning; NUTOVER). - It is a node in the dependency map (
integration:<id>): say what it powers under Map → Dependencies. While it runs on battery it counts as down, so servers that go offline with it are folded under its alert (which says "also takes down …") instead of each being announced. The UPS page lists what needs it in the order to shut it down — what nothing else needs first, then what that needed — so nothing is switched off while something that depends on it is still running. - If the UPS cannot be read for five minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other.
/metricshashomelab_ups_on_battery,homelab_ups_battery_charge_percent,homelab_ups_runtime_seconds,homelab_ups_load_percentandhomelab_ups_input_voltsfor each UPS that was read lately.
- Alerts (category Monitoring, source UPS; announced and recovered like the other health problems, held back by maintenance on the integration): mains power has failed — running on battery (critical;
NUT
- Not verified against a real UPS — NUT's protocol and the UPS-MIB are as published, and both readers are tried against pretend servers. Some UPSs leave out objects (the page then shows a dash), and some network cards number the load or voltage tables differently; if a value is missing, the Diagnostic Log has what was asked and answered.
Jellyfin
- Config fields: the address of Jellyfin (
http://host:8096), an API key (Jellyfin → Dashboard → API Keys → add one; stored encrypted) and, for an https address with a certificate you made yourself, insecure. - Required access: read only. The API key is Jellyfin's own, which is administrator-level in Jellyfin; this app only ever sends GET requests for the server's information, its sessions, its scheduled tasks, the item counts and the activity log. Nothing is ever changed or played.
- What it does: every two minutes Jellyfin is read and stored — its version, whether it wants a restart or has an update, who is streaming what and whether it is being transcoded, how its scheduled tasks (a library scan) last ended, how many films, series, episodes and songs there are, and how many
sign-ins failed in the last day. Apps → Jellyfin shows it, with a chart of the most that were streaming at once (readings kept 35 days).
- Alerts (category Monitoring, source Jellyfin; held back by maintenance on the integration): waiting to be restarted (warning), a scheduled task failed (warning; the task's name and error), 10 or more sign-ins failed in a day (warning).
- Somebody is watching. If the Jellyfin runs on a server this app knows (the Jellyfin's address is that server's address or host name), then before an update run restarts that machine the update drawer says who is streaming and asks again, and the server answers
409 watchingto a run started without saying it should go ahead anyway. A patch plan that comes to that server while people are streaming waits for them, up to two hours, then goes ahead and says so in its message; the server's row in the run reads Waiting: 2 people are streaming from Cinema (Ann: Dune, …). Only a reading from the last ten minutes counts: if Jellyfin cannot be read, nobody is assumed to be watching. - If Jellyfin cannot be read for ten minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other.
/metricshashomelab_jellyfin_streams,homelab_jellyfin_transcodesandhomelab_jellyfin_pending_restartfor each Jellyfin that was read lately.
- Not verified against a live Jellyfin — the endpoints (
/System/Info,/Sessions,/ScheduledTasks,/Items/Counts,/System/ActivityLog/Entries) and their fields are as Jellyfin publishes them and the reader is tried against a pretend server. Every field is read defensively, and a part that cannot be read (older versions differ) is left out without failing the rest; the Diagnostic Log has what was asked and answered.
Immich
- Config fields: the address of Immich (
http://host:2283), an API key (Immich → Account Settings → API Keys; stored encrypted) and, for an https address with a certificate you made yourself, insecure. - Required access: read only. Give the key just these permissions:
server.about,server.storage,server.statisticsandjob.read(queue.readon newer versions) — statistics and jobs need an administrator's key. This app only ever sends GET requests; nothing is changed, and no job is started, paused or cleared. If one of those is refused, that part is left out and the rest still works. - What it does: every five minutes Immich is read and stored — its version (and whether a newer one is out), how full the disk under the library is, how many photos and videos there are and what they take, and the background job queues with how many jobs failed in each.
Apps → Immich shows it.
- Alerts (source Immich; held back by maintenance on the integration): the disk under the library is 90 % full (warning; 95 %, critical) and 10 or more background jobs have failed, all queues together (warning; the worst queues are named — thumbnails or metadata that were never made. Failed jobs stay counted until you run them again or clear them in Immich, so the alert stays until you do).
- If Immich cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be asked is unknown, never none.
/metricshashomelab_immich_photos,homelab_immich_videos,homelab_immich_library_bytes,homelab_immich_disk_used_percentandhomelab_immich_failed_jobsfor each Immich that was read lately.
- Not verified against a live Immich — the endpoints (
/api/server/about,/server/storage,/server/statistics,/server/version-check,/api/jobs, and/api/queueson newer versions) and their fields are as Immich publishes them, and the reader is tried against a pretend server that answers both ways. Immich renames these now and then; the Diagnostic Log has what was asked and answered if something comes back empty. Whether a waiting backlog is a problem is not judged: a big import has one for days.
Nextcloud
- Config fields: the address of Nextcloud (
https://cloud.example.lan); optionally an administrator's name and an app password (Personal settings → Security → Devices & sessions → Create new app password; stored encrypted — never the account's own password); and, for an https address with a certificate you made yourself, insecure. - Required access: read only. Without a login only
/status.phpis read, which Nextcloud answers to anyone. With one, the Monitoring app (serverinfo, installed by default) is also asked, which needs an administrator; if it is refused or the app is off, the status is still read and the page says so. This app only ever sends GET requests, and nothing is changed. - What it does: every five minutes Nextcloud is read and stored — its version, whether it is in maintenance mode, whether it needs its database upgrading, and (with the login) the room left where the data is kept, the users, the files, who was active in the last day and how many app updates wait. Apps → Nextcloud shows it.
- Alerts (source Nextcloud; held back by maintenance on the integration): the database needs upgrading (critical — nobody can use it until
occ upgrade), maintenance mode is on (warning — nobody can sign in), and less than 20 GB is left for the data (warning; under 5 GB, critical), the background jobs are not running (warning — Nextcloud's own Cron last run check says error, which it does when the last run was more than an hour ago; see below) and Nextcloud's own checks report an error (warning; one alert naming them). - If Nextcloud cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other.
/metricshashomelab_nextcloud_maintenance_mode,homelab_nextcloud_free_bytes,homelab_nextcloud_active_users_24handhomelab_nextcloud_app_updatesfor each Nextcloud that was read lately.
- Alerts (source Nextcloud; held back by maintenance on the integration): the database needs upgrading (critical — nobody can use it until
- Not verified against a live Nextcloud —
/status.phpand the Monitoring app's/ocs/v2.php/apps/serverinfo/api/v1/infoare as Nextcloud publishes them and the reader is tried against a pretend server. Cron is read a different way, because the Monitoring app has no field for it (its source was read to be sure): with the same login, Nextcloud's own setup checks are asked (GET /settings/setupcheck, Nextcloud 28 and later; no administrator is needed), and the one that is Nextcloud's Cron last run — found by its class name, not by its text, which is in the language Nextcloud is set to — gives the alert above and the Background jobs line on the page. Any other of those checks that reports an error is one alert, and ones that report a warning (HTTP headers, a PHP setting …) are only listed on the page, as in Nextcloud's own admin overview. Before Nextcloud 28 there is no such page: cron and the checks are then not known (and say so, never fine). The same read gives the version Nextcloud itself says is available, shown on the page. With Nextcloud AIO the admin pages are the mastercontainer's, but the Nextcloud behind it is an ordinary one and is read the same way (use its own address, not the AIO admin address).
Sonarr, Radarr and Prowlarr
- Config fields: the application's URL and its API key (in the application: Settings → General → Security → API Key; stored encrypted), and Allow self-signed certificate if it is on HTTPS with its own certificate. Add each application as its own integration, as the kind it is — the Test button says if the address turns out to be another one. The key is sent as
X-Api-Key; the app only ever sends GET requests. - Lidarr and Readarr (music and books) are the same: add them as their own kinds. They answer under
/api/v1(as Prowlarr does), and ask for their own unknown items in the queue (includeUnknownArtistItems,includeUnknownAuthorItems). The Test button says if an address is another one of the family. Readarr's own project has been retired; the integration reads whatever install you still run. - Required access: the application's address reachable from the app. Sonarr and Radarr answer under
/api/v3, Prowlarr under/api/v1. A read is five to six requests, every five minutes. - What it does: every five minutes each application is read — its version, what its own checks found (
/health), its download queue (/queue: the first 100, and how many there are), its disks (/diskspace), for Sonarr and Radarr how many wanted items have no file (/wanted/missing), and for Prowlarr its indexers and which it has switched off after failures (/indexer,/indexerstatus). Apps → Media managers shows them. Nothing is searched, grabbed, removed or changed.- Alerts (sources Sonarr, Radarr, Prowlarr; held back by maintenance on the integration): what the application says is wrong with itself (a finding of type warning or error — a download client that cannot be reached, a root folder gone, indexers unavailable; a notice, such as an update being available, is shown but not raised); downloads that are stuck (in the queue for two hours or more and judged warning or error, failed, or blocked from importing — one alert for the lot, naming the first three and why); a disk nearly full (under 10% free, critical under 5%; folders on one disk count once, and a disk under 2 GB is not a media disk). See MONITORING.md.
- If an application cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be read (the queue, say) is shown as could not be read, never as empty.
/metricshashomelab_arr_health_issues,homelab_arr_queue_items,homelab_arr_queue_stuck_items,homelab_arr_wanted_missingandhomelab_arr_disk_free_bytes.
- Not verified against live installs — the endpoints and fields are as the applications' published OpenAPI files and source have them (HealthResource, QueueResource, DiskSpaceResource, IndexerStatusResource), and the reader is tried against pretend ones. A finding is raised under a key made from the check and its words (numbers left out), so a finding whose wording changes is raised anew. Lidarr, Readarr and Bazarr are not read.
qBittorrent and SABnzbd
- Config fields: for qBittorrent, the Web UI URL (Tools → Options → Web UI) and, if it asks for a sign-in, the user name and password (stored encrypted); leave them empty for one that lets this address in without signing in (Bypass authentication for clients in whitelisted IP subnets). For SABnzbd, its URL and its API key (Config → General → Security → API Key — the full API key, not the NZB key; stored encrypted). Allow self-signed certificate for either on HTTPS with its own certificate. Add each as its own integration.
- Required access: the address reachable from the app. qBittorrent is read through its Web API v2 (
/api/v2/…): the app signs in with the form (POST /auth/login), sends the session cookie and its own address as theReferer(qBittorrent's protection against forged requests wants that), reads, and signs out. SABnzbd is read through/api?mode=…&output=json&apikey=…. A read is three to five requests, every five minutes. Nothing is sent that adds, pauses, resumes, removes or changes anything — the sign-in is the only POST. - What it does: every five minutes each client is read — qBittorrent: its version, every torrent (
/sync/maindata, or/torrents/infowhere that is not answered) with its state, progress, speed and last activity, the speeds and whether it can reach the network (connection_status: connected, firewalled or disconnected) and the free space of its download folder; SABnzbd: its version, the queue (mode=queue: up to 200 slots, paused or not, the speed, and the free and total space of the incomplete and complete folders), what failed (mode=history: the last 50 entries, the ones that failed) and its own warnings (mode=warnings). Apps → Download clients shows them, the items that need a look first; items that are finished and idle (seeding, stopped) are counted, not listed (at most 100 are kept).- Alerts (sources qBittorrent, SABnzbd; held back by maintenance on the integration): downloads stuck (in an error state — qBittorrent's
errorandmissingFiles— or stalled with nothing moving for a day; one alert for the lot, naming the first three); no connection (qBittorrent,disconnectedwith torrents loaded for 15 minutes — a VPN that dropped; firewalled is shown but not raised, since it still downloads); paused and forgotten (SABnzbd's queue paused for six hours with downloads waiting); downloading nothing (SABnzbd, not paused, work waiting, and no speed for an hour — a news server that does not answer or refuses the login); a download disk nearly full (SABnzbd says how big the disks are: under 10% free, critical under 5%; qBittorrent says only what is free: under 20 GB, critical under 5 GB). Failures in SABnzbd's history are shown for the last day but are not an alert, since a failed download is normal on Usenet and the *arr applications try another release. See MONITORING.md. - "Since when" (disconnected, paused, idle) is what this app saw: the time of the first read that showed it.
- If a client cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be read (the history, say) is shown as could not be read, never as empty.
/metricshashomelab_download_speed_bytes,homelab_download_items,homelab_download_stuck_items,homelab_download_paused,homelab_download_connected,homelab_download_failed_recentandhomelab_download_disk_free_bytes.
- Alerts (sources qBittorrent, SABnzbd; held back by maintenance on the integration): downloads stuck (in an error state — qBittorrent's
- A wrong password is retried every five minutes, and qBittorrent bans an address for an hour after a few wrong ones (Web UI → Ban client after consecutive failures). If the integration says it was refused with HTTP 403, fix the password and wait out the ban (or restart qBittorrent).
- Not verified against live installs — the endpoints and fields are as the two applications' published API documentation has them, and the reader is tried against pretend ones. qBittorrent 5 renamed some states (
pausedDLbecamestoppedDL); both are understood. SABnzbd's figures arrive as text, in megabytes and gigabytes, and are converted. Torrents are not paused, removed or added from here, and no NZB is added.
Hetzner Robot
- Config fields: the webservice user name (it looks like
#ws+abc123…) and its password (stored encrypted), made in Hetzner Robot → Settings → Webservice and app settings. That is not the login to Robot itself. There is no address to give: Robot is alwayshttps://robot-ws.your-server.de. This is the dedicated servers and storage boxes side of Hetzner; the cloud servers are the Hetzner Cloud integration, with a project token. - Required access: the webservice user, reachable from the app over HTTPS. HTTP Basic is sent with every request, and the app only ever sends GET requests.
- What it does: every fifteen minutes it reads
GET /server(number, name, product, data centre, addresses, traffic plan, status, cancelled, paid until),GET /server/{number}for each server (whether its rescue system is on — it is not in the list) andGET /storagebox(product, location, cancelled, locked, paid until, the linked server). Infrastructure → Hetzner Robot shows them. Nothing is reset, nothing is activated, ordered or cancelled.- Fifteen minutes, and 25 servers: Robot allows 200 requests an hour, and a read is a list, one request per server and a list of storage boxes — so ten servers is 12 requests a read, 48 an hour. Only the first 25 servers (by number) are asked about their rescue system; any more are listed, counted on the page, and left without a rescue state.
- Alerts (source Hetzner Robot; held back by maintenance on the integration): a server or storage box that is cancelled and ends within 30 days (critical within 7; the date is the last day it runs, and the data goes with it); a storage box that is locked (critical); a rescue system on for two hours (the server's next boot is into the rescue system); a server still "in process" a day after the app first saw it so. See MONITORING.md.
- "Since when" (rescue on, not ready) is what this app saw: the time of the first read that showed it.
- If the account cannot be read for 45 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be read (the storage boxes, a server's rescue state) is shown as could not be read, never as none or off.
/metricshashomelab_hetzner_robot_servers,homelab_hetzner_robot_rescue_active,homelab_hetzner_robot_days_leftandhomelab_hetzner_robot_storage_box_locked.
- A wrong password is retried every fifteen minutes, and Robot blocks an address for a while after a few wrong ones (HTTP 403). If the integration says it was refused, fix the password and wait.
- Not verified against a live account — the endpoints and fields are as Hetzner's published webservice documentation has them, and the reader is tried against a pretend one. An account with no servers (or no storage boxes) is answered with a 404 and a code ending in
NOT_FOUND, read as none. Whether Robot switches the rescue system off by itself after a while is not known here, so the alert is for one that has been on two hours; traffic used is not read (Robot gives it per address, and the plan only).
Hetzner Cloud
- Config fields: the project's API token (Hetzner Console → the project → Security → API tokens → Generate API token; stored encrypted). Read permission is enough — and recommended: the app only ever sends GET requests. A token belongs to one project, so add one integration for each project you want to watch.
- Required access:
api.hetzner.cloudreachable from the app. The API allows 3600 requests an hour per project; a read is about ten requests (plus one for each further page of 50 servers), every five minutes — well inside it. - What it does: every five minutes the project's servers, volumes, snapshots and backups, primary IPs and Hetzner's price list are read and stored. The Hetzner Cloud page shows them with a monthly cost estimate; a server's own page gets a card when it is one of them (matched by address, else by name).
- Alerts (source Hetzner; held back by maintenance on the integration): a server that was running and is off (warning; left alone after a week), one stuck migrating or rebuilding for half an hour, traffic at 80% of the month's quota (critical at 100%), rescue mode left on for an hour, and backups enabled but late (the same limit as Proxmox guests' backups, 48 hours by default). See MONITORING.md.
- If Hetzner cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A list that could not be asked (the volumes, say) is shown as could not be read, never as empty.
- Load balancers, floating IPs and certificates are read with the rest (a list that cannot be asked is shown as could not be read, never as none): the Hetzner page lists each load balancer with the health of its targets, each floating IP and what it points at, and each certificate with when it ends. Their prices (a load balancer's type, a floating IP's kind and place) are now in the cost estimate. Alerts: a load balancer with an unhealthy target (warning; critical when none of its targets is healthy), a certificate that is in use and ends within 14 days (critical within 3, or past its end) or that Hetzner could not issue or renew, and a floating IP that points at no server (it is billed all the same). A certificate nothing uses is not raised.
- Traffic forecast: from the month's traffic the app writes down about every six hours it works out how the month is going — by the last week's rate, or, with too little of it, by the month's average (after three days) — and warns, below the 80% alert, when a server is on course to pass its quota before the month ends: "at this rate web will pass its 20.0 TB traffic quota on 24 June". The page shows the date, or what the month will come to, under each server's traffic bar. The month is the calendar month in UTC; a counter that goes down starts the history over.
/metricshashomelab_hetzner_server_running,homelab_hetzner_traffic_outgoing_bytes,homelab_hetzner_traffic_included_bytesandhomelab_hetzner_monthly_cost.
- Not verified against a live project — the endpoints (
/servers,/volumes,/images?type=snapshotandtype=backup,/primary_ips,/pricing) and their fields are as Hetzner's published OpenAPI file has them, and the reader is tried against a pretend server. Traffic is read as bytes and shown in binary units (Hetzner's 20 TB is 20 TiB); a server's included traffic and the outgoing traffic of the current billing month come from the server itself. The cost is the list price including VAT (thegrossprices): check it against Hetzner's invoice the first time. Dedicated (Robot) servers and Hetzner Storage Boxes are a different API and are not read.
Fragnet game servers
- Config fields: the account's API key (panel.fragnet.net → your profile → API Credentials → create one; it starts with
ptlc_and is shown only once; stored encrypted). It must be the account's own key — an Application key (ptla_) is for panel administrators and does not work, and the app says so. Optional: the panel address (https://panel.fragnet.netwhen left out — fill it in for another Pterodactyl panel, since Fragnet's is a fork of Pterodactyl and this speaks its client API), warn when the newest backup is older than n days (7; 0 turns backups off), warn when disk or memory is fuller than n % (90), servers whose backups are not judged (names, comma-separated) and three tick boxes that switch one kind of alert off for the whole account — do not alert about disk space, memory or backups (the page still shows the figures). A key may be limited to certain addresses in the panel; if so, allow the app's. - Required access:
panel.fragnet.net(HTTPS) reachable from the app. The panel limits the requests per minute (429 when over); a read is four requests for each game server, every five minutes. - What it does: every five minutes each game server of the account (also those shared with it) is read — the game (the panel's egg, for example Minecraft: Paper), every IP address and port, SFTP, the plan's memory, disk and CPU limits and its room for backups and databases, whether it is running, what it uses, its backups, schedules and databases. Infrastructure → Game servers shows them; a row opens to show every address (click to copy), the backups, the schedules and a link to the server in the game panel.
- Power: operators can start, stop, restart and kill a server from the page (a confirmation first; kill says it loses unsaved progress). It sends exactly that signal to the panel and writes it to the audit log (
start_game_server…). The page reads again a few seconds later. Beside backups, it is the only thing this integration ever sends but reads, and only a server the last read found can be signalled. - Back up now: operators can ask for a backup of a server whose plan has room for backups (Back up on its row, or Back up now beside its backups; a confirmation first, which says how many the plan allows and how many are made). It is
POST /api/client/servers/{id}/backupswith a name that says it was asked for here (Homelab Manager — 2026-11-04 14:30 UTC) and nothing else — no file is left out, nothing is locked. The panel makes it in the background; the page reads the account again after a few seconds and then every twenty seconds until the backup has finished. It is written to the audit log (backup_game_server, with the backup's id). Refused here before the panel is asked: a plan with no room for backups, a server that is suspended or being installed, one for which a backup is already being made (one that has been "being made" for more than two hours is taken to be lost and does not count), and the same server asked again within 30 seconds (HTTP 429). Refused by the panel, and said in its words: a server at the number of backups its plan allows (delete one in the panel first — the app never deletes a backup), the panel's own limit of a couple of backups in ten minutes (429), an account that may not make backups on a shared server (403 — it needs the Backups → Create permission) and a server that is busy (409). A refusal costs no wait before the next try. - Alerts (source Fragnet; held back by maintenance on the integration): a server whose plan allows backups and whose newest successful backup is older than the limit (or has none, once the app has known it for that long; a backup that failed does not count, and the message says when the newest attempt failed); disk over the limit (critical from 98%); memory over the limit while it runs. A server that is stopped is not an alert. (When one is turned on or off, a notification says so: NOTIFICATIONS.md.)
- Power history. Every change a read sees (turned on, turned off) is written down, and so is each Start, Stop, Restart or Kill sent from here with who sent it, so a row's details have a Power history: the share of the last 30 days (or of what has been watched, when less) that the server was on, how many times it started and stopped, a bar for the last seven days (green on, grey off), and the latest changes — "Turned on — start by Ada" when the change followed a signal sent from here in the 20 minutes before. It is what this app saw: the account is read every five minutes, so every time is to the nearest five, and nothing is known of the time before a server was first read. Kept 180 days; it goes with the integration. See MONITORING.md.
- If the panel cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that cannot be read for one server (a sub-user without the database permission, say) is shown as could not be listed, never as none.
/metricshashomelab_fragnet_server_running,homelab_fragnet_disk_used_bytes,homelab_fragnet_disk_limit_bytes,homelab_fragnet_memory_used_bytes,homelab_fragnet_memory_limit_bytesandhomelab_fragnet_newest_backup_timestamp_seconds.
- Power: operators can start, stop, restart and kill a server from the page (a confirmation first; kill says it loses unsaved progress). It sends exactly that signal to the panel and writes it to the audit log (
- Not verified against a live account — the endpoints (
/api/client?include=egg,allocations,/servers/{id}/resources,…/backups,…/schedules,…/databases,POST …/power) and their fields are as Pterodactyl's own source and Fragnet's documentation have them, and the reader is tried against a pretend panel. Fragnet's fork may differ: the game is left out (shown as the Docker image) if the panel does not send the egg, and a panel that refuses the extraincludeis asked again plainly. Disk and memory limits are in MB as the panel counts them and shown in binary units. What the servers cost is not in the API: add it under Records → Costs.
AdGuard Home
- Config fields: the URL of its web interface and, if it has a sign-in, the user name and password (HTTP Basic; stored encrypted). Optional: the DNS server address (the host of the URL unless told — fill it in if a reverse proxy sits in front of the web interface), the name to test DNS with (
example.com) and Allow self-signed certificate. - Required access: the web interface reachable from the app over HTTP(S), and — for the DNS test — its DNS port (read from its status, usually 53) reachable from the app over UDP. If the app sits where UDP 53 to AdGuard Home is blocked, the test will say so (no answer) and DNS will be reported down; allow it or set the DNS server address to one the app can reach.
- What it does: every two minutes it reads
GET /control/status(running, protection, version, DNS port),GET /control/stats(queries, blocked, average time, top names and clients) andGET /control/filtering/status(the lists and when each was updated) and puts one DNS question — the address of the test name — to its DNS server. An answer, or "no such name", means the resolver works; a server failure or a refusal does not. Network → AdGuard Home shows it all. Nothing is changed: protection is never switched, no list refreshed.- Alerts (source AdGuard Home; held back by maintenance on the integration): the DNS server not running (critical); the test question unanswered in every read for ten minutes (critical — one lost packet is not an outage); protection switched off for an hour (warning); filter lists switched on and not updated for a week (warning, one for all). See MONITORING.md.
- If it cannot be read for ten minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be read (the statistics, the lists) is shown as could not be read, never as none.
/metricshashomelab_adguard_running,homelab_adguard_protection_enabled,homelab_adguard_dns_up,homelab_adguard_dns_probe_seconds,homelab_adguard_queries,homelab_adguard_blockedandhomelab_adguard_avg_processing_seconds.
- Not verified against a live install — the endpoints and fields are as AdGuard Home's published OpenAPI file has them (
ServerStatus,Stats,FilterStatus), and the reader (and the DNS question, against a pretend DNS server) is tried against pretend ones. The statistics are over AdGuard Home's own period (a day unless set otherwise). A DNS question is asked of the host in the URL: with a proxy in front, set DNS server address.
Technitium DNS
- Config fields: the URL of its web console (
http://dns.example.lan:5380) and an API token — a non-expiring one, made under Administration → Sessions → Create Token; stored encrypted — of a user who may view the dashboard, the settings and the zones (the DHCP server, for the DHCP counts, and administration, for the cluster — a token without it still works; the cluster is just not shown). Optional: the DNS server address (the host of the URL unless told — fill it in if a reverse proxy sits in front of the console), the name to test DNS with (example.com) and Allow self-signed certificate. Zones and records are connected separately, as a DNS provider on the DNS page, with a token of its own; this integration only says how the server is doing. - Required access: the console reachable from the app over HTTP(S) and — for the DNS test — the DNS port (the first of the server's listening endpoints, usually 53) reachable from the app over UDP. The token goes in an
Authorization: Bearerheader, which Technitium 15.0 and later require; an older server answers "token not accepted". If the app sits where UDP 53 to it is blocked, the test says so (no answer) and DNS is reported down; allow it or set the DNS server address to one the app can reach. - What it does: every two minutes it reads
GET /api/settings/get(version, when it started, whether blocking is on, the block lists and when they are next updated, the cache limit, recursion, DNSSEC, the DNS port),GET /api/dashboard/stats/get?type=LastDay(the last day's queries and how each ended, clients, cache entries, zone and list counts, the clients and names asked about and blocked most),GET /api/zones/list(which secondary zones have expired or cannot sync; the server's own internal zones and switched-off zones are not judged),GET /api/admin/cluster/state(if it is part of a cluster, Technitium 14 and later: the nodes, which is primary, which of them it can reach and when it last took the configuration from the primary; it needs the token's user to be allowed to view administration — without that the rest is read as before and the page says what is missing; a server in no cluster shows nothing) andGET /api/dhcp/scopes/listand…/leases/list(scopes and lease counts) — and puts one DNS question to its DNS server, as for AdGuard Home. Network → Technitium DNS shows it all, and the dashboard has a widget for it in its Network section (whether DNS answers and how fast, the last day's queries and the share blocked, how they were answered, and what is wrong). Nothing is changed: blocking is never switched, no block list refreshed, no zone touched.- Alerts (source Technitium DNS; held back by maintenance on the integration): the test question unanswered in every read for ten minutes (critical — one lost packet is not an outage); a secondary zone that has expired (critical — it no longer answers), or zones that cannot sync (warning), one alert for all the zones; blocking switched off for an hour while block lists are set up (warning — with none, off is how it is); block lists whose update was due more than six hours ago (warning); a cluster node that has been unreachable for ten minutes (warning for a secondary, critical for the primary — one alert for each node); a secondary that has not taken the configuration from the primary for three of its refresh periods and at least half an hour (warning). See MONITORING.md.
- If it cannot be read for ten minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be read (the statistics, the zones, DHCP) is shown as could not be read, never as none; the settings are the one part that must work, since they say it is there and the token is accepted.
/metricshashomelab_technitium_dns_up,homelab_technitium_dns_probe_seconds,homelab_technitium_blocking_enabled,homelab_technitium_uptime_seconds,homelab_technitium_block_lists_overdue,homelab_technitium_queries,homelab_technitium_blocked,homelab_technitium_cached,homelab_technitium_recursive,homelab_technitium_server_failures,homelab_technitium_clients,homelab_technitium_cache_entries,homelab_technitium_zones,homelab_technitium_zone_problemsandhomelab_technitium_dhcp_leases, and for a clustered serverhomelab_technitium_cluster_nodes,homelab_technitium_cluster_nodes_unreachableandhomelab_technitium_cluster_config_synced_timestamp_seconds.
- No CPU, memory or disk. Technitium's API has no figures for the machine it runs on (its "resource" numbers are the DNS server's own: queries, cache, zones). Put a server agent on that machine for those.
- Not verified against a live install — the endpoints and fields are as Technitium's own API documentation (
APIDOCS.md) has them, and the reader (and the DNS question, against a pretend DNS server) is tried against pretend ones. The statistics are over the last day; the zones are read up to 1000 at a time; the page shows the share of failed queries in yellow from 20% (with at least 200 queries), which is not an alert. A DNS question is asked of the host in the URL: with a proxy in front, set DNS server address. Cluster state and the version-behind comparison of the Versions page are not read.
Grafana
- Config fields: the URL and a service account token (Administration → Users and access → Service accounts → add a service account with the Viewer role → add a token; shown once; stored encrypted), and Allow self-signed certificate. To also test the data sources the service account needs permission to read and query them (the Viewer role usually has it); without it they are shown as could not be listed and the rules still work.
- Required access: Grafana's address reachable from the app. A read is a few requests plus one for each data source, every five minutes.
- What it does: every five minutes the alert rules (
GET /api/prometheus/grafana/api/v1/rules— Grafana-managed alerting's Prometheus-compatible view: which are firing, pending, or cannot be evaluated) and the data sources with Grafana's own health check of each (GET /api/datasources,GET /api/datasources/uid/{uid}/health) are read and stored. Monitoring → Grafana shows them. Nothing is silenced, paused or changed.- Alerts (source Grafana; held back by maintenance on the integration): a rule firing (critical when it carries the label
severity=criticalorpage, a warning otherwise; a pending rule is shown, not raised), a rule Grafana cannot evaluate, and a data source that fails its health check. Grafana can notify about its own alerts too — with both switched on you hear twice; this is for having them in one list, or for the ones that reach you nowhere else. See MONITORING.md. - If Grafana cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other.
/metricshashomelab_grafana_rules,homelab_grafana_rules_firing,homelab_grafana_rules_errorandhomelab_grafana_datasources_failing.
- Alerts (source Grafana; held back by maintenance on the integration): a rule firing (critical when it carries the label
- Not verified against a live Grafana — the endpoints and fields are as Grafana's HTTP API documentation has them, and the reader is tried against a pretend one. Only Grafana-managed rules are read (rules of a Prometheus or Loki data source that Grafana merely shows are not). A data source whose type has no health check is not tested, which is not the same as healthy.
Speedtest Tracker
- Config fields: the address of Speedtest Tracker (
http://speedtest.example.lan) and an API token (the profile menu → API tokens → create one with the results:read ability; stored encrypted — that is all it needs). Optional: the download and upload you pay for (Mbit/s) and the share below which to warn (60% unless you say), which the alerts use, and, for an https address with a certificate of its own, insecure. - Required access: read only. The app asks for
/api/healthcheck(no login) and/api/v1/resultsand only ever sends GET requests — no speed test is started (that would bePOST /api/v1/speedtests/run, which is never called). - What it does: every ten minutes the newest results are read (three pages of 30 the first time, so there is a past to chart) and each is stored once for 90 days: when, download and upload, ping. The Speedtest page shows the latest test, the middle of the last three and charts of speed and ping over 1, 7, 30 or 90 days.
- Alerts (source Speedtest, category Monitoring; held back by maintenance on the integration): the internet is slow — the middle of the newest three completed tests is under the share (60%) of what you pay for, judged separately for download and upload and only for one whose number you gave; and the speed tests are failing — the newest three all failed (the internet is down, or Speedtest Tracker cannot reach Ookla). One slow test is not an alert: the middle of three is what is judged.
- If Speedtest Tracker cannot be read for 45 minutes its alerts are neither raised nor cleared, and the Alerts page says it could not check.
- On a status page the integration reads as the internet: Working, Having trouble when it is slow, Not working when the tests are failing.
/metricshashomelab_speedtest_download_bits_per_second,homelab_speedtest_upload_bits_per_secondandhomelab_speedtest_ping_secondsfor the newest completed test of each.
- Not verified against a live Speedtest Tracker — the endpoints and fields are read from its own source code (
routes/api/v1/routes.php, the results controller and resource) and the reader is tried against a pretend server.downloadanduploadare bytes per second there (the bits fields are used when present); a result's time is the one Ookla gives in its data, elsecreated_at, taken as UTC. Speedtest Tracker may allow fewer than 30 results a page; the reader asks again without a size when it says so.
NetBox
- Config fields: the address of NetBox (
https://netbox.example.lan), an API token (your profile → API Tokens; stored encrypted; write enabled off is enough — both the olderTokentokens and NetBox 4.5'snbt_…tokens work) and, for an https address with a certificate you made yourself, insecure. - Required access: read only.
/api/status/, and the counts and addresses of devices, virtual machines, prefixes and IP addresses. This app only ever sends GET requests; nothing is changed. - What it does: every five minutes NetBox is read and stored — its version, how many background workers are running (they run its webhooks, scripts, jobs and reports; in the Docker image they are a separate container that can be down while the pages still load), how many devices, VMs, prefixes and addresses it holds, and the addresses
themselves (up to 5000). Network → NetBox shows it.
- Alert (source NetBox; held back by maintenance on the integration): no background worker is running (warning).
- Not in NetBox: the page lists the servers this app manages none of whose addresses are in NetBox (an address that is the same on every host, like Docker's bridge, is left out as on the Consistency page; loopback and link-local addresses say nothing). That is a list, not an alert — documentation that is behind is not an outage. If NetBox holds more than 5000 addresses the page says what is missing may be in the part that was not read.
- If NetBox cannot be read for 20 minutes its alert is neither raised nor cleared, and the Alerts page says it could not check.
/metricshashomelab_netbox_workers,homelab_netbox_devicesandhomelab_netbox_ip_addressesfor each NetBox that was read lately.
- Not verified against a live NetBox — the endpoints and fields are as NetBox publishes them and the reader is tried against a pretend server that answers the addresses in pages. The Diagnostic Log has what was asked and answered.
n8n
- Config fields: the address of n8n (
http://host:5678), an API key (Settings → n8n API → Create an API key; stored encrypted) and, for an https address with a certificate you made yourself, insecure. - Required access: read only.
GET /api/v1/workflowsandGET /api/v1/executions— the public API has to be switched on (it is on by default in current versions). This app only ever sends GET requests: no workflow is started, changed or switched off. - What it does: every five minutes n8n is read and stored — the workflows and whether each is switched on, and, from the newest 250 runs, each workflow's last outcome and how many of its runs failed in the last day. Automation → n8n shows it.
- Alert (source n8n, category Automation; held back by maintenance on the integration): a workflow that is switched on failed on its last run (warning; one alert for each workflow, saying when and, if more than one run failed, how many in the last day). It clears by itself when the workflow next succeeds. A workflow that is switched off, or whose failure is more than a week old, is not raised.
- If n8n cannot be read for 20 minutes its alerts are neither raised nor cleared, and the Alerts page says it could not check. If the runs could not be read (but the workflows could), the last outcomes are unknown and nothing is claimed.
/metricshashomelab_n8n_workflows,homelab_n8n_workflows_activeandhomelab_n8n_workflows_failingfor each n8n that was read lately.
- Not verified against a live n8n — the endpoints and fields are as n8n documents them and the reader is tried against a pretend server that pages with a cursor. A workflow that runs less often than 250 other runs go by may show no run (and so no alert); the page says it is judged from the newest 250.
Paperless-ngx
- Config fields: the address of Paperless-ngx (
http://host:8000), an API token (your profile → API Auth Token, or Auth Tokens in the admin pages; stored encrypted) and, for an https address with a certificate you made yourself, insecure. - Required access: read only, and a superuser's token is best: the system status (the worker, Redis, the index, the disk) is only given to a superuser. With an ordinary user's token the document counts and the failed imports are still read, and the page says the status is unknown. This app only ever sends GET requests; nothing is changed, and no failed task is dismissed.
- What it does: every five minutes Paperless is read and stored — its version (and whether a newer one is out), the status of the database, Redis, the worker that consumes documents, the search index, the classifier and the sanity check, the disk, the document and inbox counts and the imports that failed
in the last week and that nobody has dismissed. Apps → Paperless shows it.
- Alerts (source Paperless-ngx; held back by maintenance on the integration): the database, Redis or the worker in error (critical — nothing can be consumed or found), the index or the classifier in error (warning), the sanity check found problems (warning), documents failed to import (warning; the files are named and the latest error shown — it clears when you dismiss them in Paperless, or after a week), and the disk under the documents is 90 % full (warning; 95 %, critical). A classifier that simply has not been trained yet (Paperless's warning) is not an alert.
- If Paperless cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be asked is unknown, never none.
/metricshashomelab_paperless_documents,homelab_paperless_inbox,homelab_paperless_failed_importsandhomelab_paperless_component_okfor each Paperless that was read lately.
- Not verified against a live Paperless — the endpoints (
/api/status/,/api/statistics/,/api/tasks/,/api/remote_version/) and their fields are as Paperless-ngx publishes them and the reader is tried against a pretend server. The Diagnostic Log has what was asked and answered.
Prometheus
- Config fields: the address of Prometheus (
http://host:9090); optionally a bearer token, if something in front of Prometheus asks for one (stored encrypted); and, for an https address with a certificate you made yourself, insecure. - Required access: read only, and nothing needs to be installed or configured in Prometheus. This app only ever sends GET requests:
/api/v1/status/buildinfo,/api/v1/targetsand/api/v1/alerts. - What it does: every two minutes Prometheus is read and stored — its version, every active scrape target with whether its last scrape worked (and the error), and the alerts its own rules have firing. Monitoring → Prometheus shows targets by job, the ones not answering and the alerts. So whatever you already
measure there — a node exporter on each host, a service's own metrics — is part of the one list of what is wrong.
- Alerts (category Monitoring, source Prometheus; held back by maintenance on the integration): targets not answering — one alert for each job, naming the instances and the scrape error, and only once a target has been down for five minutes (one failed scrape is not news; the time is kept from one read to the next),
and an alert that Prometheus's rules are firing — one for each alert name, critical if any of them has the label
severity="critical"(orpage), a warning otherwise. Pending alerts,infoones and the by-design heartbeats (Watchdog,DeadMansSwitch,InfoInhibitor) say nothing. - If Prometheus cannot be read for ten minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A list Prometheus did not answer (targets, or alerts) is unknown, never none.
- Nothing is sent back to
/metrics: this app already exposes its own (see PROMETHEUS-GRAFANA.md), and exporting what Prometheus said into Prometheus would only go round in a circle.
- Alerts (category Monitoring, source Prometheus; held back by maintenance on the integration): targets not answering — one alert for each job, naming the instances and the scrape error, and only once a target has been down for five minutes (one failed scrape is not news; the time is kept from one read to the next),
and an alert that Prometheus's rules are firing — one for each alert name, critical if any of them has the label
- Not verified against a live Prometheus — the endpoints and fields are as Prometheus documents them and the reader is tried against a pretend server. Alerts that Grafana manages itself (Grafana-managed alert rules) are not in Prometheus's list and are not seen; alerts that Prometheus's own rules send to Alertmanager are, while they are active.
Authentik
- Config fields: the address of Authentik (
https://auth.example.lan), an API token (Authentik → Directory → Tokens and App passwords → Create, intent API Token, for a user who may read; stored encrypted), optionally a token for making and managing users (below) and, for an https address with a certificate you made yourself, insecure. - Required access: read only. This app only ever sends GET requests: the version, the workers, the outposts and their health, the certificates, the tokens and the events log. Nothing is ever changed. Give the token a user with just enough to read these (an administrator, or a user in a role that may view them); if one of the lists is refused, that part is left out and the rest still works.
- Making and managing users (optional, administrators only): all of it is on its own tab, Apps → Authentik → Users and groups, which only an administrator sees; Status (the default) stays what it was. with a second, separate token in Token for making and managing users — an API token of an account that may add, change and delete users, which is close to an administrator of Authentik, so give it only if you want this — Apps → Authentik → Users and groups → New user makes a user
(user name, name, an email if there is one, and groups, which are read from Authentik when the form opens; a group that makes members administrators of Authentik is marked) and then a one-time recovery link for them. They open the link and choose their own password: this app never sets, sees or keeps one.
The link is in the answer to that one request and nowhere else (not stored, not in the audit log); the audit log has who made which user and who made a link for whom, never the link or a token. If the user is made and the link is not (Authentik needs a recovery flow on the brand — System → Brands),
the page says so and the link is made in Authentik (the user → Create recovery link). Authentik builds the link from the address it was called at, so the integration's address should be the one people use. The token for making users is only used for this; reading Authentik never uses it,
and Stop allowing this on that tab removes it again (the reading token stays).
Users on the same tab, read when the tab opens, lists the people (service accounts — what an outpost or an integration signs in with — are left out), searchable, with whether each is on, whether they are an administrator and when they last signed in, and lets an administrator edit a user's name, email and groups (the user name is shown but not changeable: it is how a person is known elsewhere, and renaming could make them a new person here; Authentik is sent only what differs, as a
PATCH, and groups as what goes in and what comes out on top of the groups the user has now, so a membership somebody gave them meanwhile is kept; a user whose groups Authentik does not say can be renamed but not moved between groups), switch a user off (aPATCHofis_activeand nothing else; they can no longer sign in, nothing of theirs is lost, Switch on brings it back) or delete one (aDELETE, for good: the user name has to be typed, and is checked again by the server against the user as Authentik has them now). Refused, by the server, with the reason: a service account, the account the token itself belongs to, and the last active administrator (so nobody can be locked out, or the sign-in in front of everything else cut off — for an edit, only when it would take them out of every group that makes them one); do those in Authentik. Each is in the audit log (who edited — which fields, never their new values — switched off / on / deleted which user). Switching off or deleting someone in Authentik does not end a session they already have in this app: end it under Users → Signed in now. Lists are read 200 at a time. Groups on the same tab, also read when it opens, lists the groups with how many are in each and lets an administrator make one (a name and nothing else, aPOST /core/groups/withis_superuseralways false: it starts empty and is never a group that makes administrators; a name Authentik already has is its own refusal), rename one, delete one (aDELETE, for good — its members stay, just not in it: the group's name has to be typed and is checked again by the server against the group as Authentik has it now; a group that makes its members administrators of Authentik is refused, since deleting it would take that from all of them at once, possibly from the last administrator) and put users in and take them out (aPATCHofnameand nothing else;POST /core/groups/{id}/add_user/andremove_user/, one user each, so somebody who joined meanwhile is never dropped by a whole list replacing the members). Everything asked is checked first and nothing is changed unless all of it may be: a service account, the token's own account, the last active administrator being taken out of the group that makes them one, and someone whose groups Authentik did not say (when taking them out of such a group) are refused with the reason. If Authentik fails part-way, the answer says how many of the changes had been made, and the audit log (who made, renamed or deleted which group — a deleted one with how many members it had and whether it decided a role here — and who was put in and taken out) has what was done. Whether a group makes its members administrators of Authentik is shown and is not changed or set from here, and no group that makes administrators is deleted here either. A group whose name is one of the admin or operator groups of Settings → Sign-in is marked decides admins / operators here and asks before it is saved: renaming it, or changing who is in it, changes people's roles in this app at their next sign-in. Making a group with such a name says so too (it is empty, so nothing changes until someone is put in it); deleting one asks first and says that people in it lose that role here at their next sign-in. Without it nothing about the page changes for anyone but an administrator, who sees where to add one. The calls (GET /core/groups/,POST /core/users/,POST /core/users/{id}/recovery/,GET /core/users/,GET /core/users/{id}/,GET /core/users/me/,PATCH(is_active, orname,emailandgroups) andDELETE /core/users/{id}/,GET /core/groups/{id}/,POST /core/groups/,PATCHandDELETE /core/groups/{id}/andPOST /core/groups/{id}/add_user/andremove_user/; asking for a link that lasts a day, which a version of Authentik that does not take that sets for itself) are not verified against a live Authentik; the tests use a pretend one. - What it does: every five minutes Authentik is read and stored — its version (and whether a newer one is out), whether a worker is connected, each outpost (the proxy outpost that guards your apps, an LDAP one) with how many instances reported in during the last five minutes and whether they run the right version, the
certificates (those Authentik does not renew by itself) with their expiry, the API tokens and app passwords that expire, and how many sign-ins failed and configuration errors happened in the last day. Apps → Authentik shows it, with what runs out soonest first.
- Alerts (source Authentik; held back by maintenance on the integration): an outpost that serves applications has not reported in (critical — the apps behind it stop letting anyone in; an outpost with no applications is left alone), an outpost runs another version (warning), a certificate runs out (warning within 14 days, critical within 3 and once it has), an API token or app password runs out (warning within 7 days, critical within 2 — the token this app uses to read Authentik is among them), no worker is connected (warning; mail, outpost changes and scheduled tasks stop), 20 or more sign-ins failed in a day (warning; shown as "100 or more" when the log's page is full) and 3 or more configuration errors in a day (warning; a flow or stage that is set up wrongly, with the newest message).
- If Authentik cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be asked (no workers endpoint on an older version) is not a problem: only none is.
/metricshashomelab_authentik_outpost_up,homelab_authentik_workers,homelab_authentik_failed_logins_24handhomelab_authentik_certificate_expiry_daysfor each Authentik that was read lately.
- Not verified against a live Authentik — the endpoints (
/api/v3/admin/version/,/admin/workers/,/outposts/instances/with/health/,/crypto/certificatekeypairs/,/core/tokens/,/events/events/) and their fields are as Authentik publishes them and the reader is tried against a pretend server. Lists are read one page at a time (200 items; 100 events), and the newest events come first. The Diagnostic Log has what was asked and answered. Flows that fail for one user are not counted — only the configuration errors Authentik itself logs; what the app sees of "failing flows" is that.
DNS providers
Cloudflare
- Config fields: API Token
- Auth: Bearer token against the Cloudflare v4 API
- Actions used: list zones, list/create/update/delete DNS records
- Required access: A scoped API token (My Profile → API Tokens → Create Token) with Zone → Zone → Read and Zone → DNS → Edit, restricted to the zone(s) you want managed.
DNS Readalone isn't enough — record add/update/delete needEdit.
Loopia
- Config fields: Username, Password
- Auth: Full account credentials sent on every XML-RPC call — Loopia's API has no scoped API-key concept
- Actions used: list domains/subdomains/zone records, add/remove zone records and subdomains
- Required access: The full Loopia account username and password. There's no way to scope this down at the API level — the credential has the same access as logging into the Loopia customer portal.
Pi-hole
- Config fields: Pi-hole URL, Web password
- Auth: Session login against the Pi-hole v6 API (
/api/auth) using the admin web password, session id cached until it expires - Actions used: read/add/update/delete local DNS "hosts" (A/AAAA) and CNAME records
- Required access: The Pi-hole admin web interface password — Pi-hole v6 doesn't have per-feature roles, so this is effectively full admin access to that Pi-hole instance.
Azure DNS
- Config fields: Tenant ID, Client (application) ID, Client secret, Subscription ID
- Auth: OAuth2 client-credentials (Azure AD app registration / service principal), then Bearer token against Azure Resource Manager
- Actions used: list DNS zones, list/read/create/update/delete record sets
- Required access: The service principal needs the DNS Zone Contributor role (or higher) on the subscription or resource group containing the DNS zone(s) — assign it under Azure Portal → the zone or resource group → Access control (IAM) → Add role assignment.
cPanel
- Config fields: cPanel URL, Username, API Token, allow self-signed certificate
- Auth:
Authorization: cpanel <username>:<apiToken>header (UAPI for reads, API 2 for record writes) - Actions used: list zones/domains, read a zone's records, add/remove a zone record
- Required access: An API token generated under cPanel → Security → Manage API Tokens for the account that owns the domain(s) being managed. cPanel tokens inherit the full account's permissions — there's no separate DNS-only scope to grant.
Technitium DNS Server
- Config fields: Technitium URL, API Token
- Auth: Bearer token
- Actions used: list zones, make a zone, edit a zone (switch it off and on, its options), delete a zone, read zone records, add/delete records (an "update" is implemented as delete + add)
- Making a zone (DNS page → pick the provider → New zone, administrators only — it makes the server an authority for a name; it is the one DNS provider that can): a Primary zone (a domain name such as
home.lan, or an address or network such as192.168.1.0/24, which Technitium turns into the reverse…in-addr.arpazone), a Secondary zone (the servers that hold it, comma-separated) or a Forwarder zone (the DNS server to pass questions to — an address, a name, a URL orthis-server— the protocol, UDP unless told, and whether to check DNSSEC, off unless told). It isPOST /api/zones/createwith the name and the type (and, for a Secondary,primaryNameServerAddresses; for a Forwarder,initializeForwarder,forwarder,protocolanddnssecValidation). The name is written lower case without a trailing dot and must be ASCII (a name with other letters in itsxn--form); anything else is refused before Technitium is asked, and what Technitium says when it refuses (a zone that is there already) is shown as it was said. The new zone opens when it is made; a Primary zone has the records Technitium makes for it and the rest are added as usual. It is written in the audit log (who made which zone, of which kind). - Editing a zone (DNS page → open the zone → Edit zone, administrators only; the server's own internal zones are never touched):
- Switch off / on —
POST /api/zones/disableand/api/zones/enable. Off, the server stops answering for the zone; its records stay, and on brings it all back. A switched-off zone is marked off in the zone list, and the Technitium integration does not judge it. - Who may ask the zone (
queryAccess: everyone, nobody, only private networks, only the zone's name servers, only the networks listed, or the name servers and the networks listed), who may copy it (zoneTransfer, the same without the private-network choice, and the TSIG keys the server has that a transfer may be limited to) and who is told when it changes (notify: nobody, the zone's name servers, only the servers listed, or both). A choice that goes by a list needs it: networks are addresses or CIDR networks, one to a line and in order, with!in front to refuse one; servers are addresses. It isGET /api/zones/options/get(with the TSIG key names) andPOST /api/zones/options/set. - What a kind of zone has: a Primary or Secondary zone has all three; a Forwarder or Stub or Catalog zone only who may ask it, and a secondary catalog none; anything else is refused with the reason, before Technitium is asked. What is not changed is not sent: only the groups that differ go, each whole (its mode and the list it uses), because the documentation does not say what Technitium does with a setting that is left out of the call. So afterwards the zone is read again, and anything else it says about the zone that moved (dynamic updates, its catalog …) is named on the page and in the audit log — a warning, not an undo. Written in the audit log: who switched which zone off or on, and which groups of options were changed (never the lists). The options call needs the token's user to have Zones: Modify (and, as the documentation words it, Zone: Delete on that zone). Not verified against a live install.
- Switch off / on —
- Deleting a zone (DNS page → open the zone → Delete zone, administrators only): the zone and every record in it go, for good —
POST /api/zones/deletewith the zone's name. The zone's name has to be typed, and the server checks it again: it must be the name the zone has now and the provider must list the zone, so a page that is minutes old, a wrong id, or one of the server's own internal zones (which are not listed) cannot be deleted by mistake; an id that is not a zone name as written (lower case, no trailing dot) is refused. What this app has cached of the zone and its records is dropped with it (the registration of the domain on the Domain names tab is not touched). What Technitium says when it refuses — a token that may not delete zones — is shown, and then nothing is changed here. It is written in the audit log (who deleted which zone, and how many of its records were cached). Not verified against a live install: the calls are as Technitium's API documentation has them. - Required access: A token tied to a Technitium user account with Zones: View + Modify permission — view-only will fail on record changes (updates are add/delete calls under the hood) and on making a zone. Deleting a zone needs Zones: Delete, which is a permission of its own.
- This is the DNS provider (zones and records, on the DNS page). How the server is doing — queries, blocking, zone health, a real DNS test, alerts — is a separate integration with its own token: see Technitium DNS under the integrations above.