mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-12-26 01:31:16 +08:00
DOCS: Shoutrrr added list of notification services (#3242)
Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>
This commit is contained in:
Jeffrey Cafferata
GitHub
parent
1ffd38face
commit
71539d40cf
1 changed files with 51 additions and 35 deletions
|
|
@ -1,27 +1,22 @@
|
|||
# Notifications
|
||||
|
||||
DNSControl has build in support for notifications when changes are made. This allows you to post messages in team chat, or send emails when dns changes are made.
|
||||
|
||||
Notifications are written in the [notifications package](https://github.com/StackExchange/dnscontrol/tree/main/pkg/notifications), and is a really simple interface to implement if you want to add
|
||||
new types or destinations.
|
||||
DNSControl's "notifications" feature will log `push` changes to other services in real time. Typically this is used to automatically announce DNS changes in a team chatroom. The functionality is implemented using the open source [Shoutrrr](https://github.com/containrrr/shoutrrr) library, which knows how to communicate to many different systems. Some additional services are provided natively, see the [notifications package](https://github.com/StackExchange/dnscontrol/tree/main/pkg/notifications).
|
||||
|
||||
## Configuration
|
||||
|
||||
Notifications are set up in your credentials JSON file. They will use the `notifications` key to look for keys or configuration needed for various notification types.
|
||||
Notifications are configured in the `creds.json` file, since they often contain API keys or other secrets. The `notifications` key lists the notification service and options.
|
||||
|
||||
{% code title="creds.json" %}
|
||||
```json
|
||||
"r53": {
|
||||
...
|
||||
},
|
||||
"gcloud": {
|
||||
...
|
||||
} ,
|
||||
{
|
||||
"r53": {},
|
||||
"gcloud": {},
|
||||
"notifications": {
|
||||
"slack_url": "https://api.slack.com/apps/0XXX0X0XX0/incoming-webhooks",
|
||||
"teams_url": "https://outlook.office.com/webhook/00000000-0000-0000-0000-000000000000@00000000-0000-0000-0000-000000000000/IncomingWebhook/00000000000000000000000000000000/00000000-0000-0000-0000-000000000000",
|
||||
"shoutrrr_url": "discover://token@id"
|
||||
"slack_url": "https://api.slack.com/apps/0XXX0X0XX0/incoming-webhooks",
|
||||
"teams_url": "https://outlook.office.com/webhook/00000000-0000-0000-0000-000000000000@00000000-0000-0000-0000-000000000000/IncomingWebhook/00000000000000000000000000000000/00000000-0000-0000-0000-000000000000",
|
||||
"shoutrrr_url": "discover://token@id"
|
||||
}
|
||||
}
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
|
|
@ -67,25 +62,62 @@ dnscontrol push --notify
|
|||
Successfully ran correction for **example.com[my_provider]** - CREATE foo.example.com A 1.2.3.4 ttl=86400
|
||||
```
|
||||
|
||||
## Notification types
|
||||
## Notification services
|
||||
|
||||
### Shoutrrr
|
||||
|
||||
DNSControl supports various notification methods via Shoutrrr, including email (SMTP), Discord, Pushover, and many others. For detailed setup instructions, click on the desired service:
|
||||
|
||||
* [Bark](https://containrrr.dev/shoutrrr/latest/services/bark/)
|
||||
* [Discord](https://containrrr.dev/shoutrrr/latest/services/discord/)
|
||||
* [Email](https://containrrr.dev/shoutrrr/latest/services/email/)
|
||||
* [Google Chat](https://containrrr.dev/shoutrrr/latest/services/googlechat/)
|
||||
* [Gotify](https://containrrr.dev/shoutrrr/latest/services/gotify/)
|
||||
* [IFTTT](https://containrrr.dev/shoutrrr/latest/services/ifttt/)
|
||||
* [Join](https://containrrr.dev/shoutrrr/latest/services/join/)
|
||||
* [Matrix](https://containrrr.dev/shoutrrr/latest/services/matrix/)
|
||||
* [Mattermost](https://containrrr.dev/shoutrrr/latest/services/mattermost/)
|
||||
* [Ntfy](https://containrrr.dev/shoutrrr/latest/services/ntfy/)
|
||||
* [OpsGenie](https://containrrr.dev/shoutrrr/latest/services/opsgenie/)
|
||||
* [Pushbullet](https://containrrr.dev/shoutrrr/latest/services/pushbullet/)
|
||||
* [Pushover](https://containrrr.dev/shoutrrr/latest/services/pushover/)
|
||||
* [Rocketchat](https://containrrr.dev/shoutrrr/latest/services/rocketchat/)
|
||||
* [Slack](https://containrrr.dev/shoutrrr/latest/services/slack/)
|
||||
* [Teams](https://containrrr.dev/shoutrrr/latest/services/teams/)
|
||||
* [Telegram](https://containrrr.dev/shoutrrr/latest/services/telegram/)
|
||||
* [Zulip Chat](https://containrrr.dev/shoutrrr/latest/services/zulip/)
|
||||
|
||||
The above list is accurate as of 2024-Dec. The compete list and all configuration details are in the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/latest/services/overview/).
|
||||
|
||||
Configure `shoutrrr_url` with the Shoutrrr URL to be notified.
|
||||
|
||||
{% code title="creds.json" %}
|
||||
```json
|
||||
{
|
||||
"notifications": {
|
||||
"shoutrrr_url": "discover://token@id"
|
||||
}
|
||||
}
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
### Slack/Mattermost
|
||||
|
||||
If you want to use the Slack integration, you need to create a webhook in Slack.
|
||||
Please see the [Slack documentation](https://api.slack.com/messaging/webhooks) or the [Mattermost documentation](https://developers.mattermost.com/integrate/webhooks/incoming/)
|
||||
To use the Slack integration, you need to create a webhook in Slack.
|
||||
Please see the [Slack documentation](https://api.slack.com/messaging/webhooks) or the [Mattermost documentation](https://docs.mattermost.com/developer/webhooks-incoming.html)
|
||||
|
||||
Configure `slack_url` to this webhook. Mattermost works as well, as they share the same api,
|
||||
|
||||
### Microsoft Teams
|
||||
|
||||
If you want to use the Teams integration, you need to create a webhook in Teams.
|
||||
To use the Teams integration, you need to create a webhook in Teams.
|
||||
Please see the [Teams documentation](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook#add-an-incoming-webhook-to-a-teams-channel)
|
||||
|
||||
Configure `teams_url` to this webhook.
|
||||
|
||||
### Telegram
|
||||
|
||||
If you want to use the [Telegram](https://telegram.org/) integration, you need to create a Telegram bot and obtain a Bot Token, as well as a Chat ID. Get a Bot Token by contacting [@BotFather](https://telegram.me/botfather), and a Chat ID by contacting [@myidbot](https://telegram.me/myidbot).
|
||||
To use the [Telegram](https://telegram.org/) integration, you need to create a Telegram bot and obtain a Bot Token, as well as a Chat ID. Get a Bot Token by contacting [@BotFather](https://telegram.me/botfather), and a Chat ID by contacting [@myidbot](https://telegram.me/myidbot).
|
||||
|
||||
Configure `telegram_bot_token` and `telegram_chat_id` to these values.
|
||||
|
||||
|
|
@ -94,19 +126,3 @@ Configure `telegram_bot_token` and `telegram_chat_id` to these values.
|
|||
This is Stack Overflow's built in chat system. This is probably not useful for most people.
|
||||
|
||||
Configure `bonfire_url` to be the full url including room and api key.
|
||||
|
||||
### Shoutrrr (email, Discord, Pushover, etc.)
|
||||
|
||||
DNSControl can use many other notification methods via Shoutrrr, such as email (SMTP), Discord, Pushover and others. See the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/latest/services/overview/) for a list of supported methods and configuration instructions.
|
||||
|
||||
Configure `shoutrrr_url` with the Shoutrrr URL to be notified.
|
||||
|
||||
## Future work
|
||||
|
||||
Yes, this seems pretty limited right now in what it can do. We didn't want to add a bunch of notification types if nobody was going to use them. The good news is, it should
|
||||
be really simple to add more. We gladly welcome any PRs with new notification destinations. Some easy possibilities:
|
||||
|
||||
- Email
|
||||
- Generic Webhooks
|
||||
|
||||
Please update this documentation if you add anything.
|
||||
|
|
|
|||
Loading…
Reference in a new issue