More docs

This commit is contained in:
Philipp Heckel 2022-02-03 13:40:19 -05:00
parent 68351230f3
commit 1c9766b8fd
2 changed files with 79 additions and 3 deletions

View file

@ -131,7 +131,8 @@ Access control entries can be applied to users as well as the special everyone u
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-file` is the user/access database; it is created automatically if it doesn't already exist; suggested
location `/var/lib/ntfy/user.db` (easiest if deb/rpm package is used)
* `auth-default-access` defines the default/fallback access if no access control entry is found; it can be * `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`. set to `read-write` (default), `read-only`, `write-only` or `deny-all`.
@ -166,8 +167,7 @@ ntfy user change-role phil admin # Make user phil an admin
The access control list (ACL) **manages access to topics for non-admin users, and for anonymous access**. Each entry The access control list (ACL) **manages access to topics for non-admin users, and for anonymous access**. Each entry
represents the access permissions for a user to a specific topic or topic pattern. represents the access permissions for a user to a specific topic or topic pattern.
**Modifying the ACL:** The ACL can be displayed or modified with the `ntfy access` command:
The access control list can be displayed or modified with the `ntfy access` command:
``` ```
ntfy access # Shows the entire access control list ntfy access # Shows the entire access control list

View file

@ -941,6 +941,81 @@ title `You've Got Mail` to topic `sometopic` (see [ntfy.sh/sometopic](https://nt
## Advanced features ## Advanced features
### Authentication
Depending on whether the server is configured to support [access control](config.md#access-control), some topics
may be read/write protected so that only users with the correct credentials can subscribe or publish to them.
To publish/subscribe to protected topics, you can use [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication)
with a valid username/password. For your self-hosted server, **be sure to use HTTPS to avoid eavesdropping** and exposing
your password.
Here's a simple example:
=== "Command line (curl)"
```
curl \
-u phil:mypass \
-d "Look ma, with auth" \
https://ntfy.example.com/mysecrets
```
=== "ntfy CLI"
```
ntfy publish \
-u phil:mypass \
ntfy.example.com/mysecrets \
"Look ma, with auth"
```
=== "HTTP"
``` http
POST /mysecrets HTTP/1.1
Host: ntfy.example.com
Authorization: Basic cGhpbDpteXBhc3M=
Look ma, with auth
```
=== "JavaScript"
``` javascript
fetch('https://ntfy.example.com/mysecrets', {
method: 'POST', // PUT works too
body: 'Look ma, with auth',
headers: {
'Authorization': 'Basic cGhpbDpteXBhc3M='
}
})
```
=== "Go"
``` go
req, _ := http.NewRequest("POST", "https://ntfy.example.com/mysecrets",
strings.NewReader("Look ma, with auth"))
req.Header.Set("Authorization", "Basic cGhpbDpteXBhc3M=")
http.DefaultClient.Do(req)
```
=== "Python"
``` python
requests.post("https://ntfy.example.com/mysecrets",
data="Look ma, with auth",
headers={
"Authorization": "Basic cGhpbDpteXBhc3M="
})
```
=== "PHP"
``` php-inline
file_get_contents('https://ntfy.example.com/mysecrets', false, stream_context_create([
'http' => [
'method' => 'POST', // PUT also works
'header' =>
'Content-Type: text/plain\r\n' .
'Authorization: Basic cGhpbDpteXBhc3M=',
'content' => 'Look ma, with auth'
]
]));
```
### Message caching ### Message caching
!!! info !!! info
If `Cache: no` is used, messages will only be delivered to connected subscribers, and won't be re-delivered if a If `Cache: no` is used, messages will only be delivered to connected subscribers, and won't be re-delivered if a
@ -1133,3 +1208,4 @@ and can be passed as **HTTP headers** or **query parameters in the URL**. They a
| `X-Cache` | `Cache` | Allows disabling [message caching](#message-caching) | | `X-Cache` | `Cache` | Allows disabling [message caching](#message-caching) |
| `X-Firebase` | `Firebase` | Allows disabling [sending to Firebase](#disable-firebase) | | `X-Firebase` | `Firebase` | Allows disabling [sending to Firebase](#disable-firebase) |
| `X-UnifiedPush` | `UnifiedPush`, `up` | [UnifiedPush](#unifiedpush) publish option, only to be used by UnifiedPush apps | | `X-UnifiedPush` | `UnifiedPush`, `up` | [UnifiedPush](#unifiedpush) publish option, only to be used by UnifiedPush apps |
| `Authorization` | - | If supported by the server, you can [login to access](#authentication) protected topics |