StackExchange/dnscontrol
1
1
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2025-12-19 07:08:32 +08:00
Code Issues Projects Releases Packages Wiki Activity
dnscontrol/documentation/advanced-features/notifications.md
Michael Kaye efe713cc0e
FEATURE: Set --notify via creds.json so that preview or push can always notify (#3910) 
Either setting these new options OR using --notify on the commandline
will send notification for any specific execution.

Fixes #3906

In a second commit (feel free to remove) I added some logging to
indicate that notifications were enabled or not (useful when testing
each case).

I've manually tested combinations of the various options, for both
preview and push:
 * --notify set or unset on commandline
 * notify_on_* set to "true" or "ASDAS" or "false" or not mentioned
 
All seem to provide the correct logging line - invalid boolean values
are considered false (not an error).
 
I've made an attempt at documentation of the options, not sure if you
want it elsewhere as well.
  
<!--
## Before submiting a pull request

Please make sure you've run the following commands from the root
directory.

    bin/generate-all.sh

(this runs commands like "go generate", fixes formatting, and so on)

## Release changelog section

Help keep the release changelog clear by pre-naming the proper section
in the GitHub pull request title.

Some examples:
* CICD: Add required GHA permissions for goreleaser
* DOCS: Fixed providers with "contributor support" table
* ROUTE53: Allow R53_ALIAS records to enable target health evaluation

More examples/context can be found in the file .goreleaser.yml under the
'build' > 'changelog' key.
!-->
2025-12-10 12:50:31 -05:00

5.7 KiB
Raw Blame History

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 library, which knows how to communicate to many different systems. Some additional services are provided natively, see the notifications package.

Configuration

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" %}

{
  "r53": {},
  "gcloud": {},
  "notifications": {
    "notify_on_push": false,
    "notify_on_preview": false,
    "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 %}

Usage

If you want to send a notification for a specific execution, add the --notify flag to the dnscontrol preview or dnscontrol push commands.

To always send notifications, enable one or more of the notify_on_push or notify_on_preview options.

Below is an example where we add the A record foo and display the notification output.

{% code title="dnsconfig.js" %}

D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
+ A("foo", "1.2.3.4"),
);

{% endcode %}

Preview example

In case of dnscontrol preview:

dnscontrol preview --notify

The notification output

**Preview: example.com[my_provider] -** CREATE foo.example.com A (1.2.3.4 ttl=86400)

Push example

In case of dnscontrol push:

dnscontrol push --notify

The notification output

Successfully ran correction for **example.com[my_provider]** - CREATE foo.example.com A 1.2.3.4 ttl=86400

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:

Chat and Messaging Platforms

Push Notification Services

Incident and Alert Management

Email Services

Specialized Services

Configure shoutrrr_url with the Shoutrrr URL to be notified.

{% code title="creds.json" %}

{
  "notifications": {
    "shoutrrr_url": "discover://token@id"
  }
}

{% endcode %}

Slack/Mattermost

To use the Slack integration, you need to create a webhook in Slack. Please see the Slack documentation or the Mattermost documentation

Configure slack_url to this webhook. Mattermost works as well, as they share the same api,

Microsoft Teams

To use the Teams integration, you need to create a webhook in Teams. Please see the Teams documentation

Configure teams_url to this webhook.

Telegram

To use the Telegram 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, and a Chat ID by contacting @myidbot.

Configure telegram_bot_token and telegram_chat_id to these values.

Bonfire

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.