diff --git a/README.md b/README.md index 7839ecd..d4fd5da 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ A few things bend to taste in **Settings**: 1. **Install** NOVA — either from [F-Droid](https://f-droid.org/packages/io.github.nofuturekid.nova/) (stable releases only) or as the latest APK from the [Releases page](https://github.com/hellwand/nova/releases). (For the APK, Android will ask you to allow installing from your browser/files app — that's expected for apps outside the Play Store.) - Betas are GitHub pre-releases, so they come as an APK from the Releases page. NOVA tells you when a new version is out (switch on **Include pre-releases** in Settings for betas) and sends your browser to the APK; Obtainium works too. - The F-Droid build and the GitHub APK are signed with different keys, so switching between them needs an uninstall first (your saved servers and API keys go with the app). See [ADR-0040](./docs/adr/0040-fdroid-play-distribution-flavors.md). -2. On your Unraid server, generate an **API key**: web UI → _Settings → Management Access → API / Connect_. +2. On your Unraid server, generate an **API key**: web UI → _Settings → Management Access → API / Connect_ (which rights it needs: [API key permissions](#api-key-permissions)). 3. Open the app → **Add server** and fill in: - **Server name** — a label, e.g. `Tower` - **Local host** — its address on your home network, e.g. `192.168.1.10`. Flip **Use SSL (HTTPS)** if the server uses HTTPS; for a self-signed certificate also enable **Trust self-signed certificate** and confirm it once @@ -105,6 +105,65 @@ This is Google's rating of the file, not a finding about what NOVA does; Google Requires an Unraid 7.x server with the API/Connect plugin enabled. All app features need Unraid API **4.30.0 or newer**; the live network speed needs **4.35.0 or newer** (API versions, not Unraid OS versions). On an older API some screens fail to load. +## API key permissions + +NOVA talks to your server with one API key per server. **NOVA never needs the ADMIN role or any permission to manage API keys.** Pick whichever of these suits you: + +- **Simplest, read-only: a key with the VIEWER role.** It can see everything NOVA shows and cannot change anything, except that servers older than Unraid API 4.37.4 let every key archive and delete notifications [^4]. Buttons that need more rights are refused by the server. +- **Simplest, full control: a key with the ADMIN role.** It can do everything NOVA offers. It can also do much more, which NOVA never uses. +- **Least privilege: the VIEWER role plus only the controls you want.** See the table below. + +### What each feature needs + +A permission is written as `RESOURCE:ACTION`, for example `DOCKER:UPDATE_ANY`. The action must match exactly: `UPDATE_ANY` does not include `READ_ANY`, and the `_OWN` actions never count. The last column says how well a row is established: **Live** means we ran it against a real server with a key that holds the permission; **Refusal live** means we saw a key without the permission refused, while that the named permission is enough comes from the Unraid API's source code; **Source** means only from the source code (see the notes below the table). + +| NOVA feature | A key needs | Established | +| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------- | +| See everything (Overview, metrics, network, array, containers and logs, VMs, notifications, plugins) | Role **VIEWER** | Live [^1] | +| Start, stop, restart, pause, resume and update one container | `DOCKER:UPDATE_ANY`, on top of VIEWER | Live [^3] | +| Update all containers | `DOCKER:UPDATE_ANY` | Source [^6] | +| Start, stop, pause, resume, reboot, reset and force-stop VMs | `VMS:UPDATE_ANY` | Refusal live [^7] | +| Start or stop the array; start, pause, resume or cancel a parity check | `ARRAY:UPDATE_ANY` | Source [^6] | +| Archive, mark as unread, archive all notifications | `NOTIFICATIONS:UPDATE_ANY` | Refusal live [^4] | +| Delete a notification, delete all archived | `NOTIFICATIONS:DELETE_ANY` | Refusal live [^4] | +| Never needed | The ADMIN role, any `API_KEY` or `PERMISSION` permission, any `CREATE_ANY` permission | Source | + +A least-privilege key is the VIEWER role plus the explicit permissions for the actions you want, for example `DOCKER:UPDATE_ANY`, `VMS:UPDATE_ANY`, `ARRAY:UPDATE_ANY`, `NOTIFICATIONS:UPDATE_ANY` and `NOTIFICATIONS:DELETE_ANY` for full control. Leave out the ones for things you do not want NOVA to do. The server reports a key's effective rights as the role's rights plus its explicit permissions (confirmed live for VIEWER plus `DOCKER:UPDATE_ANY`). Only the container part of this recipe was tried with such a key. + +Do not build a key from read permissions only. The server's command line tool cannot create a key without a role (it requires one), and we did not check whether the web interface can. As background, from the server's source and not verified with such a key: reading everything without the VIEWER role would need `READ_ANY` on `INFO`, `DISPLAY`, `ARRAY`, `DOCKER`, `VMS`, `NOTIFICATIONS`, `CONFIG` and `ME`. + +[^1]: Checked on 2026-11-13 against a server running Unraid 7.4.0 with Unraid API 4.37.11: a key with only the VIEWER role got HTTP 200 with data on every screen's query; the logs query was checked only as far as the permission (it was sent with an unknown container id). + +[^3]: Checked live on the same server: a VIEWER key was refused when it started, stopped, paused, unpaused or updated a container, and a VIEWER key with `DOCKER:UPDATE_ANY` got past the permission check (tried with an id that does not exist, so nothing could change). NOVA restarts a container as a stop followed by a start, so a restart needs the same `DOCKER:UPDATE_ANY`. + +[^4]: Servers before API 4.37.4 do not check these two permissions at all (read from the source of 4.37.3 and 4.37.4), so every key can archive and delete notifications there. On 4.37.11 the refusal of a VIEWER key was seen live for archive, mark as unread and delete. + +[^6]: Not testable without acting on a server (they have no id that could be faked), so this row is from the source code at 4.37.11 only. + +[^7]: Live: a key without `VMS:UPDATE_ANY` is refused on VM start and stop. Not tried with a key that holds it, and not every VM action was probed. + +### Where to set the key and its permissions + +In the Unraid web interface open _Settings → Management Access → API_ (Unraid's documentation lists the keys under _Management Access_, as _API Keys_). When you create a key you choose its role and, if you want, individual permissions. The upstream form offers both ([source](https://github.com/unraid/api/blob/v4.37.11/web/src/components/ApiKey/ApiKeyCreate.vue)); we have not looked at how the dialog is laid out on every Unraid version. The same can be done on the server's command line, following Unraid's [API key documentation](https://docs.unraid.net/API/programmatic-api-key-management/), which also recommends specific permissions over the ADMIN role: + +```sh +unraid-api apikey --create --name "NOVA" --roles VIEWER \ + --permissions "DOCKER:UPDATE_ANY,VMS:UPDATE_ANY,ARRAY:UPDATE_ANY,NOTIFICATIONS:UPDATE_ANY,NOTIFICATIONS:DELETE_ANY" +``` + +The command shape, with the VIEWER role and `DOCKER:UPDATE_ANY`, was run live and works; the other permissions in the example were not tried. If you change a key's permissions later, the key itself stays the same, so you do not need to enter it again in NOVA. + +### When a permission is missing + +The server decides, not NOVA. An action the key may not do is refused with the message **"Forbidden resource"** and nothing changes on the server (confirmed live for container actions with a VIEWER key). A read the key may not do is refused the same way, so that screen fails to load. A key the server does not accept at all is answered with "API key validation failed". A later version of NOVA will hide the controls a key cannot use instead of showing buttons that are refused. + +### Which Unraid API version you need + +Every screen needs Unraid API **4.30.0 or newer**; live network speed needs **4.35.0 or newer**. These are versions of the Unraid API, not of Unraid OS. They are different numbers. + +To see which API version you have, open _Settings → Management Access → API_ in the web interface, where the installed Unraid API version should be shown [^5]. As a rule of thumb, every Unraid OS release from 7.2.5 on ships an API of 4.30.0 or newer (we checked 7.2.5, 7.2.8, 7.3.0, 7.3.2 and 7.4.0 against the release notes). The reverse does not hold: the API version does not rise steadily with the OS version, for example 7.2.8 ships 4.36.1 and 7.3.2 ships 4.35.1. + +[^5]: We have not checked what that page shows on each Unraid version. If you cannot find the version there, Unraid's release notes for your OS version name the API version that ships with it. ## Trademark attribution Unraid® is a registered trademark of Lime Technology, Inc. NOVA is an independent, community-built client; it uses the term solely to describe compatibility with the Unraid® operating system and is not affiliated with, endorsed by, or supported by Lime Technology. The project was previously named `UnraidControl`; the rename to NOVA in v0.1.33 was made to comply with the Unraid® Trademark Policy — see [ADR-0038](./docs/adr/0038-lime-trademark-compliance-rename-pending.md) and [ADR-0039](./docs/adr/0039-rename-to-nova.md). diff --git a/site/index.html b/site/index.html index b1bb118..973cf62 100644 --- a/site/index.html +++ b/site/index.html @@ -375,6 +375,41 @@

Set it up

+

Which API key

+ +

+ NOVA never needs the ADMIN role or any permission to manage API + keys. If a key lacks a permission, the server refuses the action + and changes nothing; a later version of NOVA will hide the controls + a key cannot use. Set the role and permissions when you create the + key, in Settings → Management Access → API. The + full table, with what was checked on a real server and what comes + from the Unraid API’s source code (not every row was tried live), is in the + README. +

+

Verify the GitHub APK

The APKs on GitHub are signed with one release key. Its certificate