From 0ad85262c16c71a76ad2a92a469d411211fc0790 Mon Sep 17 00:00:00 2001 From: Philipp Heckel Date: Wed, 2 Feb 2022 19:26:17 -0500 Subject: [PATCH] More docs; this will never end --- cmd/access.go | 2 +- docs/config.md | 94 +++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 87 insertions(+), 9 deletions(-) diff --git a/cmd/access.go b/cmd/access.go index 3a2ebb71..95451512 100644 --- a/cmd/access.go +++ b/cmd/access.go @@ -50,7 +50,7 @@ Arguments: - deny (alias: none) Examples: - ntfy access + ntfy access # Shows entire access control list ntfy access phil # Shows access for user phil ntfy access phil mytopic rw # Allow read-write access to mytopic for user phil ntfy access everyone mytopic rw # Allow anonymous read-write access to mytopic diff --git a/docs/config.md b/docs/config.md index 79c3fbd1..f233215a 100644 --- a/docs/config.md +++ b/docs/config.md @@ -125,21 +125,99 @@ and `visitor-attachment-daily-bandwidth-limit`. Setting these conservatively is By default, the ntfy server is open for everyone, meaning **everyone can read and write to any topic**. To restrict access to your own server, you can optionally configure authentication and authorization. -ntfy's auth is implemented with a simple SQLite-based backend. It implements two roles (`user` and `admin`) and per-topic -`read` and `write` permissions using an access control list (ACL). Access control entries can be applied to users as well -as the special everyone user (`*`), which represents anonymous API access. +ntfy's auth is implemented with a simple [SQLite](https://www.sqlite.org/)-based backend. It implements two roles +(`user` and `admin`) and per-topic `read` and `write` permissions using an [access control list (ACL)](https://en.wikipedia.org/wiki/Access-control_list). +Access control entries can be applied to users as well as the special everyone user (`*`), which represents anonymous API access. To set up auth, simply configure the following two options: -* `auth-file` is the SQLite user/access database; it is created automatically if it doesn't already exist +* `auth-file` is the user/access database; it is created automatically if it doesn't already exist * `auth-default-access` defines the default/fallback access if no access control entry is found; it can be set to `read-write` (default), `read-only`, `write-only` or `deny-all`. -### Managing users + access -Once configured, you can use the `ntfy user` command to add/modify/delete users, and the `ntfy access` command -to modify the access control list to allow/deny access to specific topic or topic patterns. +Once configured, you can use the `ntfy user` command to [add or modify users](#users-and-roles), and the `ntfy access` command +lets you [modify the access control list](#access-control-list-acl) for specific users and topic patterns. Both of these +commands directly edit the auth database (as defined in `auth-file`), so they only work on the server, and only if the user +accessing them has the right permissions. -XXXXXXXXXXXXXXXXXXXx +### Users and roles +The `ntfy user` command allows you to add/remove/change users in the ntfy user database, as well as change +passwords or roles (`user` or `admin`). In practice, you'll often just create one admin +user with `ntfy user add --role=admin ...` and be done with all this (see [example below](#example-private-instance)). + +**Roles:** + +* Role `user` (default): Users with this role have no special permissions. Manage access using `ntfy access` + (see [below](#access-control-list-acl)). +* Role `admin`: Users with this role can read/write to all topics. Granular access control is not necessary. + +**Example commands** (type `ntfy user --help` or `ntfy user COMMAND --help` for more details): + +``` +ntfy user list # Shows list of users +ntfy user add phil # Add regular user phil +ntfy user add --role=admin phil # Add admin user phil +ntfy user del phil # Delete user phil +ntfy user change-pass phil # Change password for user phil +ntfy user change-role phil admin # Make user phil an admin +``` + +### Access control list (ACL) +The access control list manages access to topics for non-admin users. Each entry represents the access permissions for +a user to a specific topic or topic pattern. Here's an example ACL: + +``` +$ ntfy access +User phil (admin) +- read-write access to all topics (admin role) +User ben (user) +- read-write access to topic garagedoor +- read-write access to topic alerts* +- read-only access to topic furnace +User * (anonymous) +- read-only access to topic announcements +- read-only access to topic server-stats +- no access to any (other) topics (server config) +``` + +In this example, `phil` has the role `admin`, so he has read-write access to all topics (no ACL entries are necessary). +User `ben` has three topic-specific entries. He can read, but not write to topic `furnace`, and has read-write access +to topic `garagedoor` and all topics starting with the word `alerts` (wildcards). Clients that are not authenticated +(called `*`/`everyone`) only have read access to the `announcements` and `server-stats` topics. + +**Modifying the ACL** +The access control list can be modified with the `ntfy access` command: + +``` +ntfy access # Shows the entire access control list +ntfy access USERNAME # Shows access control entries for USERNAME +ntfy access USERNAME TOPIC PERMISSION # Allow/deny access for USERNAME to TOPIC +``` +XXXXXXXXXXXXXXXXXXXXXXXX + +USERNAME an existing user, as created with 'ntfy user add', or "everyone"/"*" +to define access rules for anonymous/unauthenticated clients +TOPIC name of a topic with optional wildcards, e.g. "mytopic*" + +**Permissions:** + +* read-write (alias: rw) +- read-only (aliases: read, ro) +- write-only (aliases: write, wo) +- deny (alias: none) + +**Example commands** (type `ntfy access --help` for more details): + +``` +ntfy access # Shows entire access control list +ntfy access phil # Shows access for user phil +ntfy access phil mytopic rw # Allow read-write access to mytopic for user phil +ntfy access everyone mytopic rw # Allow anonymous read-write access to mytopic +ntfy access everyone "up*" write # Allow anonymous write-only access to topics "up..." +ntfy access --reset # Reset entire access control list +ntfy access --reset phil # Reset all access for user phil +ntfy access --reset phil mytopic # Reset access for user phil and topic mytopic +``` ### Example: Private instance The easiest way to configure a private instance is to set `auth-default-access` to `deny-all` in the `server.yml`: