vbatts/ntfy
1
0
Fork 0
Code Pull requests Activity

Emoji reference and such

Browse source
This commit is contained in:
Philipp Heckel 2021-12-02 12:04:22 -05:00
parent 62f4d9963e
commit 29f2196376
8 changed files with 2049 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
docs/config.md
View file

@ -24,6 +24,9 @@ variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`).
| Config option | Env variable | Format | Default | Description |
|---|---|---|---|---|
| `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`. |
| `key-file` | `NTFY_KEY_FILE` | *filename* | - | HTTPS/TLS private key file, only used if `listen-https` is set. |
| `cert-file` | `NTFY_CERT_FILE` | *filename* | - | HTTPS/TLS certificate file, only used if `listen-https` is set. |
| `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. |
| `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. |
| `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. |
@ -67,20 +70,43 @@ firebase-key-file: "/etc/ntfy/ntfy-sh-firebase-adminsdk-ahnce-9f4d6f14b5.json"
## Behind a proxy (TLS, etc.)
!!! warning
If you are behind a proxy, you must set the `behind-proxy` flag. Otherwise all visitors are rate limited
If you are running ntfy behind a proxy, you must set the `behind-proxy` flag. Otherwise all visitors are rate limited
as if they are one.
**TLS/SSL*: ntfy does not support TLS at this time.
If you are running ntfy behind a proxy (e.g. nginx, HAproxy or Apache), you should set the `behind-proxy` flag. This will
instruct the [rate limiting](#rate-limiting) logic to use the `X-Forwarded-For` header as the primary identifier
**Rate limiting:** If you are running ntfy behind a proxy (e.g. nginx, HAproxy or Apache), you should set the `behind-proxy`
flag. This will instruct the [rate limiting](#rate-limiting) logic to use the `X-Forwarded-For` header as the primary
identifier for a visitor, as opposed to the remote IP address. If the `behing-proxy` flag is not set, all visitors will
be counted as one, because from the perspective of the ntfy server, they all share the proxy's IP address.
**TLS/SSL:** ntfy supports HTTPS/TLS by setting the `listen-https` config option. However, if you are behind a proxy, it is
recommended that TLS/SSL termination is done by the proxy itself.
## Rate limiting
Rate limiting: Allowed GET/PUT/POST requests per second, per visitor:
- visitor-request-limit-burst is the initial bucket of requests each visitor has
- visitor-request-limit-replenish is the rate at which the bucket is refilled
!!! info
Be aware that if you are running ntfy behind a proxy, you must set the `behind-proxy` flag.
Otherwise all visitors are rate limited as if they are one.
By default, ntfy runs without authentication, so it is vitally important that we protect the server from abuse or overload.
There are various limits and rate limits in place that you can use to configure the server. Let's do the easy ones first:
* `global-topic-limit` defines the total number of topics before the server rejects new topics. It defaults to 5000.
* `visitor-subscription-limit` is the number of subscriptions (open connections) per visitor. This value defaults to 30.
A **visitor** is identified by its IP address (or the `X-Forwarded-For` header if `behind-proxy` is set). All config
options that start with the word `visitor` apply only on a per-visitor basis.
In addition to the limits above, there is a requests/second limit per visitor for all sensitive GET/PUT/POST requests.
This limit uses a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) (using Go's [rate package](https://pkg.go.dev/golang.org/x/time/rate)):
Each visitor has a bucket of 60 requests they can fire against the server (defined by `visitor-request-limit-burst`).
After the 60, new requests will encounter a `429 Too Many Requests` response. The visitor request bucket is refilled at a rate of one
request every 10s (defined by `visitor-request-limit-replenish`)
* `visitor-request-limit-burst` is the initial bucket of requests each visitor has. This defaults to 60.
* `visitor-request-limit-replenish` is the rate at which the bucket is refilled (one request per x). Defaults to 10s.
During normal usage, you shouldn't encounter this limit at all, and even if you burst a few requests shortly (e.g. when you
reconnect after a connection drop), it shouldn't have any effect.
## Command line options
```

1831
docs/emojis.md Normal file
View file

File diff suppressed because it is too large Load diff

157
docs/publish/index.md
View file

@ -115,6 +115,60 @@ a [title](#message-title), and [tag messages](#tags-emojis) 🥳 🎉. Here's an
<figcaption>Urgent notification with tags and title</figcaption>
</figure>
## Message title
The notification title is typically set to the topic short URL (e.g. `ntfy.sh/mytopic`). To override the title,
you can set the `X-Title` header (or any of its aliases: `Title`, `ti`, or `t`).
=== "Command line (curl)"
```
curl -H "X-Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
curl -H "Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
curl -H "t: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
```
=== "HTTP"
``` http
POST /controversial HTTP/1.1
Host: ntfy.sh
Title: Dogs are better than cats
Oh my ...
```
=== "JavaScript"
``` javascript
fetch('https://ntfy.sh/controversial', {
method: 'POST',
body: 'Oh my ...',
headers: { 'Title': 'Dogs are better than cats' }
})
```
=== "Go"
``` go
req, _ := http.NewRequest("POST", "https://ntfy.sh/controversial", strings.NewReader("Oh my ..."))
req.Header.Set("Title", "Dogs are better than cats")
http.DefaultClient.Do(req)
```
=== "PHP"
``` php
file_get_contents('https://ntfy.sh/controversial', false, stream_context_create([
'http' => [
'method' => 'POST',
'header' =>
"Content-Type: text/plain\r\n" .
"Title: Dogs are better than cats",
'content' => 'Oh my ...'
]
]));
```
<figure markdown>
![notification with title](../static/img/notification-with-title.png){ width=500 }
<figcaption>Detail view of notification with title</figcaption>
</figure>
## Message priority
All messages have a priority, which defines how urgently your phone notifies you. You can set custom
notification sounds and vibration patterns on your phone to map to these priorities (see [Android config](../subscribe/phone.md)).
@ -182,26 +236,99 @@ You can set the priority with the header `X-Priority` (or any of its aliases: `P
</figure>
## Tags & emojis 🥳 🎉
You can tag messages with emojis (or other relevant strings). If a tag matches a <a href="https://raw.githubusercontent.com/github/gemoji/master/db/emoji.json">known emoji short code</a>,
it will be converted to an emoji. If it doesn't match, it will be listed below the notification. This is useful
for things like warnings and such (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. which script the
message came from, ...).
You can tag messages with emojis and other relevant strings:
You can set tags with the `X-Tags` header (or any of its aliases: `Tags`, or `ta`).
Use <a href="https://raw.githubusercontent.com/github/gemoji/master/db/emoji.json">this reference</a>
to figure out what tags can be converted to emojis. In the example below, the tag "warning" matches the emoji ⚠️,
the tag "ssh-login" doesn't match and will be displayed below the message.
* **Emojis**: If a tag matches an [emoji short code](../emojis.md), it'll be converted to an emoji and prepended
to title or message.
* **Other tags:** If a tag doesn't match, it will be listed below the notification.
This feature is useful for things like warnings (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. script
names, hostnames, etc.). Use [the emoji short code list](../emojis.md) to figure out what tags can be converted to emojis.
Here's an **excerpt of emojis** I've found very useful in alert messages:
<table class="remove-md-box"><tr>
<td>
<table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
<tr><td><code>+1</code></td><td>👍️</td></tr>
<tr><td><code>partying_face</code></td><td>🥳</td></tr>
<tr><td><code>tada</code></td><td>🎉</td></tr>
<tr><td><code>heavy_check_mark</code></td><td>✔️</td></tr>
<tr><td><code>loudspeaker</code></td><td>📢</td></tr>
<tr><td>...</td><td>...</td></tr>
</tbody></table>
</td>
<td>
<table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
<tr><td><code>-1</code></td><td>👎️</td></tr>
<tr><td><code>warning</code></td><td>⚠️</td></tr>
<tr><td><code>rotating_light</code></td><td>️🚨</td></tr>
<tr><td><code>triangular_flag_on_post</code></td><td>🚩</td></tr>
<tr><td><code>skull</code></td><td>💀</td></tr>
<tr><td>...</td><td>...</td></tr>
</tbody></table>
</td>
<td>
<table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
<tr><td><code>facepalm</code></td><td>🤦</td></tr>
<tr><td><code>no_entry</code></td><td>⛔</td></tr>
<tr><td><code>no_entry_sign</code></td><td>🚫</td></tr>
<tr><td><code>cd</code></td><td>💿</td></tr>
<tr><td><code>computer</code></td><td>💻</td></tr>
<tr><td>...</td><td>...</td></tr>
</tbody></table>
</td>
</tr></table>
You can set tags with the `X-Tags` header (or any of its aliases: `Tags`, or `ta`). Specify multiple tags by separating
them with a comma, e.g. `tag1,tag2,tag3`.
=== "Command line (curl)"
```
$ curl -H "Tags: warning,ssh-login" -d "Unauthorized SSH access" ntfy.sh/mytopic
{"id":"ZEIwjfHlSS",...,"tags":["warning","ssh-login"],"message":"Unauthorized SSH access"}
curl -H "X-Tags: warning,mailsrv13,daily-backup" -d "Backup of mailsrv13 failed" ntfy.sh/backups
curl -H "Tags: horse,unicorn" -d "Unicorns are just horses with unique horns" ntfy.sh/backups
curl -H ta:dog -d "Dogs are awesome" ntfy.sh/backups
```
## Message title
The notification title is typically set to the topic short URL (e.g. `ntfy.sh/mytopic`.
To override it, you can set the `X-Title` header (or any of its aliases: `Title`, `ti`, or `t`).
=== "HTTP"
``` http
POST /backups HTTP/1.1
Host: ntfy.sh
Tags: warning,mailsrv13,daily-backup
```
curl -H "Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/mytopic<
Backup of mailsrv13 failed
```
=== "JavaScript"
``` javascript
fetch('https://ntfy.sh/backups', {
method: 'POST',
body: 'Backup of mailsrv13 failed',
headers: { 'Tags': 'warning,mailsrv13,daily-backup' }
})
```
=== "Go"
``` go
req, _ := http.NewRequest("POST", "https://ntfy.sh/backups", strings.NewReader("Backup of mailsrv13 failed"))
req.Header.Set("Tags", "warning,mailsrv13,daily-backup")
http.DefaultClient.Do(req)
```
=== "PHP"
``` php
file_get_contents('https://ntfy.sh/backups', false, stream_context_create([
'http' => [
'method' => 'POST',
'header' =>
"Content-Type: text/plain\r\n" .
"Tags: warning,mailsrv13,daily-backup",
'content' => 'Backup of mailsrv13 failed'
]
]));
```
<figure markdown>
![priority notification](../static/img/notification-with-tags.png){ width=500 }
<figcaption>Detail view of notifications with tags</figcaption>
</figure>

10
docs/static/css/extra.css vendored
View file

@ -2,3 +2,13 @@ figure img {
border-radius: 7px;
filter: drop-shadow(3px 3px 5px #ccc);
}
.remove-md-box {
background: none;
border: none;
margin: 0 auto;
}
.remove-md-box td {
padding: 0 10px
}

BIN
docs/static/img/notification-with-tags.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 155 KiB

BIN
docs/static/img/notification-with-title.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 161 KiB

3
mkdocs.yml
View file

@ -79,7 +79,8 @@ nav:
- "Polling": subscribe/poll.md
- "Other things":
- "Examples": examples.md
- "FAQs": faq.md
- "Emojis 🥳 🎉": emojis.md
- "Development": develop.md
- "FAQs": faq.md

27
scripts/emoji-convert.sh
View file

@ -7,10 +7,11 @@ SCRIPTDIR="$(cd "$(dirname "$0")" && pwd)"
ROOTDIR="$(cd "$(dirname "$0")/.." && pwd)"
if [ -z "$1" ]; then
echo "Syntax: $0 FILE.(js|json)"
echo "Syntax: $0 FILE.(js|json|md)"
echo "Example:"
echo " $0 emoji-converted.json"
echo " $0 $ROOTDIR/server/static/js/emoji.js"
echo " $0 $ROOTDIR/docs/emojis.md"
exit 1
fi
@ -19,6 +20,30 @@ if [[ "$1" == *.js ]]; then
// Original data source: https://github.com/github/gemoji/blob/master/db/emoji.json
const rawEmojis = " > "$1"
cat "$SCRIPTDIR/emoji.json" | jq -rc 'map({emoji: .emoji,aliases: .aliases})' >> "$1"
elif [[ "$1" == *.md ]]; then
echo "# Emoji reference
<!-- This file was generated by scripts/emoji-convert.sh -->
You can [tag messages](../publish/#tags-emojis) with emojis 🥳 🎉 and other relevant strings. Matching tags are automatically
converted to emojis. This is a reference of all supported emojis. To learn more about the feature, please refer to the
[tagging and emojis page](../publish/#tags-emojis).
<table class="remove-md-box"><tr>
" > "$1"
count="$(cat "$SCRIPTDIR/emoji.json" | jq -r '.[] | .emoji' | wc -l)"
percolumn=$(($count / 3)) # This will misbehave if the count is not divisible by 3
for col in 0 1 2; do
from="$(($col * $percolumn + 1))"
to="$(($col * $percolumn + 1 + $percolumn))"
echo "<td><table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>" >> "$1"
cat "$SCRIPTDIR/emoji.json" \
| jq -r '.[] | "<tr><td><code>" + .aliases[0] + "</code></td><td>" + .emoji + "</td></tr>"' \
| sed -n "${from},${to}p" >> "$1"
echo "</tbody></table></td>" >> "$1"
done
echo "</tr></table>" >> "$1"
else
cat "$SCRIPTDIR/emoji.json" | jq -rc 'map({emoji: .emoji,aliases: .aliases})' > "$1"
fi