diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md new file mode 100644 index 0000000..88b5de9 --- /dev/null +++ b/INTEGRATIONS.md @@ -0,0 +1,102 @@ +# 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 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. + +## 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 +- **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. +- **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) +- **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. + +## 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. diff --git a/README.md b/README.md index 6506680..8f03658 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,9 @@ All modules from the original plan are built: All six integrations follow the same config-in-UI + encrypted-credentials pattern, added (and edited — e.g. to rotate an expired API token without recreating the whole integration) through **Integrations → Manage -integrations**. +integrations**. See [INTEGRATIONS.md](INTEGRATIONS.md) for exactly what +credential to create and what access it needs in each target system, +for every integration and DNS provider. **Verified for real, end to end**: every module above — including all six integrations, both their read-only views and their write actions