# 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 ### 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==` 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, read backup job schedules and recent `vzdump` task 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. - **Notes:** self-signed certificates are supported via the "Allow self-signed certificate" checkbox — common for an internal PVE host. ### 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 `limit` of 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 ` header - **Actions used:** list repos, list Actions workflow runs, re-run failed jobs in a run - **Required access:** A personal access token with **`repo`** scope (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 the `repository` and `write: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](docs/MONITORING.md#endpoint-checks-and-heartbeats)). 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](docs/MONITORING.md#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, and `GET /api/vulnerabilities?env=&severity=critical&limit=100` only where that count is above zero (needs the *images: view* permission). Nothing is scanned from here. **Critical** findings are a warning per Docker host (a setting turns it off — see [MONITORING.md](docs/MONITORING.md#docker-containers-that-are-broken)); 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 under `summary`; the reader follows the code and reads nothing it does not find as *unknown*. ### 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 `login` event over `ws://` or `wss://` to the same address as the integration, so use an `https://` 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:///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:///api/duplicati-report/hlm_d_… --send-http-result-output-format=Json --send-http-level=All ``` `send-http-level=All` matters: 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. 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 and the first message. 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 among `Extra`). A report the app cannot read is answered "OK (not a report this app can read)" and the page does not learn from it. - What it does with them — alerts, `/metrics`, the history — is in [MONITORING.md](docs/MONITORING.md#duplicati-backups). ### Proxmox Backup Server - **Config fields:** Proxmox Backup Server URL, API token ID, API token secret, allow self-signed certificate - **Auth:** `PBSAPIToken=:` 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.Audit` on 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 `vzdump` push 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.state` on 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 `PBSAPIToken` header 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 `SELECT` joining 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: ```sql CREATE USER 'homelab_manager'@'%' IDENTIFIED BY 'a-strong-password'; GRANT SELECT ON osticket.* TO 'homelab_manager'@'%'; FLUSH PRIVILEGES; ``` (narrow the host part — `'%'` — 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 `state` classification, 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** (Settings → Notifications → 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
/api/tickets.json` with the key in an `X-API-Key` header. - **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 Settings → Notifications → Alert tickets, a subject, the problem's text and a link back to this app, optionally a help topic and priority id — with `autorespond` off (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 a `data:` 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 `osticket` and the prefix if yours differ): ```sql 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** (Settings → Notifications → 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). - **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 `token` header (and `phpipam-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 `token` header, 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:///proxy/network/integration/v1/…`, on a self-hosted Network application at `https://: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//…`, or `/api/s//…` self-hosted), and the session is logged out after each read. - **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, 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. **Nothing is ever written** to NPM. - **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. - **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 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/` and `GET /api/states` are 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** (`public` when blank; stored encrypted). - **Required access:** read only. **NUT:** `upsd` must listen on an address this server can reach (`LISTEN` in `upsd.conf`; the default is only the machine itself) and, if `upsd.users`/`ACL` limit who may ask, allow this host. Only `LIST UPS` and `LIST VAR ` are sent — no command, no login. **SNMP:** version 2c, a `GET` of 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; NUT `LB`, SNMP battery low or depleted), **the UPS asks for its battery to be replaced** (warning; NUT `RB`), and **a load of 90 % or more, or an overload** (warning; NUT `OVER`). - **It is a node in the dependency map** (`integration:`): 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. - `/metrics` has `homelab_ups_on_battery`, `homelab_ups_battery_charge_percent`, `homelab_ups_runtime_seconds`, `homelab_ups_load_percent` and `homelab_ups_input_volts` for each UPS that was read lately. - **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 watching` to 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. - `/metrics` has `homelab_jellyfin_streams`, `homelab_jellyfin_transcodes` and `homelab_jellyfin_pending_restart` for 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.statistics` and `job.read` (`queue.read` on 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*. - `/metrics` has `homelab_immich_photos`, `homelab_immich_videos`, `homelab_immich_library_bytes`, `homelab_immich_disk_used_percent` and `homelab_immich_failed_jobs` for 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/queues` on 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.php` is 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. - `/metrics` has `homelab_nextcloud_maintenance_mode`, `homelab_nextcloud_free_bytes`, `homelab_nextcloud_active_users_24h` and `homelab_nextcloud_app_updates` for each Nextcloud that was read lately. - **Not verified against a live Nextcloud** — `/status.php` and the Monitoring app's `/ocs/v2.php/apps/serverinfo/api/v1/info` are 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). ### 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.cloud` reachable 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](docs/MONITORING.md#hetzner-cloud). - 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. - `/metrics` has `homelab_hetzner_server_running`, `homelab_hetzner_traffic_outgoing_bytes`, `homelab_hetzner_traffic_included_bytes` and `homelab_hetzner_monthly_cost`. - **Not verified against a live project** — the endpoints (`/servers`, `/volumes`, `/images?type=snapshot` and `type=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 (the `gross` prices): check it against Hetzner's invoice the first time. Dedicated (Robot) servers and Hetzner Storage Boxes are a different API and are not read. ### 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 older `Token` tokens and NetBox 4.5's `nbt_…` 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. - `/metrics` has `homelab_netbox_workers`, `homelab_netbox_devices` and `homelab_netbox_ip_addresses` for 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/workflows` and `GET /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. - `/metrics` has `homelab_n8n_workflows`, `homelab_n8n_workflows_active` and `homelab_n8n_workflows_failing` for 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*. - `/metrics` has `homelab_paperless_documents`, `homelab_paperless_inbox`, `homelab_paperless_failed_imports` and `homelab_paperless_component_ok` for 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/targets` and `/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"` (or `page`), a warning otherwise. Pending alerts, `info` ones 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](docs/PROMETHEUS-GRAFANA.md)), and exporting what Prometheus said into Prometheus would only go round in a circle. - **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) 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. - **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. - `/metrics` has `homelab_authentik_outpost_up`, `homelab_authentik_workers`, `homelab_authentik_failed_logins_24h` and `homelab_authentik_certificate_expiry_days` for 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 Read` alone isn't enough — record add/update/delete need `Edit`. ### 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 :` 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, read zone records, add/delete records (an "update" is implemented as delete + add) - **Required access:** A token tied to a Technitium user account with **Zones: View + Modify** permission — view-only will fail on record changes since updates are add/delete calls under the hood.