Quick Start

After installing Cascade you can immediately start using it, unless you need to adjust the addresses it listens on or need to modify the settings relating to daemonization.

Important

Fully automatic key rolls are enabled by default. For this to work, Cascade requires access to all nameservers of the zone and the parent zone. If this is not available, make sure to disable automatic key rolls.

Configuring Cascade

By default, Cascade only listens on the localhost address. If you want Cascade to listen on other addresses too, you need to configure them.

The /etc/cascade/config.toml file controls listen addresses, which filesystem paths Cascade uses, daemonization settings (running in the background, running as a different user), and log settings.

If using systemd to run Cascade some of these settings should be ignored and systemd features used instead.

On systems using systemd the cascaded.socket unit is used to bind to listen addresses on behalf of Cascade. By default, the provided listen address is localhost:53. If you wish to change the addresses bound, you will need to override the cascaded.socket unit. One way to do this is to use the systemctl edit command like so:

sudo systemctl edit cascaded.socket

and insert the following config:

[Socket]
# Uncomment the next line if you wish to disable listening on localhost.
#ListenStream=
ListenDatagram=<your-ip>:53
ListenStream=<your-ip>:53

Then notify systemd of the changes and (re)start Cascade:

sudo systemctl daemon-reload
sudo systemctl restart cascaded

Interacting with Cascade

Cascade consists of two parts: the cascaded daemon which runs continuously, receiving, signing and publishing zone records, and the cascade CLI (command-line interface) tool which can be used to inspect and control Cascade.

Using the CLI we can see that on first start Cascade has no policies and no zones:

$ cascade status
Signing queue:
  The signing queue is currently empty.

$ cascade policy list

$ cascade zone list

Note

The program:cascade CLI connects via HTTPS to the cascaded daemon. By default it connects to 127.0.0.1:4539. You can override this by passing --server <IP>:<PORT> to connect to a Cascade daemon running on another machine.

The cascade CLI is the primary means of interacting with the cascaded daemon.

For monitoring purposes Cascade supports Prometheus which when combined with other tools such as Grafana and Alertmanager enable visual insight into the behaviour of Cascade and early warning of unexpected situations.

Additionally, while normally not needed, the CLI and the daemon produce logs which can be inspected and if needed can be made more verbose. The CLI logs to the terminal while the daemon typically logs to syslog or to a file. Both the CLI and the daemon take a --log-level argument which can be used to adjust the verbosity of the produced log output. It is also possible to use the CLI to adjust the verbosity of an already running daemon, for example:

$ cascade debug change-logging --level debug
Changed log-level to: debug

Defining Policy

After configuring Cascade, you can begin adding zones. Cascade supports zones sourced from a local file or fetched from another nameserver using XFR zone transfers.

Note

The current version of Cascade does not yet support TSIG authenticated XFR nor can it pass through a signed zone intact. Any DNSSEC records will be stripped from the zone before signing. We expect to add support for these features soon.

Zones take a lot of their settings from policy. Policies allow easy re-use of settings across multiple zones and control things like whether or not zones should be reviewed and how, what DNSSEC settings should be used to sign the zone, and more.

Adding a policy is done by creating a file. To make it easy to get started we provide a default policy template so we’ll use that to create a policy for our zone to use. The name of the policy is taken from the file name. The directory to save the policy file to is determined by the policy-dir setting as configured in /etc/cascade/config.toml.

In the example below, the sudo tee command is needed because the default policy directory is not writable by the current user.

Tip

Cascade needs to running before you proceed further. See Configuring Cascade above on how to configure and start Cascade.

cascade template policy | sudo tee /etc/cascade/policies/default.toml
cascade policy reload

Signing Your First Zone

Adding a zone will trigger Cascade to load, sign and publish it. If you have configured Review Hooks, they will be executed and may intentionally prevent your zone reaching publication.

To add a zone use:

cascade zone add --source <file-path|ip-address> --policy default <zone-name>

Cascade will now generate signing keys for the zone and attempt to load and sign it.

Checking the Result

You can view the status of a zone with:

cascade zone status <zone-name>

For example:

zone:   example.com
policy: default
source: /path/to/zonefile/example.txt

review
  loaded: off
  signed: off

last published
  loaded serial: 2001062501
  signed serial: 2026050600
  timestamp:     <TODO>
  size:          <TODO> records (<TODO>B)

status: idle

Published zone available at 127.0.0.1:4542

From the above you can see that the signed zone can be retrieved from 127.0.0.1:4542 using a DNS client, e.g.:

dig @127.0.0.1 -p 4542 AXFR example.com

If you have the BIND dnssec-verify tool installed, you can check that the zone is correctly DNSSEC signed:

$ dig @127.0.0.1 -p 4542 example.com AXFR | dnssec-verify -o example.com /dev/stdin
Loading zone 'example.com' from file '/dev/stdin'

Verifying the zone using the following algorithms:
- ECDSAP256SHA256
Zone fully signed:
Algorithm: ECDSAP256SHA256: KSKs: 1 active, 0 stand-by, 0 revoked
                            ZSKs: 1 active, 0 stand-by, 0 revoked

Next Steps