Docs docs docs docs docs

docs/config.md

@@ -122,14 +122,14 @@ Please also refer to the [rate limiting](#rate-limiting) settings below, specifi
 and `visitor-attachment-daily-bandwidth-limit`. Setting these conservatively is necessary to avoid abuse.
 
 ## Access control
-By default, the ntfy server is open for everyone, meaning **everyone can read and write to any topic**. To restrict access
+By default, the ntfy server is open for everyone, meaning **everyone can read and write to any topic** (this is how
-to your own server, you can optionally configure authentication and authorization. 
+ntfy.sh is configured). To restrict access to your own server, you can optionally configure authentication and authorization. 
 
 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:
+To set up auth, simply **configure the following two options**:
 
 * `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
@@ -137,7 +137,7 @@ To set up auth, simply configure the following two options:
 
 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 
+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.
 
 ### Users and roles
@@ -163,9 +163,46 @@ 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
+The access control list (ACL) **manages access to topics for non-admin users, and for anonymous access**. Each entry 
-a user to a specific topic or topic pattern. Here's an example ACL:
+represents the access permissions for a user to a specific topic or topic pattern. 
 
+**Modifying the ACL:**   
+The access control list can be displayed or 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
+```
+
+A `USERNAME` is an existing user, as created with `ntfy user add` (see [users and roles](#users-and-roles)), or the 
+anonymous user `everyone` or `*`, which represents clients that access the API without username/password.
+
+A `TOPIC` is either a specific topic name (e.g. `mytopic`, or `phil_alerts`), or a wildcard pattern that matches any
+number of topics (e.g. `alerts_*` or `ben-*`). Only the wildcard character `*` is supported. It stands for zero to any 
+number of characters.
+
+A `PERMISSION` is any of the following supported permissions:
+
+* `read-write` (alias: `rw`): Allows [publishing messages](publish.md) to the given topic, as well as 
+  [subscribing](subscribe/api.md) and reading messages
+* `read-only` (aliases: `read`, `ro`): Allows only subscribing and reading messages, but not publishing to the topic
+* `write-only` (aliases: `write`, `wo`): Allows only publishing to the topic, but not subscribing to it
+* `deny` (alias: `none`): Allows neither publishing nor subscribing to a topic 
+
+**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 ACL:**
 ```
 $ ntfy access
 User phil (admin)
@@ -185,40 +222,6 @@ User `ben` has three topic-specific entries. He can read, but not write to topic
 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`:
 
@@ -715,7 +718,7 @@ CLI option (e.g. `--listen-http :80`. Here's a list of all available options. Al
 variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`).
 
 | Config option                              | Env variable                                    | Format                                              | Default | Description                                                                                                                                                                                                                     |
-|--------------------------------------------|-------------------------------------------------|------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|--------------------------------------------|-------------------------------------------------|-----------------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `base-url`                                 | `NTFY_BASE_URL`                                 | *URL*                                               | -       | Public facing base URL of the service (e.g. `https://ntfy.sh`)                                                                                                                                                                  |
 | `listen-http`                              | `NTFY_LISTEN_HTTP`                              | `[host]:port`                                       | `:80`   | Listen address for the HTTP web server                                                                                                                                                                                          |
 | `listen-https`                             | `NTFY_LISTEN_HTTPS`                             | `[host]:port`                                       | -       | Listen address for the HTTPS web server. If set, you also need to set `key-file` and `cert-file`.                                                                                                                               |
@@ -725,6 +728,8 @@ variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`).
 | `firebase-key-file`                        | `NTFY_FIREBASE_KEY_FILE`                        | *filename*                                          | -       | If set, also publish messages to a Firebase Cloud Messaging (FCM) topic for your app. This is optional and only required to save battery when using the Android app. See [Firebase (FCM](#firebase-fcm).                        |
 | `cache-file`                               | `NTFY_CACHE_FILE`                               | *filename*                                          | -       | If set, messages are cached in a local SQLite database instead of only in-memory. This allows for service restarts without losing messages in support of the since= parameter. See [message cache](#message-cache).             |
 | `cache-duration`                           | `NTFY_CACHE_DURATION`                           | *duration*                                          | 12h     | Duration for which messages will be buffered before they are deleted. This is required to support the `since=...` and `poll=1` parameter. Set this to `0` to disable the cache entirely.                                        |
+| `auth-file`                                | `NTFY_AUTH_FILE`                                | *filename*                                          | -       | Auth database file used for access control. If set, enables authentication and access control. See [access control](#access-control).                                                                                           |
+| `auth-default-access`                      | `NTFY_AUTH_DEFAULT_ACCESS`                      | `read-write`, `read-only`, `write-only`, `deny-all` | -       | Default permissions if no matching entries in the auth database are found. Default is `read-write`.                                                                                                                             |
 | `behind-proxy`                             | `NTFY_BEHIND_PROXY`                             | *bool*                                              | false   | If set, the X-Forwarded-For header is used to determine the visitor IP address instead of the remote address of the connection.                                                                                                 |
 | `attachment-cache-dir`                     | `NTFY_ATTACHMENT_CACHE_DIR`                     | *directory*                                         | -       | Cache directory for attached files. To enable attachments, this has to be set.                                                                                                                                                  |
 | `attachment-total-size-limit`              | `NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT`              | *size*                                              | 5G      | Limit of the on-disk attachment cache directory. If the limits is exceeded, new attachments will be rejected.                                                                                                                   |
@@ -760,6 +765,9 @@ NAME:
 USAGE:
    ntfy serve [OPTIONS..]
 
+CATEGORY:
+   Server commands
+
 DESCRIPTION:
    Run the ntfy server and listen for incoming requests
    
@@ -781,6 +789,8 @@ OPTIONS:
    --firebase-key-file value, -F value               Firebase credentials file; if set additionally publish to FCM topic [$NTFY_FIREBASE_KEY_FILE]
    --cache-file value, -C value                      cache file used for message caching [$NTFY_CACHE_FILE]
    --cache-duration since, -b since                  buffer messages for this time to allow since requests (default: 12h0m0s) [$NTFY_CACHE_DURATION]
+   --auth-file value, -H value                       auth database file used for access control [$NTFY_AUTH_FILE]
+   --auth-default-access value, -p value             default permissions if no matching entries in the auth database are found (default: "read-write") [$NTFY_AUTH_DEFAULT_ACCESS]
    --attachment-cache-dir value                      cache directory for attached files [$NTFY_ATTACHMENT_CACHE_DIR]
    --attachment-total-size-limit value, -A value     limit of the on-disk attachment cache (default: 5G) [$NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT]
    --attachment-file-size-limit value, -Y value      per-file attachment size limit (e.g. 300k, 2M, 100M) (default: 15M) [$NTFY_ATTACHMENT_FILE_SIZE_LIMIT]