Installation

Prerequisites

To use Cascade a v0.2.0 version of dnst is required. The Cascade DEB and RPM packages automatically ensure that the appropriate version of dnst is installed.

To use automatic keyrolls (which are on by default) the Cascade host machine will need to have IPv6 connectivity if any of its nameservers or parent nameservers have AAAA records.

Binary Packages

Getting started with Cascade is really easy by installing a binary package for either Debian and Ubuntu or for Red Hat Enterprise Linux (RHEL) and compatible systems such as Rocky Linux. Alternatively, you can run with Docker.

You can also build Cascade from the source code using Cargo, Rust’s build system and package manager. Cargo lets you run Cascade on almost any operating system and CPU architecture. Refer to the Building From Source section to get started.

To install a Cascade package, you need the 64-bit version of one of these Debian versions:

  • Debian Trixie 13

  • Debian Bookworm 12

  • Debian Bullseye 11

Packages are available for the amd64/x86_64 architecture only.

First update the apt package index:

sudo apt update

Then install packages to allow apt to use a repository over HTTPS:

sudo apt install \
  ca-certificates \
  curl \
  gnupg \
  lsb-release

Add the GPG key from NLnet Labs:

curl -fsSL https://packages.nlnetlabs.nl/aptkey.asc | sudo gpg --dearmor -o /etc/apt/keyrings/nlnetlabs-archive-keyring.gpg

Now, use the following command to set up the proposed repository:

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/nlnetlabs-archive-keyring.gpg] https://packages.nlnetlabs.nl/linux/debian \
$(lsb_release -cs)-proposed main" | sudo tee /etc/apt/sources.list.d/nlnetlabs-proposed.list > /dev/null

Update the apt package index once more:

sudo apt update

You can now install Cascade with:

sudo apt install cascade

After installing, refer to the Quick Start to get started.

Once you’re ready, start Cascade with:

sudo systemctl start cascaded

You can also configure Cascade to start at boot:

sudo systemctl enable cascaded

You can check the status of Cascade with:

sudo systemctl status cascaded

You can view the logs with:

sudo journalctl --unit=cascaded

Updating

Danger

In its current beta version form Cascade will likely report errors if a newer version is started using existing state and policy files created by an older version.

Before updating, delete all state and policy files. Note that this will delete signing keys stored on disk. Signing keys stored in HSMs will not be affected but Cascade will no longer know about them. If HSM signing keys that are left behind are no longer wanted, you will need to remove them manually.

First stop Cascade, using systemd if in use on your system:

sudo systemctl stop cascaded.socket
sudo systemctl stop cascaded.service

Or by killing the Cascade daemon process otherwise:

pkill cascaded

Next, delete the state and policy files:

(if you modified any of the filesystem locations specified in your Cascade config file, use the updated paths instead of the default paths shown in these instructions)

sudo rm -R /var/lib/cascade
sudo rm -R /etc/cascade/policies

To update an existing Cascade installation, first update the repository using:

sudo apt update

You can use this command to get an overview of the available versions:

sudo apt policy cascade

You can upgrade an existing Cascade installation to the latest version using:

sudo apt --only-upgrade install cascade