Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS: Shoutrrr added list of notification services #3242

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
78 changes: 47 additions & 31 deletions documentation/notifications.md
Original file line number Diff line number Diff line change
@@ -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 includes built-in support for notifications, enabling you to post messages in team chats or send emails whenever DNS changes occur, with the functionality implemented in the [notifications package](https://github.com/StackExchange/dnscontrol/tree/main/pkg/notifications).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
DNSControl includes built-in support for notifications, enabling you to post messages in team chats or send emails whenever DNS changes occur, with the functionality implemented in the [notifications package](https://github.com/StackExchange/dnscontrol/tree/main/pkg/notifications).
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 set up in your credentials JSON file. They will use the `notifications` key to look for keys or configuration needed for various notification services.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 services.
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 %}

Expand Down Expand Up @@ -67,7 +62,44 @@ 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/)

For a full overview of supported methods and configuration details, refer to the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/latest/services/overview/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For a full overview of supported methods and configuration details, refer to the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/latest/services/overview/).
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

Expand All @@ -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