From 12eb086cb28ef20157de25440e027a98ff7a0abd Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Fri, 17 Oct 2025 12:09:02 +0200 Subject: [PATCH 1/7] Update man pages. --- doc/manual/build/man/cascade-config.1 | 4 +- doc/manual/build/man/cascade-hsm.1 | 4 +- doc/manual/build/man/cascade-keyset.1 | 4 +- doc/manual/build/man/cascade-policy.1 | 4 +- doc/manual/build/man/cascade-template.1 | 4 +- doc/manual/build/man/cascade-zone.1 | 50 ++++++++++++++++++- doc/manual/build/man/cascade.1 | 7 ++- doc/manual/build/man/cascaded-config.toml.5 | 55 ++++++++++++++++----- doc/manual/build/man/cascaded-policy.toml.5 | 43 ++++++++++------ doc/manual/build/man/cascaded.1 | 11 +++-- 10 files changed, 142 insertions(+), 44 deletions(-) diff --git a/doc/manual/build/man/cascade-config.1 b/doc/manual/build/man/cascade-config.1 index 48406a97..c0dd3a6e 100644 --- a/doc/manual/build/man/cascade-config.1 +++ b/doc/manual/build/man/cascade-config.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADE-CONFIG" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADE-CONFIG" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascade-config \- Manage configuration .SH SYNOPSIS @@ -53,7 +53,7 @@ Note: Only some setting changes are honoured by Cascade at this point. .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascade-hsm.1 b/doc/manual/build/man/cascade-hsm.1 index a28dff31..385f783b 100644 --- a/doc/manual/build/man/cascade-hsm.1 +++ b/doc/manual/build/man/cascade-hsm.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADE-HSM" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADE-HSM" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascade-hsm \- Manage HSMs .SH SYNOPSIS @@ -222,7 +222,7 @@ longer than this will be truncated to fit. .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascade-keyset.1 b/doc/manual/build/man/cascade-keyset.1 index 10b43f93..6067d809 100644 --- a/doc/manual/build/man/cascade-keyset.1 +++ b/doc/manual/build/man/cascade-keyset.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADE-KEYSET" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADE-KEYSET" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascade-keyset \- Execute manual key roll or key removal commands .SH SYNOPSIS @@ -126,7 +126,7 @@ Continue when removing the underlying keys fails. .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascade-policy.1 b/doc/manual/build/man/cascade-policy.1 index 713c719a..f660568f 100644 --- a/doc/manual/build/man/cascade-policy.1 +++ b/doc/manual/build/man/cascade-policy.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADE-POLICY" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADE-POLICY" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascade-policy \- Manage policies .SH SYNOPSIS @@ -67,7 +67,7 @@ Reload all the policies from the files. .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascade-template.1 b/doc/manual/build/man/cascade-template.1 index 6e7b8027..6d06803e 100644 --- a/doc/manual/build/man/cascade-template.1 +++ b/doc/manual/build/man/cascade-template.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADE-TEMPLATE" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADE-TEMPLATE" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascade-template \- Print example config or policy files .SH SYNOPSIS @@ -56,7 +56,7 @@ Generate a policy template. .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascade-zone.1 b/doc/manual/build/man/cascade-zone.1 index acfb3d1f..7cd60aa0 100644 --- a/doc/manual/build/man/cascade-zone.1 +++ b/doc/manual/build/man/cascade-zone.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADE-ZONE" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADE-ZONE" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascade-zone \- Manage zones .SH SYNOPSIS @@ -42,6 +42,10 @@ cascade-zone \- Manage zones .sp \fBcascade zone\fP \fB[OPTIONS]\fP \fI\%reload\fP \fB\fP .sp +\fBcascade zone\fP \fB[OPTIONS]\fP \fI\%approve\fP \fB<\-\-unsigned|\-\-signed>\fP \fB\fP \fB\fP +.sp +\fBcascade zone\fP \fB[OPTIONS]\fP \fI\%reject\fP \fB<\-\-unsigned|\-\-signed>\fP \fB\fP \fB\fP +.sp \fBcascade zone\fP \fB[OPTIONS]\fP \fI\%status\fP \fB[\-\-detailed]\fP \fB\fP .sp \fBcascade zone\fP \fB[OPTIONS]\fP \fI\%history\fP \fB\fP @@ -77,6 +81,16 @@ Reload a zone. .UNINDENT .INDENT 0.0 .TP +.B approve +Approve a zone being reviewed. +.UNINDENT +.INDENT 0.0 +.TP +.B reject +Reject a zone being reviewed. +.UNINDENT +.INDENT 0.0 +.TP .B status Get the status of a single zone. .UNINDENT @@ -152,6 +166,38 @@ Import a CSK from an HSM. .B \-h, \-\-help Print the help text (short summary with \fB\-h\fP, long help with \fB\-\-help\fP). .UNINDENT +.SH OPTIONS FOR ZONE APPROVE +.INDENT 0.0 +.TP +.B <\-\-unsigned|\-\-signed> +Whether the zone to approve is at the unsigned or signed review stage. +.UNINDENT +.INDENT 0.0 +.TP +.B +The name of the zone to approve. +.UNINDENT +.INDENT 0.0 +.TP +.B +The serial number of the zone to approve. +.UNINDENT +.SH OPTIONS FOR ZONE REJECT +.INDENT 0.0 +.TP +.B <\-\-unsigned|\-\-signed> +Whether the zone to reject is at the unsigned or signed review stage. +.UNINDENT +.INDENT 0.0 +.TP +.B +The name of the zone to reject. +.UNINDENT +.INDENT 0.0 +.TP +.B +The serial number of the zone to reject. +.UNINDENT .SH OPTIONS FOR ZONE STATUS .INDENT 0.0 .TP @@ -162,7 +208,7 @@ identifiers in use, as well as the new DNSKEY records during key rolls. .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascade.1 b/doc/manual/build/man/cascade.1 index 72da750e..2ab15411 100644 --- a/doc/manual/build/man/cascade.1 +++ b/doc/manual/build/man/cascade.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADE" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADE" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascade \- Cascade CLI .SH SYNOPSIS @@ -64,6 +64,9 @@ Print version. \fBcascade\-config\fP(1) Manage Cascade\(aqs configuration. .TP +\fBcascade\-health\fP(1) +Check the health of Cascade. +.TP \fBcascade\-zone\fP(1) Manage zones. .TP @@ -82,7 +85,7 @@ Print example config or policy files. .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascaded\fP(1) diff --git a/doc/manual/build/man/cascaded-config.toml.5 b/doc/manual/build/man/cascaded-config.toml.5 index 20eee872..749ff9c8 100644 --- a/doc/manual/build/man/cascaded-config.toml.5 +++ b/doc/manual/build/man/cascaded-config.toml.5 @@ -27,19 +27,27 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADED-CONFIG.TOML" "5" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADED-CONFIG.TOML" "5" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascaded-config.toml \- Cascade configuration file .sp Cascade uses the TOML format for its configuration file. A template can be generated using \fBcascade template config\fP\&. The provided values to the options below are the default values and are serving as a hint to the option\(aqs format. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +All changes to the configuration file require running \fBcascade config +reload\fP for them to take effect. Currently, most options additionally +require a restart of the server. +.UNINDENT +.UNINDENT .SH EXAMPLE .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX version = \(dqv1\(dq policy\-dir = \(dq/etc/cascade/policies\(dq zone\-state\-dir = \(dq/var/lib/cascade/zone\-state\(dq @@ -51,7 +59,7 @@ dnst\-binary\-path = \(dq/usr/libexec/cascade/cascade\-dnst\(dq [daemon] log\-level = \(dqinfo\(dq -log\-target = { type = \(dqfile\(dq, path = \(dq/dev/stdout\(dq } +log\-target = { type = \(dqstdout\(dq } daemonize = false [remote\-control] @@ -71,8 +79,7 @@ servers = [\(dq127.0.0.1:4542\(dq, \(dq[::1]:4542\(dq] [server] servers = [\(dq127.0.0.1:4543\(dq, \(dq[::1]:4543\(dq] -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH OPTIONS @@ -161,7 +168,7 @@ can be backed up and restored in the event of filesystem corruption. The path to the dnst binary Cascade should use. .sp Cascade relies on a Cascade specific verison of the (not yet officially -released) \fBdnst\fP program (<\fI\%https://github.com/NLnetLabs/dnst\fP>) in order +released) \fBdnst\fP program (<\X'tty: link https://github.com/NLnetLabs/dnst'\fI\%https://github.com/NLnetLabs/dnst\fP\X'tty: link'>) in order to perform DNSSEC key management. You can specify an absolute path here, or just \fBdnst\fP if it is in $PATH. .UNINDENT @@ -192,23 +199,45 @@ following levels are defined: .UNINDENT .INDENT 0.0 .TP -.B log\-target = { type = \(dqfile\(dq, path = \(dq/dev/stdout\(dq } +.B log\-target = { type = \(dqstdout\(dq } +.UNINDENT +.INDENT 0.0 +.TP +.B log\-target = { type = \(dqstderr\(dq } .UNINDENT .INDENT 0.0 .TP .B log\-target = { type = \(dqsyslog\(dq } +.UNINDENT +.INDENT 0.0 +.TP +.B log\-target = { type = \(dqfile\(dq, path = \(dqcascaded.log\(dq } The location the daemon writes logs to. .INDENT 7.0 .IP \(bu 2 type \fBfile\fP: Logs are appended line\-by\-line to the specified file path. .sp -It can be set to \fB/dev/stdout\fP or \fB/dev/stderr\fP for standard output and -error, respectively. If it is a terminal, ANSI escape codes may be used -to style the output. +If it is a terminal, ANSI escape codes may be used to style the output. +.IP \(bu 2 +type \fBstdout\fP: Logs are written to stdout. (The default) +.sp +If it is a terminal, ANSI escape codes may be used to style the output. +.IP \(bu 2 +type \fBstderr\fP: Logs are written to stderr. +.sp +If it is a terminal, ANSI escape codes may be used to style the output. .IP \(bu 2 type \fBsyslog\fP: Logs are written to the UNIX syslog. .sp This option is only supported on UNIX systems. +.INDENT 2.0 +.INDENT 3.5 +Changed in version 0.1.0\-alpha2: Added types \fBstdout\fP and \fBstderr\fP which should be used instead of +\fBfile\fP values \fB/dev/stdout\fP and \fB/dev/stderr\fP which do not work +properly in some cases, e.g. when running under systemd. + +.UNINDENT +.UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 @@ -260,7 +289,7 @@ supported; only names can be used. .INDENT 7.0 .INDENT 3.5 When using systemd, you should rely on its \(aqUser=\(aq and \(aqGroup=\(aq -options instead. See <\fI\%https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User=\fP>. +options instead. See <\X'tty: link https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User='\fI\%https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User=\fP\X'tty: link'>. .UNINDENT .UNINDENT .UNINDENT @@ -370,7 +399,7 @@ Default Cascade config file .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascaded-policy.toml.5 b/doc/manual/build/man/cascaded-policy.toml.5 index ce11ebe5..1c05acfc 100644 --- a/doc/manual/build/man/cascaded-policy.toml.5 +++ b/doc/manual/build/man/cascaded-policy.toml.5 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADED-POLICY.TOML" "5" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADED-POLICY.TOML" "5" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascaded-policy.toml \- Cascade policy file format .sp @@ -54,12 +54,20 @@ internal copy of the policy. Only policy files stored in the configured policy directory and having a \fB\&.toml\fP extension will be loaded by Cascade.\(ga .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +In the current alpha release, changes to some policy options (e.g. review +hook) also require a server restart in addition to running \fBcascade policy +reload\fP to take effect. +.UNINDENT +.UNINDENT .SH EXAMPLE .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX version = \(dqv1\(dq [loader] @@ -116,8 +124,7 @@ required = false [server.outbound] send\-notify\-to = [] -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH OPTIONS @@ -170,12 +177,16 @@ It will receive the following information via environment variables: .IP \(bu 2 \fBCASCADE_SERIAL\fP: The serial number of the zone (decimal integer). .IP \(bu 2 -\fBCASCADE_SERVER\fP: The TCP/UDP port where Cascade is serving the zone for -review, formatted \fB:\fP\&. +\fBCASCADE_SERVER\fP: The combined address and port where Cascade is serving +the zone for review, formatted as \fB:\fP\&. .IP \(bu 2 -\fBCASCADE_CONTROL\fP: The address of Cascade\(aqs HTTP API server, for sending -approvals and rejections. +\fBCASCADE_SERVER_IP\fP: Just the address of the above server. +.IP \(bu 2 +\fBCASCADE_SERVER_PORT\fP: Just the port of the above server. .UNINDENT +.sp +Added in version 0.1.0\-alpha2: \fBCASCADE_SERVER_IP\fP and \fBCASCADE_SERVER_PORT\fP\&. + .sp The command will be called from an unspecified directory, and it must be accessible to Cascade (i.e. after it has dropped privileges). Its exit code @@ -401,7 +412,7 @@ The HSM server to use. If this is set, the named HSM server (which must be configured via \fBcascade hsm add\fP) will be used for generating new DNSSEC keys. .sp -See \fI\%https://cascade.docs.nlnetlabs.nl/en/latest/hsms.html\fP for more +See \X'tty: link https://cascade.docs.nlnetlabs.nl/en/latest/hsms.html'\fI\%https://cascade.docs.nlnetlabs.nl/en/latest/hsms.html\fP\X'tty: link' for more information. .UNINDENT .INDENT 0.0 @@ -473,7 +484,7 @@ Supported options: .IP \(bu 2 \fBcounter\fP: increment the serial number every time. .IP \(bu 2 -\fBunixtime\fP: use the current Unix time, in seconds. +\fBunix\-time\fP: use the current Unix time, in seconds. .IP \(bu 2 \fBdate\-counter\fP: format the number as \fB
\fP in decimal. \fB\fP is a simple counter to allow up to 100 versions per day. @@ -573,8 +584,12 @@ It will receive the following information via environment variables: .IP \(bu 2 \fBCASCADE_SERIAL\fP: The serial number of the signed zone (decimal integer). .IP \(bu 2 -\fBCASCADE_SERVER\fP: The TCP/UDP port where Cascade is serving the zone for -review, formatted \fB:\fP\&. +\fBCASCADE_SERVER\fP: The combined address and port where Cascade is serving +the zone for review, formatted as \fB:\fP\&. +.IP \(bu 2 +\fBCASCADE_SERVER_IP\fP: Just the address of the above server. +.IP \(bu 2 +\fBCASCADE_SERVER_PORT\fP: Just the port of the above server. .UNINDENT .sp The command will be called from an unspecified directory, and it must be @@ -606,7 +621,7 @@ Default policies directory .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) diff --git a/doc/manual/build/man/cascaded.1 b/doc/manual/build/man/cascaded.1 index 911356b1..5274ca06 100644 --- a/doc/manual/build/man/cascaded.1 +++ b/doc/manual/build/man/cascaded.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CASCADED" "1" "Oct 06, 2025" "0.1.0-rc1" "Cascade" +.TH "CASCADED" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" .SH NAME cascaded \- DNSSEC signer .SH SYNOPSIS @@ -39,7 +39,7 @@ cascaded \- DNSSEC signer solution. .sp For more information about Cascade, please refer to the Cascade documentation -at \fI\%https://cascade.docs.nlnetlabs.nl\fP\&. +at \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link'\&. .SH OPTIONS .INDENT 0.0 .TP @@ -71,6 +71,11 @@ Defaults to \fBinfo\fP, unless set in the config file. Where logs should be written to [possible values: stdout, stderr, file:, syslog]. .UNINDENT +.sp +Changed in version 0.1.0\-alpha2: Added types \fBstdout\fP and \fBstderr\fP\&. Type \fBfile\fP with values \fB/dev/stdout\fP +and \fB/dev/stderr\fP can still be used but may not work properly in some +cases, e.g. when running under systemd. + .INDENT 0.0 .TP .B \-d, \-\-daemonize @@ -117,7 +122,7 @@ Default directory for KMIP state files .SH SEE ALSO .INDENT 0.0 .TP -.B \fI\%https://cascade.docs.nlnetlabs.nl\fP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' Cascade online documentation .TP \fBcascade\fP(1) From 6ef07e4637044b383e3d74c422d7d1aa999fc5c6 Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Fri, 17 Oct 2025 12:15:16 +0200 Subject: [PATCH 2/7] Remove duplicate entry in conf.py. --- doc/manual/source/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index 02d4732b..829dd92f 100644 --- a/doc/manual/source/conf.py +++ b/doc/manual/source/conf.py @@ -240,9 +240,8 @@ ('man/cascaded-policy.toml', 'cascaded-policy.toml', 'Cascade policy file format', author, 5), ('man/cascade', 'cascade', 'Cascade CLI', author, 1), ('man/cascade-config', 'cascade-config', 'Manage configuration', author, 1), - ('man/cascade-health', 'cascade-health', 'Check health', author, 1), - ('man/cascade-hsm', 'cascade-hsm', 'Manage HSMs', author, 1), ('man/cascade-health', 'cascade-health', 'Check the health of Cascade', author, 1), + ('man/cascade-hsm', 'cascade-hsm', 'Manage HSMs', author, 1), ('man/cascade-keyset', 'cascade-keyset', 'Execute manual key roll or key removal commands', author, 1), ('man/cascade-policy', 'cascade-policy', 'Manage policies', author, 1), ('man/cascade-status', 'cascade-status', 'Show the status of Cascade', author, 1), From c6fb83c66f6bac53e143b0443fe1a1cad425cab4 Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Fri, 17 Oct 2025 12:15:59 +0200 Subject: [PATCH 3/7] Fix broken link to cascade-health man page. --- doc/manual/source/man/cascade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/source/man/cascade.rst b/doc/manual/source/man/cascade.rst index 7ceb9aaa..bf803d9d 100644 --- a/doc/manual/source/man/cascade.rst +++ b/doc/manual/source/man/cascade.rst @@ -43,7 +43,7 @@ Commands Manage Cascade's configuration. - :doc:`cascade-health`\ (1) + :doc:`cascade-health `\ (1) Check the health of Cascade. From 5a030b0cd88505c76c0a7bb3e5bd77d9f72fa1af Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Fri, 17 Oct 2025 12:17:11 +0200 Subject: [PATCH 4/7] Really add built man pages. --- doc/manual/build/man/cascade-health.1 | 67 +++ doc/manual/build/man/cascade-status.1 | 66 +++ doc/manual/build/man/cascaded-config.toml.1 | 362 ++++++++++++ doc/manual/build/man/cascaded-policy.toml.1 | 618 ++++++++++++++++++++ 4 files changed, 1113 insertions(+) create mode 100644 doc/manual/build/man/cascade-health.1 create mode 100644 doc/manual/build/man/cascade-status.1 create mode 100644 doc/manual/build/man/cascaded-config.toml.1 create mode 100644 doc/manual/build/man/cascaded-policy.toml.1 diff --git a/doc/manual/build/man/cascade-health.1 b/doc/manual/build/man/cascade-health.1 new file mode 100644 index 00000000..906a03a1 --- /dev/null +++ b/doc/manual/build/man/cascade-health.1 @@ -0,0 +1,67 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CASCADE-HEALTH" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" +.SH NAME +cascade-health \- Check the health of Cascade +.sp +Added in version 0.1.0\-alpha2. + +.SH SYNOPSIS +.sp +\fBcascade health\fP +.SH DESCRIPTION +.sp +Check the health of Cascade. +.sp +Exits with code zero if Cascade is healthy, non\-zero otherwise. +.SH SEE ALSO +.INDENT 0.0 +.TP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' +Cascade online documentation +.TP +\fBcascade\fP(1) +\fI\%Cascade CLI\fP +.TP +\fBcascaded\fP(1) +\fI\%Cascade Daemon\fP +.TP +\fBcascaded\-config.toml\fP(5) +\fI\%Configuration File Format\fP +.TP +\fBcascaded\-policy.toml\fP(5) +\fI\%Policy File Format\fP +.UNINDENT +.SH AUTHOR +NLnet Labs +.SH COPYRIGHT +2025–2025, NLnet Labs +.\" Generated by docutils manpage writer. +. diff --git a/doc/manual/build/man/cascade-status.1 b/doc/manual/build/man/cascade-status.1 new file mode 100644 index 00000000..6d8d6ba4 --- /dev/null +++ b/doc/manual/build/man/cascade-status.1 @@ -0,0 +1,66 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CASCADE-STATUS" "1" "Oct 17, 2025" "0.1.0-alpha2" "Cascade" +.SH NAME +cascade-status \- Show the status of Cascade +.sp +Added in version 0.1.0\-alpha2. + +.SH SYNOPSIS +.sp +\fBcascade status\fP +.SH DESCRIPTION +.sp +Displays an at\-a\-glance status report for Cascade indicating what it is +currently doing and noting any issues that require operator action. +.SH SEE ALSO +.INDENT 0.0 +.TP +.B \X'tty: link https://cascade.docs.nlnetlabs.nl'\fI\%https://cascade.docs.nlnetlabs.nl\fP\X'tty: link' +Cascade online documentation +.TP +\fBcascade\fP(1) +\fI\%Cascade CLI\fP +.TP +\fBcascaded\fP(1) +\fI\%Cascade Daemon\fP +.TP +\fBcascaded\-config.toml\fP(5) +\fI\%Configuration File Format\fP +.TP +\fBcascaded\-policy.toml\fP(5) +\fI\%Policy File Format\fP +.UNINDENT +.SH AUTHOR +NLnet Labs +.SH COPYRIGHT +2025–2025, NLnet Labs +.\" Generated by docutils manpage writer. +. diff --git a/doc/manual/build/man/cascaded-config.toml.1 b/doc/manual/build/man/cascaded-config.toml.1 new file mode 100644 index 00000000..e0ddebf3 --- /dev/null +++ b/doc/manual/build/man/cascaded-config.toml.1 @@ -0,0 +1,362 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CASCADED-CONFIG.TOML" "1" "Oct 05, 2025" "0.1.0-rc1" "Cascade" +.SH NAME +cascaded-config.toml \- Cascade configuration file +.sp +Cascade uses the TOML format for its configuration file. A template can be +generated using \fBcascade template config\fP\&. The provided values to the options +below are the default values and are serving as a hint to the option\(aqs format. +.SH EXAMPLE +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +version = \(dqv1\(dq +policy\-dir = \(dq/etc/cascade/policies\(dq +zone\-state\-dir = \(dq/var/lib/cascade/zone\-state\(dq +tsig\-store\-path = \(dq/var/lib/cascade/tsig\-keys.db\(dq +kmip\-credentials\-store\-path = \(dq/var/lib/cascade/kmip/credentials.db\(dq +keys\-dir = \(dq/var/lib/cascade/keys\(dq +kmip\-server\-state\-dir = \(dq/var/lib/cascade/kmip\(dq +dnst\-binary\-path = \(dq/usr/libexec/cascade/cascade\-dnst\(dq + +[daemon] +log\-level = \(dqinfo\(dq +log\-target = { type = \(dqfile\(dq, path = \(dq/dev/stdout\(dq } +daemonize = false + +[remote\-control] +servers = [\(dq127.0.0.1:2060\(dq, \(dq[::1]:2060\(dq] + +[loader] +notify\-listeners = [\(dq127.0.0.1:2050\(dq, \(dq[::1]:2050\(dq] + +[loader.review] +servers = [\(dq127.0.0.1:2051\(dq, \(dq[::1]:2051\(dq] + +[signer] +[signer.review] +servers = [\(dq127.0.0.1:2052\(dq, \(dq[::1]:2052\(dq] + +[key\-manager] + +[server] +servers = [\(dq127.0.0.1:2053\(dq, \(dq[::1]:2053\(dq] +.EE +.UNINDENT +.UNINDENT +.SH GLOBAL OPTIONS +.INDENT 0.0 +.TP +.B version = \(dqv1\(dq +The configuration file version. (REQUIRED) +.sp +This is the only required option. All other settings, and their defaults, +are associated with this version number. More versions may be added in the +future and Cascade may drop support for older versions over time. +.INDENT 7.0 +.IP \(bu 2 +\fBv1\fP: This format. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B policy\-dir = \(dq/etc/cascade/policies\(dq +The directory storing zone policies. +.sp +Zone policies are user\-managed files configuring groups of zones. You can +modify them as you like, then ask Cascade to reload them with \(aqcascade +policy reload\(aq. +.UNINDENT +.INDENT 0.0 +.TP +.B zone\-state\-dir = \(dq/var/lib/cascade/zone\-state\(dq +The directory storing per\-zone state files. +.sp +Cascade maintains an internal state file for every known zone here. These +files should not be modified manually, but they can be backed up and +restored in the event of filesystem corruption. +.UNINDENT +.INDENT 0.0 +.TP +.B tsig\-store\-path = \(dq/var/lib/cascade/tsig\-keys.db\(dq +The file storing TSIG key secrets. +.sp +This is an internal state file containing sensitive cryptographic material. +It should not be modified manually, but it can be backed up and restored in +the event of filesystem corruption. Carefully consider its security. +.UNINDENT +.INDENT 0.0 +.TP +.B kmip\-credentials\-store\-path = \(dq/var/lib/cascade/kmip/credentials.db\(dq +The file storing KMIP credentials. +.sp +This is an internal state file containing sensitive cryptographic material. +It should not be modified manually, but it can be backed up and restored in +the event of filesystem corruption. Carefully consider its security. +.UNINDENT +.INDENT 0.0 +.TP +.B keys\-dir = \(dq/var/lib/cascade/keys\(dq +The directory storing rollover states and on\-disk DNSSEC keys. +.sp +For every zone, the state of its DNSSEC keys (which keys are used, ongoing +rollovers, etc.) are stored here. If on\-disk keys are used to sign zones, +they are stored also here. +.sp +The organization of this directory (file names and file formats) constitutes +internal implementation details. It should not be modified manually, but it +can be backed up and restored in the event of filesystem corruption. +Carefully consider its security. +.UNINDENT +.INDENT 0.0 +.TP +.B kmip\-server\-state\-dir = \(dq/var/lib/cascade/kmip\(dq +The directory containing KMIP server state. +.sp +Information about known KMIP servers is stored in this directory. +.sp +The organization of this directory (file names and file formats) constitutes +internal implementation details. It should not be modified manually, but it +can be backed up and restored in the event of filesystem corruption. +.UNINDENT +.INDENT 0.0 +.TP +.B dnst\-binary\-path = \(dq/usr/libexec/cascade/cascade\-dnst\(dq +The path to the dnst binary Cascade should use. +.sp +Cascade relies on the (not yet officially released) \fBdnst\fP program +(<\X'tty: link https://github.com/NLnetLabs/dnst'\fI\%https://github.com/NLnetLabs/dnst\fP\X'tty: link'>) in order to perform DNSSEC key +rollovers. You can specify an absolute path here, or just \fBdnst\fP if it is +in $PATH. +.UNINDENT +.SH SETTINGS RELEVANT TO ANY DAEMON PROGRAM. +.sp +The \fB[daemon]\fP section. +.INDENT 0.0 +.TP +.B log\-level = \(dqinfo\(dq +The minimum severity of the messages logged by the daemon. +.sp +Messages at or above the specified severity level will be logged. The +following levels are defined: +.INDENT 7.0 +.IP \(bu 2 +\fBtrace\fP: A function or variable was interacted with, for debugging. +.IP \(bu 2 +\fBdebug\fP: Something occurred that may be relevant to debugging. +.IP \(bu 2 +\fBinfo\fP: Things are proceeding as expected. +.IP \(bu 2 +\fBwarning\fP: Something does not appear to be correct. +.IP \(bu 2 +\fBerror\fP: Something went wrong (but Cascade can recover). +.IP \(bu 2 +\fBcritical\fP: Something went wrong and Cascade can\(aqt function at all. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B log\-target = { type = \(dqfile\(dq, path = \(dq/dev/stdout\(dq } +.UNINDENT +.INDENT 0.0 +.TP +.B log\-target = { type = \(dqsyslog\(dq } +The location the daemon writes logs to. +.INDENT 7.0 +.IP \(bu 2 +type \fBfile\fP: Logs are appended line\-by\-line to the specified file path. +.sp +It can be set to \fB/dev/stdout\fP or \fB/dev/stderr\fP for standard output and +error, respectively. If it is a terminal, ANSI escape codes may be used +to style the output. +.IP \(bu 2 +type \fBsyslog\fP: Logs are written to the UNIX syslog. +.sp +This option is only supported on UNIX systems. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B daemonize = false +Whether to apply internal daemonization. +.sp +\(aqDaemonization\(aq involves several steps: +.INDENT 7.0 +.IP \(bu 2 +Forking the process to disconnect it from the terminal +.IP \(bu 2 +Tracking the new process\(aq PID (by storing it in a file) +.IP \(bu 2 +Binding privileged ports (below 1024) as configured +.IP \(bu 2 +Dropping administrator privileges +.UNINDENT +.sp +These features may be provided by an external system service manager, such +as systemd. If no such service manager is being used, Cascade can provide +such features itself, by setting this option to \fBtrue\fP\&. This will also +enable the \fBpid\-file\fP and \fBidentity\fP settings (although they remain +optional). +.UNINDENT +.INDENT 0.0 +.TP +.B pid\-file = \(dq/var/run/cascade.pid\(dq +The path to a PID file to maintain, if any. +.sp +If specified, Cascade will maintain a PID file at this location; it will be +a simple plain\-text file containing the PID number of the daemon process. +This option is only supported if \fBdaemonize\fP is true. +.UNINDENT +.INDENT 0.0 +.TP +.B identity = \(dqcascade:cascade\(dq +An identity (user and group) to assume after startup. +.sp +Cascade will assume the specified identity after initialization. Note that +this will fail if Cascade is started without administrator privileges. This +option is only supported if \fBdaemonize\fP is \fBtrue\fP\&. +.sp +The identity can be specified as \fB:\fP or just \fB\fP; in the +latter case, the identically named group will be used. Numeric IDs are not +supported; only names can be used. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When using systemd, you should rely on its \(aqUser=\(aq and \(aqGroup=\(aq +options instead. See <\X'tty: link https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User='\fI\%https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User=\fP\X'tty: link'>. +.UNINDENT +.UNINDENT +.UNINDENT +.SH HOW CASCADE IS CONTROLLED. +.sp +The \fB[remote\-control]\fP section. +.INDENT 0.0 +.TP +.B servers = [\(dq127.0.0.1:2060\(dq, \(dq[::1]:2060\(dq] +Where to serve Cascade\(aqs HTTP API. +.sp +The HTTP API can be used to monitor and control Cascade. The addresses +refer to TCP sockets that will be listened on for HTTP requests. At the +moment, security mechanisms like TLS are not supported. +.sp +These sockets may be bound by systemd and passed into Cascade. If systemd +does not provide them, Cascade will bind them itself (and will do so before +dropping privileges, if that is enabled). +.UNINDENT +.SH HOW ZONES ARE LOADED. +.sp +The \fB[loader]\fP section. +.INDENT 0.0 +.TP +.B notify\-listeners = [\(dq127.0.0.1:2050\(dq, \(dq[::1]:2050\(dq] +Where to listen for zone change notifications. +.sp +A DNS server will be bound to these addresses. If a DNS NOTIFY message for +a known zone is received there, the zone will be reloaded appropriately. +.sp +Unless explicitly specified (e.g. \fBudp://localhost:2050\fP), each address will +be served over UDP and TCP. An empty array will disable listening entirely. +.sp +These sockets may be bound by systemd and passed into Cascade. If systemd +does not provide them, Cascade will bind them itself (and will do so before +dropping privileges, if that is enabled). +.UNINDENT +.SH HOW LOADED ZONES ARE REVIEWED. +.sp +The \fB[loader.review]\fP section. +.INDENT 0.0 +.TP +.B servers = [\(dq127.0.0.1:2051\(dq, \(dq[::1]:2051\(dq] +Where to serve loaded zones for review. +.sp +A DNS server will be bound to these addresses, and will serve the contents +of all loaded zones. This can be used to verify the consistency of these +zones. +.sp +Unless explicitly specified (e.g. \fBudp://localhost:2051\fP), each address will +be served over UDP and TCP. An empty array will disable serving entirely. +.sp +These sockets may be bound by systemd and passed into Cascade. If systemd +does not provide them, Cascade will bind them itself (and will do so before +dropping privileges, if that is enabled). +.UNINDENT +.SH HOW ZONES ARE SIGNED. +.sp +The \fB[signer]\fP section. (This only includes the \fB[signer.review]\fP section +below, for now). +.SH HOW SIGNED ZONES ARE REVIEWED. +.sp +The \fB[signer.review]\fP section. +.INDENT 0.0 +.TP +.B servers = [\(dq127.0.0.1:2052\(dq, \(dq[::1]:2052\(dq] +Where to serve signed zones for review. +.sp +A DNS server will be bound to these addresses, and will serve the contents +of all signed (but not necessarily published) zones. This can be used to +check the correctness of the signer. +.sp +Unless explicitly specified (e.g. \fBudp://localhost:2052\fP), each address will +be served over UDP and TCP. An empty array will disable serving entirely. +.sp +These sockets may be bound by systemd and passed into Cascade. If systemd +does not provide them, Cascade will bind them itself (and will do so before +dropping privileges, if that is enabled). +.UNINDENT +.SH DNSSEC KEY MANAGEMENT. +.sp +The \fB[key\-manager]\fP section. (Currently without options) +.SH HOW ZONES ARE PUBLISHED. +.sp +The \fB[server]\fP section. +.INDENT 0.0 +.TP +.B servers = [\(dq127.0.0.1:2053\(dq, \(dq[::1]:2053\(dq] +Where to serve published zones. +.sp +A DNS server will be bound to these addresses, and will serve the contents +of all published zones. This is the final output from Cascade. +.sp +Unless explicitly specified (e.g. \fBudp://localhost:2053\fP), each address will +be served over UDP and TCP. At least one address must be specified. +.sp +These sockets may be bound by systemd and passed into Cascade. If systemd +does not provide them, Cascade will bind them itself (and will do so before +dropping privileges, if that is enabled). +.UNINDENT +.SH AUTHOR +NLnet Labs +.SH COPYRIGHT +2025–2025, NLnet Labs +.\" Generated by docutils manpage writer. +. diff --git a/doc/manual/build/man/cascaded-policy.toml.1 b/doc/manual/build/man/cascaded-policy.toml.1 new file mode 100644 index 00000000..8caaea9c --- /dev/null +++ b/doc/manual/build/man/cascaded-policy.toml.1 @@ -0,0 +1,618 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CASCADED-POLICY.TOML" "1" "Oct 05, 2025" "0.1.0-rc1" "Cascade" +.SH NAME +cascaded-policy.toml \- Cascade policy file format +.sp +A policy is a collection of settings that apply to a group of zones known to +Cascade. Policy controls how Cascade operates on those zones, e.g. how they +are signed. This page describes all possible settings and their defaults. You +can generate a template with these default values using \fBcascade template +policy\fP\&. +.sp +Policy files are managed by the user, and are stored at a configurable path +(by default, \fB/etc/cascade/policies\fP). You can add, modify, and remove +policy files, then update Cascade with \fBcascade policy reload\fP\&. Note that: +.INDENT 0.0 +.IP \(bu 2 +Cascade maintains an internal copy of all policies, and will use this until +\fBcascade policy reload\fP is used. If reloading fails, Cascade will continue +to use its existing internal copy. It won\(aqt reload policies if it restarts. +.IP \(bu 2 +Policies cannot be removed if they are attached to zones; those zones need +to be deleted or shifted to a different policy first. If you remove a used +policy and reload policies in Cascade, it will fail and continue to use its +internal copy of the policy. +.UNINDENT +.SH EXAMPLE +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +version = \(dqv1\(dq + +[loader] +[loader.review] +required = false + +[key\-manager] +ksk.validity = \(dq31536000\(dq +zsk.validity = \(dq2592000\(dq +csk.validity = \(dq31536000\(dq +ksk.auto\-start = true +zsk.auto\-start = true +csk.auto\-start = true +algorithm.auto\-start = true +ksk.auto\-report = true +zsk.auto\-report = true +csk.auto\-report = true +algorithm.auto\-report = true +ksk.auto\-expire = true +zsk.auto\-expire = true +csk.auto\-expire = true +algorithm.auto\-expire = true +ksk.auto\-done = true +zsk.auto\-done = true +csk.auto\-done = true +algorithm.auto\-done = true +ds\-algorithm = \(dqSHA256\(dq +auto\-remove = true + +[key\-manager.records] +ttl = 3600 +dnskey.signature\-inception\-offset = 86400 +cds.signature\-inception\-offset = 86400 +dnskey.signature\-lifetime = 1209600 +cds.signature\-lifetime = 1209600 +dnskey.signature\-remain\-time = 604800 +cds.signature\-remain\-time = 604800 + +[key\-manager.generation] +use\-csk = false +algorithm = \(dqECDSAP256SHA256\(dq + +[signer] +serial\-policy = \(dqdate\-counter\(dq +signature\-inception\-offset = 86400 +signature\-lifetime = 1209600 +signature\-remain\-time = 604800 + +[signer.denial] +type = \(dqnsec\(dq + +[signer.review] +required = false + +[server.outbound] +send\-notify\-to = [] +.EE +.UNINDENT +.UNINDENT +.SH GLOBAL OPTIONS +.INDENT 0.0 +.TP +.B version = \(dqv1\(dq +The policy file version. (REQUIRED) +.sp +This is the only required option. All other settings, and their defaults, +are associated with this version number. More versions may be added in the +future and Cascade may drop support for older versions over time. +.INDENT 7.0 +.IP \(bu 2 +\fBv1\fP: This format. +.UNINDENT +.UNINDENT +.SH HOW ZONES ARE LOADED. +.sp +The \fB[loader]\fP section. +.INDENT 0.0 +.TP +.B [loader.review] +How loaded zones are reviewed. +.sp +Review offers an opportunity to perform external checks on the zone contents +loaded by Cascade. +.UNINDENT +.INDENT 0.0 +.TP +.B required = false +Whether review is required. +.sp +If this is \fBtrue\fP, a loaded version of a zone will not be signed or +published until it is approved. If it is \fBfalse\fP, loaded zones will be +signed immediately. At the moment, the review hook will only be run if this +is set to true. +.UNINDENT +.INDENT 0.0 +.TP +.B cmd\-hook = \(dq\(dq +A hook for reviewing a loaded zone. This is a path to an executable. +.sp +This command string will be executed in the user\(aqs shell when a new version +of a zone is loaded. At the moment, it will only be run if \fBrequired\fP is +true. +.sp +It will receive the following information via environment variables: +.INDENT 7.0 +.IP \(bu 2 +\fBCASCADE_ZONE\fP: The name of the zone, formatted without a trailing dot. +.IP \(bu 2 +\fBCASCADE_SERIAL\fP: The serial number of the zone (decimal integer). +.IP \(bu 2 +\fBCASCADE_TOKEN\fP: A UUID associated with this review, for approving or +rejecting this version of the zone. +.IP \(bu 2 +\fBCASCADE_SERVER\fP: The TCP/UDP port where Cascade is serving the zone for +review, formatted \fB:\fP\&. +.IP \(bu 2 +\fBCASCADE_CONTROL\fP: The address of Cascade\(aqs HTTP API server, for sending +approvals and rejections. +.UNINDENT +.sp +The command will be called from an unspecified directory, and it must be +accessible to Cascade (i.e. after it has dropped privileges). +.sp +To approve the zone contents, send an HTTP GET request to +\fBhttp://$CASCADE_CONTROL/approve/$CASCADE_TOKEN?zone=$CASCADE_ZONE&serial=$CASCADE_SERIAL\fP\&. +\fBapprove\fP can be replaced by \fBreject\fP to reject the zone. If the command +exits without approving or rejecting the zone, Cascade will wait for the +user to approve it manually. +.UNINDENT +.SH DNSSEC KEY MANAGEMENT. +.sp +The \fB[key\-manager]\fP section. +.INDENT 0.0 +.TP +.B ksk.validity = \(dq31536000\(dq +.UNINDENT +.INDENT 0.0 +.TP +.B zsk.validity = \(dq2592000\(dq +.UNINDENT +.INDENT 0.0 +.TP +.B csk.validity = \(dq31536000\(dq +How long keys are considered valid for. +.sp +If a key has been used for longer than this time, it is considered expired, +and (if enabled) it will automatically be rolled over to a new key. Even if +automatic rollovers are not enabled, the key will be reported as expired. +This is a soft condition \-\- DNSSEC does not have a concept of key expiry, +and it will not break DNSSEC validation, but it is usually important to the +security of the zone. +.sp +Independent validity times are set for KSKs, ZSKs, and CSKs. An integer +value will be interpreted as seconds; \fBforever\fP means keys never expire. +.UNINDENT +.INDENT 0.0 +.TP +.B ksk.auto\-start = true +.UNINDENT +.INDENT 0.0 +.TP +.B zsk.auto\-start = true +.UNINDENT +.INDENT 0.0 +.TP +.B csk.auto\-start = true +.UNINDENT +.INDENT 0.0 +.TP +.B algorithm.auto\-start = true +Whether to automatically start key rollovers. +.sp +If this is enabled, Cascade will automatically start rolling over keys when +they expire (as per \fBvalidity\fP). When using this setting, \fBvalidity\fP must +not be set to \fBforever\fP\&. +.sp +The first step in a rollover will be to generate new keys to replace old +ones. By disabling this setting, the user can manually control how new keys +are generated, and when rollovers happen. +.UNINDENT +.INDENT 0.0 +.TP +.B ksk.auto\-report = true +.UNINDENT +.INDENT 0.0 +.TP +.B zsk.auto\-report = true +.UNINDENT +.INDENT 0.0 +.TP +.B csk.auto\-report = true +.UNINDENT +.INDENT 0.0 +.TP +.B algorithm.auto\-report = true +Whether to automatically check for record propagation. +.sp +If this is enabled, Cascade will automatically contact public DNS servers to +detect when new records (e.g. DNSKEY) are visible globally. It is necessary +to wait until some records are visible globally to progress key rollovers. If +this is disabled, the user will have to inform Cascade when these conditions +are reached manually. +.sp +For this setting to work, Cascade must have network access to the zone\(aqs +public nameservers and the parent zone\(aqs public nameservers. +.UNINDENT +.INDENT 0.0 +.TP +.B ksk.auto\-expire = true +.UNINDENT +.INDENT 0.0 +.TP +.B zsk.auto\-expire = true +.UNINDENT +.INDENT 0.0 +.TP +.B csk.auto\-expire = true +.UNINDENT +.INDENT 0.0 +.TP +.B algorithm.auto\-expire = true +Whether to automatically wait for cache expiry. +.sp +If this is enabled, Cascade will automatically progress through key rollover +steps that need to wait for downstream users\(aq DNS caches to expire. It will +estimate the right amount of time to wait based on record TTLs. +.UNINDENT +.INDENT 0.0 +.TP +.B ksk.auto\-done = true +.UNINDENT +.INDENT 0.0 +.TP +.B zsk.auto\-done = true +.UNINDENT +.INDENT 0.0 +.TP +.B csk.auto\-done = true +.UNINDENT +.INDENT 0.0 +.TP +.B algorithm.auto\-done = true +Whether to automatically check for rollover completion. +.sp +Like \fBauto\-report\fP, if this setting is enabled, Cascade will automatically +contact public DNS servers to detect when new records are visible globally. +\fBauto\-done\fP specifically affects automatic checks for the last step of key +rollovers, and is independent from \fBauto\-report\fP\&. +.sp +For this setting to work, Cascade must have network access to the zone\(aqs +public nameservers and the parent zone\(aqs public nameservers. +.UNINDENT +.INDENT 0.0 +.TP +.B ds\-algorithm = \(dqSHA256\(dq +The hash algorithm used by the parent zones\(aq DS records. +.sp +Supported options: +.INDENT 7.0 +.IP \(bu 2 +\fBSHA256\fP: SHA\-256. +.IP \(bu 2 +\fBSHA384\fP: SHA\-384. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B auto\-remove = true +Whether to automatically remove expired keys. +.sp +If this is set, expired keys will be removed automatically (by deleting the +files for on\-disk keys or removing it from the HSM). +.UNINDENT +.SH THE MANAGEMENT OF DNS RECORDS BY THE KEY MANAGER. +.sp +The \fB[key\-manager.records]\fP section. +.sp +The key manager generates and signs several records (DNSKEY and CDS). This +section controls its behaviour towards them. +.INDENT 0.0 +.TP +.B ttl = 3600 +The TTL for the generated records. +.UNINDENT +.INDENT 0.0 +.TP +.B dnskey.signature\-inception\-offset = 86400 +.UNINDENT +.INDENT 0.0 +.TP +.B cds.signature\-inception\-offset = 86400 +The offset for generated signature inceptions. +.sp +Record signatures have a fixed inception time, from when they are considered +valid. An imprecise computer clock could cause signatures to be considered +invalid, because their inception point appears to be some time in the future. +To prevent such cases, this setting allows the inception time to be offset +into the past. +.sp +Independent offsets can be set for each type of record. An integer value is +intepreted as seconds; inception times will be calculated as \fBnow \- offset\fP +at the time of signing. +.UNINDENT +.INDENT 0.0 +.TP +.B dnskey.signature\-lifetime = 1209600 +.UNINDENT +.INDENT 0.0 +.TP +.B cds.signature\-lifetime = 1209600 +The lifetime of generated signatures. +.sp +Record signatures have a fixed lifetime, after which they are considered +invalid. To keep the zone valid, the signatures should be regenerated before +they expire; see \fBsignature\-remain\-time\fP to control regeneration time. +.sp +Independent lifetimes can be set for each type of record. An integer value is +interpreted as seconds. +.UNINDENT +.INDENT 0.0 +.TP +.B dnskey.signature\-remain\-time = 604800 +.UNINDENT +.INDENT 0.0 +.TP +.B cds.signature\-remain\-time = 604800 +The amount of time remaining before expiry when signatures will be +regenerated. +.sp +In order to prevent a zone\(aqs signatures from appearing invalid, they +have to be regenerated before they expire. That hard limit is set by +\fBsignature\-lifetime\fP above. This setting controls how long before expiry +signatures will be regenerated; it must be less than the \fBsignature\-lifetime\fP +setting. +.sp +Independent waiting times can be set for each type of record. An integer +value is interpreted as seconds. +.UNINDENT +.SH HOW KEYS ARE GENERATED. +.sp +The \fB[key\-manager.generation]\fP section. +.INDENT 0.0 +.TP +.B hsm\-server\-id = \(dq\(dq +The HSM server to use. +.sp +If this is set, the named HSM server (which must be configured via \(aqcascade +hsm add\(aq) will be used for generating new DNSSEC keys. +.sp +See \X'tty: link https://cascade.docs.nlnetlabs.nl/en/latest/hsms.html'\fI\%https://cascade.docs.nlnetlabs.nl/en/latest/hsms.html\fP\X'tty: link' for more +information. +.UNINDENT +.INDENT 0.0 +.TP +.B use\-csk = false +Whether to generate CSKs, instead of separate ZSKs and KSKs. +.sp +A CSK (Combined Signing Key) takes the role of both ZSK and KSK for a zone, +unlike the standard practice of using separate keys for ZSK and KSK. This +setting does not affect how DNSSEC validation is performed, only procedures +for key rollovers. +.sp +If this is enabled, Cascade will generate CSKs for the associated zones. +.UNINDENT +.INDENT 0.0 +.TP +.B algorithm = \(dqECDSAP256SHA256\(dq +The cryptographic algorithm (and parameters) for generated keys. +.sp +DNSSEC supports various cryptographic algorithms for signatures; one must be +selected, and for some algorithms, additional parameters are also necessary. +The same algorithm and parameters will be applied to the ZSK and KSK. +.INDENT 7.0 +.IP \(bu 2 +\fBRSASHA256[:]\fP, algorithm 8, with a public key size of +\fB\fP (default 2048) bits. +.IP \(bu 2 +\fBRSASHA512[:]\fP, algorithm 10, with a public key size of +\fB\fP (default 2048) bits. +.IP \(bu 2 +\fBECDSAP256SHA256\fP, algorithm 13. +.IP \(bu 2 +\fBECDSAP384SHA384\fP, algorithm 14. +.IP \(bu 2 +\fBED25519\fP, algorithm 15. +.IP \(bu 2 +\fBED448\fP, algorithm 16. +.UNINDENT +.sp +There are additional algorithms, but many are now considered insecure, and +it is recommended or mandated to avoid them. In addition, RSA keys smaller +than 2048 bits are not recommended. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +At the moment, only RSASHA256 and ECDSAP256SHA256 work with HSMs. +Other algorithms cannot be used with HSMs, and will cause generation +failures. +.UNINDENT +.UNINDENT +.UNINDENT +.SH HOW ZONES ARE SIGNED. +.sp +The \fB[signer]\fP section. +.sp +Note that certain records (e.g. DNSKEY and CDS records at the apex of the +zone) are signed by the key manager, rather than the zone signer; see the +\fB[key\-manager.records]\fP section for configuring the signing of those records. +.INDENT 0.0 +.TP +.B serial\-policy = \(dqdate\-counter\(dq +How SOA serial numbers are generated for signed zones. +.sp +Supported options: +.INDENT 7.0 +.IP \(bu 2 +\fBkeep\fP: use the same serial number as the unsigned zone. +.IP \(bu 2 +\fBcounter\fP: increment the serial number every time. +.IP \(bu 2 +\fBunixtime\fP: use the current Unix time, in seconds. +.IP \(bu 2 +\fBdate\-counter\fP: format the number as \fB
\fP in decimal. +\fB\fP is a simple counter to allow up to 100 versions per day. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B signature\-inception\-offset = 86400 +The offset for generated signature inceptions. +.sp +Record signatures have a fixed inception time, from when they are considered +valid. An imprecise computer clock could cause signatures to be considered +invalid, because their inception point appears to be some time in the +future. To prevent such cases, this setting allows the inception time to be +offset into the past. +.sp +An integer value is interpreted as seconds; inception times will be +calculated as \fBnow \- offset\fP at the time of signing. +.UNINDENT +.INDENT 0.0 +.TP +.B signature\-lifetime = 1209600 +The lifetime of generated signatures. +.sp +Record signatures have a fixed lifetime, after which they are considered +invalid. To keep the zone valid, the signatures should be regenerated before +they expire; see \fBsignature\-remain\-time\fP to control regeneration time. +.sp +An integer value is interpreted as seconds. +.UNINDENT +.INDENT 0.0 +.TP +.B signature\-remain\-time = 604800 +The amount of time remaining before expiry when signatures will be +regenerated. +.sp +In order to prevent a zone\(aqs signatures from appearing invalid, they +have to be regenerated before they expire. That hard limit is set by +\fBsignature\-lifetime\fP above. This setting controls how long before expiry +signatures will be regenerated; it must be less than the \fBsignature\-lifetime\fP +setting. +.sp +An integer value is interpreted as seconds. +.UNINDENT +.SH HOW DENIAL-OF-EXISTENCE RECORDS ARE GENERATED. +.sp +The \fB[signer.denial]\fP section. +.INDENT 0.0 +.TP +.B type = \(dqnsec\(dq +The type of denial\-of\-existence records to generate. +.sp +Supported options: +\- \fBnsec\fP: Use NSEC records (RFC 4034). +\- \fBnsec3\fP: Use NSEC3 records (RFC 5155). +.UNINDENT +.INDENT 0.0 +.TP +.B opt\-out = false +(Only set when using NSEC3) +.sp +Whether to skip NSEC3 records for unsigned delegations. +.sp +This enables the NSEC3 Opt\-Out flag, and skips delegations to unsigned zones +when generating NSEC3 records. This affects the security of the zone, so be +careful if you wish to enable it. +.UNINDENT +.SH HOW SIGNED ZONES ARE REVIEWED. +.sp +The \fB[signer.review]\fP section. +.INDENT 0.0 +.TP +.B required = false +Whether review is required. +.sp +If this is \fBtrue\fP, a signed version of a zone will not be published until it +is approved. If it is \fBfalse\fP, signed zones will be published immediately. +At the moment, the review hook will only be run if this is set to true. +.UNINDENT +.INDENT 0.0 +.TP +.B cmd\-hook = \(dq\(dq +A hook for reviewing a signed zone. This is a path to an executable. +.sp +This command string will be executed in the user\(aqs shell when a new version of +a zone is signed. At the moment, it will only be run if \fBrequired\fP is true. +.sp +It will receive the following information via environment variables: +.INDENT 7.0 +.IP \(bu 2 +\fBCASCADE_ZONE\fP: The name of the zone, formatted without a trailing dot. +.IP \(bu 2 +\fBCASCADE_SERIAL\fP: The serial number of the signed zone (decimal integer). +.IP \(bu 2 +\fBCASCADE_UNSIGNED_SERIAL\fP: The serial number of the unsigned zone from which +the signed zone was generated (decimal integer). +.IP \(bu 2 +\fBCASCADE_TOKEN\fP: A UUID associated with this review, for approving or +rejecting this version of the zone. +.IP \(bu 2 +\fBCASCADE_SERVER\fP: The TCP/UDP port where Cascade is serving the zone for +review, formatted \fB:\fP\&. +.IP \(bu 2 +\fBCASCADE_UNSIGNED_SERVER\fP: The TCP/UDP port where Cascade is serving the +unsigned version of the zone for review, formatted \fB:\fP\&. +.IP \(bu 2 +\fBCASCADE_CONTROL\fP: The address of Cascade\(aqs HTTP API server, for sending +approvals and rejections. +.UNINDENT +.sp +The command will be called from an unspecified directory, and it must be +accessible to Cascade (i.e. after it has dropped privileges). +.sp +To approve the zone contents, send an HTTP GET request to +\fBhttp://$CASCADE_CONTROL/approve/$CASCADE_TOKEN?zone=$CASCADE_ZONE&serial=$CASCADE_SERIAL\fP\&. +\fBapprove\fP can be replaced by \fBreject\fP to reject the zone. If the +command exits without approving or rejecting the zone, Cascade will wait for +the user to approve it manually. +.UNINDENT +.SH HOW PUBLISHED ZONES ARE SERVED. +.sp +The \fB[server.outbound]\fP section. +.INDENT 0.0 +.TP +.B send\-notify\-to = [] +The set of nameservers to which NOTIFY messages should be sent. +.sp +If empty, no NOTIFY messages will be sent. +.sp +A collection of \fBIP:[port]\fP, defaulting to port 53 when not specified, e.g.: +\fBsend\-notify\-to = [\(dq[::1]:53\(dq]\fP +.UNINDENT +.SH AUTHOR +NLnet Labs +.SH COPYRIGHT +2025–2025, NLnet Labs +.\" Generated by docutils manpage writer. +. From 4304432349e0512e954dca1b3b68121c9db085b0 Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Fri, 17 Oct 2025 12:19:33 +0200 Subject: [PATCH 5/7] Revert accidental addition of old locally built files that make man no longer builds. --- doc/manual/build/man/cascaded-config.toml.1 | 362 ------------ doc/manual/build/man/cascaded-policy.toml.1 | 618 -------------------- 2 files changed, 980 deletions(-) delete mode 100644 doc/manual/build/man/cascaded-config.toml.1 delete mode 100644 doc/manual/build/man/cascaded-policy.toml.1 diff --git a/doc/manual/build/man/cascaded-config.toml.1 b/doc/manual/build/man/cascaded-config.toml.1 deleted file mode 100644 index e0ddebf3..00000000 --- a/doc/manual/build/man/cascaded-config.toml.1 +++ /dev/null @@ -1,362 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "CASCADED-CONFIG.TOML" "1" "Oct 05, 2025" "0.1.0-rc1" "Cascade" -.SH NAME -cascaded-config.toml \- Cascade configuration file -.sp -Cascade uses the TOML format for its configuration file. A template can be -generated using \fBcascade template config\fP\&. The provided values to the options -below are the default values and are serving as a hint to the option\(aqs format. -.SH EXAMPLE -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -version = \(dqv1\(dq -policy\-dir = \(dq/etc/cascade/policies\(dq -zone\-state\-dir = \(dq/var/lib/cascade/zone\-state\(dq -tsig\-store\-path = \(dq/var/lib/cascade/tsig\-keys.db\(dq -kmip\-credentials\-store\-path = \(dq/var/lib/cascade/kmip/credentials.db\(dq -keys\-dir = \(dq/var/lib/cascade/keys\(dq -kmip\-server\-state\-dir = \(dq/var/lib/cascade/kmip\(dq -dnst\-binary\-path = \(dq/usr/libexec/cascade/cascade\-dnst\(dq - -[daemon] -log\-level = \(dqinfo\(dq -log\-target = { type = \(dqfile\(dq, path = \(dq/dev/stdout\(dq } -daemonize = false - -[remote\-control] -servers = [\(dq127.0.0.1:2060\(dq, \(dq[::1]:2060\(dq] - -[loader] -notify\-listeners = [\(dq127.0.0.1:2050\(dq, \(dq[::1]:2050\(dq] - -[loader.review] -servers = [\(dq127.0.0.1:2051\(dq, \(dq[::1]:2051\(dq] - -[signer] -[signer.review] -servers = [\(dq127.0.0.1:2052\(dq, \(dq[::1]:2052\(dq] - -[key\-manager] - -[server] -servers = [\(dq127.0.0.1:2053\(dq, \(dq[::1]:2053\(dq] -.EE -.UNINDENT -.UNINDENT -.SH GLOBAL OPTIONS -.INDENT 0.0 -.TP -.B version = \(dqv1\(dq -The configuration file version. (REQUIRED) -.sp -This is the only required option. All other settings, and their defaults, -are associated with this version number. More versions may be added in the -future and Cascade may drop support for older versions over time. -.INDENT 7.0 -.IP \(bu 2 -\fBv1\fP: This format. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B policy\-dir = \(dq/etc/cascade/policies\(dq -The directory storing zone policies. -.sp -Zone policies are user\-managed files configuring groups of zones. You can -modify them as you like, then ask Cascade to reload them with \(aqcascade -policy reload\(aq. -.UNINDENT -.INDENT 0.0 -.TP -.B zone\-state\-dir = \(dq/var/lib/cascade/zone\-state\(dq -The directory storing per\-zone state files. -.sp -Cascade maintains an internal state file for every known zone here. These -files should not be modified manually, but they can be backed up and -restored in the event of filesystem corruption. -.UNINDENT -.INDENT 0.0 -.TP -.B tsig\-store\-path = \(dq/var/lib/cascade/tsig\-keys.db\(dq -The file storing TSIG key secrets. -.sp -This is an internal state file containing sensitive cryptographic material. -It should not be modified manually, but it can be backed up and restored in -the event of filesystem corruption. Carefully consider its security. -.UNINDENT -.INDENT 0.0 -.TP -.B kmip\-credentials\-store\-path = \(dq/var/lib/cascade/kmip/credentials.db\(dq -The file storing KMIP credentials. -.sp -This is an internal state file containing sensitive cryptographic material. -It should not be modified manually, but it can be backed up and restored in -the event of filesystem corruption. Carefully consider its security. -.UNINDENT -.INDENT 0.0 -.TP -.B keys\-dir = \(dq/var/lib/cascade/keys\(dq -The directory storing rollover states and on\-disk DNSSEC keys. -.sp -For every zone, the state of its DNSSEC keys (which keys are used, ongoing -rollovers, etc.) are stored here. If on\-disk keys are used to sign zones, -they are stored also here. -.sp -The organization of this directory (file names and file formats) constitutes -internal implementation details. It should not be modified manually, but it -can be backed up and restored in the event of filesystem corruption. -Carefully consider its security. -.UNINDENT -.INDENT 0.0 -.TP -.B kmip\-server\-state\-dir = \(dq/var/lib/cascade/kmip\(dq -The directory containing KMIP server state. -.sp -Information about known KMIP servers is stored in this directory. -.sp -The organization of this directory (file names and file formats) constitutes -internal implementation details. It should not be modified manually, but it -can be backed up and restored in the event of filesystem corruption. -.UNINDENT -.INDENT 0.0 -.TP -.B dnst\-binary\-path = \(dq/usr/libexec/cascade/cascade\-dnst\(dq -The path to the dnst binary Cascade should use. -.sp -Cascade relies on the (not yet officially released) \fBdnst\fP program -(<\X'tty: link https://github.com/NLnetLabs/dnst'\fI\%https://github.com/NLnetLabs/dnst\fP\X'tty: link'>) in order to perform DNSSEC key -rollovers. You can specify an absolute path here, or just \fBdnst\fP if it is -in $PATH. -.UNINDENT -.SH SETTINGS RELEVANT TO ANY DAEMON PROGRAM. -.sp -The \fB[daemon]\fP section. -.INDENT 0.0 -.TP -.B log\-level = \(dqinfo\(dq -The minimum severity of the messages logged by the daemon. -.sp -Messages at or above the specified severity level will be logged. The -following levels are defined: -.INDENT 7.0 -.IP \(bu 2 -\fBtrace\fP: A function or variable was interacted with, for debugging. -.IP \(bu 2 -\fBdebug\fP: Something occurred that may be relevant to debugging. -.IP \(bu 2 -\fBinfo\fP: Things are proceeding as expected. -.IP \(bu 2 -\fBwarning\fP: Something does not appear to be correct. -.IP \(bu 2 -\fBerror\fP: Something went wrong (but Cascade can recover). -.IP \(bu 2 -\fBcritical\fP: Something went wrong and Cascade can\(aqt function at all. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B log\-target = { type = \(dqfile\(dq, path = \(dq/dev/stdout\(dq } -.UNINDENT -.INDENT 0.0 -.TP -.B log\-target = { type = \(dqsyslog\(dq } -The location the daemon writes logs to. -.INDENT 7.0 -.IP \(bu 2 -type \fBfile\fP: Logs are appended line\-by\-line to the specified file path. -.sp -It can be set to \fB/dev/stdout\fP or \fB/dev/stderr\fP for standard output and -error, respectively. If it is a terminal, ANSI escape codes may be used -to style the output. -.IP \(bu 2 -type \fBsyslog\fP: Logs are written to the UNIX syslog. -.sp -This option is only supported on UNIX systems. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B daemonize = false -Whether to apply internal daemonization. -.sp -\(aqDaemonization\(aq involves several steps: -.INDENT 7.0 -.IP \(bu 2 -Forking the process to disconnect it from the terminal -.IP \(bu 2 -Tracking the new process\(aq PID (by storing it in a file) -.IP \(bu 2 -Binding privileged ports (below 1024) as configured -.IP \(bu 2 -Dropping administrator privileges -.UNINDENT -.sp -These features may be provided by an external system service manager, such -as systemd. If no such service manager is being used, Cascade can provide -such features itself, by setting this option to \fBtrue\fP\&. This will also -enable the \fBpid\-file\fP and \fBidentity\fP settings (although they remain -optional). -.UNINDENT -.INDENT 0.0 -.TP -.B pid\-file = \(dq/var/run/cascade.pid\(dq -The path to a PID file to maintain, if any. -.sp -If specified, Cascade will maintain a PID file at this location; it will be -a simple plain\-text file containing the PID number of the daemon process. -This option is only supported if \fBdaemonize\fP is true. -.UNINDENT -.INDENT 0.0 -.TP -.B identity = \(dqcascade:cascade\(dq -An identity (user and group) to assume after startup. -.sp -Cascade will assume the specified identity after initialization. Note that -this will fail if Cascade is started without administrator privileges. This -option is only supported if \fBdaemonize\fP is \fBtrue\fP\&. -.sp -The identity can be specified as \fB:\fP or just \fB\fP; in the -latter case, the identically named group will be used. Numeric IDs are not -supported; only names can be used. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -When using systemd, you should rely on its \(aqUser=\(aq and \(aqGroup=\(aq -options instead. See <\X'tty: link https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User='\fI\%https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User=\fP\X'tty: link'>. -.UNINDENT -.UNINDENT -.UNINDENT -.SH HOW CASCADE IS CONTROLLED. -.sp -The \fB[remote\-control]\fP section. -.INDENT 0.0 -.TP -.B servers = [\(dq127.0.0.1:2060\(dq, \(dq[::1]:2060\(dq] -Where to serve Cascade\(aqs HTTP API. -.sp -The HTTP API can be used to monitor and control Cascade. The addresses -refer to TCP sockets that will be listened on for HTTP requests. At the -moment, security mechanisms like TLS are not supported. -.sp -These sockets may be bound by systemd and passed into Cascade. If systemd -does not provide them, Cascade will bind them itself (and will do so before -dropping privileges, if that is enabled). -.UNINDENT -.SH HOW ZONES ARE LOADED. -.sp -The \fB[loader]\fP section. -.INDENT 0.0 -.TP -.B notify\-listeners = [\(dq127.0.0.1:2050\(dq, \(dq[::1]:2050\(dq] -Where to listen for zone change notifications. -.sp -A DNS server will be bound to these addresses. If a DNS NOTIFY message for -a known zone is received there, the zone will be reloaded appropriately. -.sp -Unless explicitly specified (e.g. \fBudp://localhost:2050\fP), each address will -be served over UDP and TCP. An empty array will disable listening entirely. -.sp -These sockets may be bound by systemd and passed into Cascade. If systemd -does not provide them, Cascade will bind them itself (and will do so before -dropping privileges, if that is enabled). -.UNINDENT -.SH HOW LOADED ZONES ARE REVIEWED. -.sp -The \fB[loader.review]\fP section. -.INDENT 0.0 -.TP -.B servers = [\(dq127.0.0.1:2051\(dq, \(dq[::1]:2051\(dq] -Where to serve loaded zones for review. -.sp -A DNS server will be bound to these addresses, and will serve the contents -of all loaded zones. This can be used to verify the consistency of these -zones. -.sp -Unless explicitly specified (e.g. \fBudp://localhost:2051\fP), each address will -be served over UDP and TCP. An empty array will disable serving entirely. -.sp -These sockets may be bound by systemd and passed into Cascade. If systemd -does not provide them, Cascade will bind them itself (and will do so before -dropping privileges, if that is enabled). -.UNINDENT -.SH HOW ZONES ARE SIGNED. -.sp -The \fB[signer]\fP section. (This only includes the \fB[signer.review]\fP section -below, for now). -.SH HOW SIGNED ZONES ARE REVIEWED. -.sp -The \fB[signer.review]\fP section. -.INDENT 0.0 -.TP -.B servers = [\(dq127.0.0.1:2052\(dq, \(dq[::1]:2052\(dq] -Where to serve signed zones for review. -.sp -A DNS server will be bound to these addresses, and will serve the contents -of all signed (but not necessarily published) zones. This can be used to -check the correctness of the signer. -.sp -Unless explicitly specified (e.g. \fBudp://localhost:2052\fP), each address will -be served over UDP and TCP. An empty array will disable serving entirely. -.sp -These sockets may be bound by systemd and passed into Cascade. If systemd -does not provide them, Cascade will bind them itself (and will do so before -dropping privileges, if that is enabled). -.UNINDENT -.SH DNSSEC KEY MANAGEMENT. -.sp -The \fB[key\-manager]\fP section. (Currently without options) -.SH HOW ZONES ARE PUBLISHED. -.sp -The \fB[server]\fP section. -.INDENT 0.0 -.TP -.B servers = [\(dq127.0.0.1:2053\(dq, \(dq[::1]:2053\(dq] -Where to serve published zones. -.sp -A DNS server will be bound to these addresses, and will serve the contents -of all published zones. This is the final output from Cascade. -.sp -Unless explicitly specified (e.g. \fBudp://localhost:2053\fP), each address will -be served over UDP and TCP. At least one address must be specified. -.sp -These sockets may be bound by systemd and passed into Cascade. If systemd -does not provide them, Cascade will bind them itself (and will do so before -dropping privileges, if that is enabled). -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2025–2025, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/cascaded-policy.toml.1 b/doc/manual/build/man/cascaded-policy.toml.1 deleted file mode 100644 index 8caaea9c..00000000 --- a/doc/manual/build/man/cascaded-policy.toml.1 +++ /dev/null @@ -1,618 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "CASCADED-POLICY.TOML" "1" "Oct 05, 2025" "0.1.0-rc1" "Cascade" -.SH NAME -cascaded-policy.toml \- Cascade policy file format -.sp -A policy is a collection of settings that apply to a group of zones known to -Cascade. Policy controls how Cascade operates on those zones, e.g. how they -are signed. This page describes all possible settings and their defaults. You -can generate a template with these default values using \fBcascade template -policy\fP\&. -.sp -Policy files are managed by the user, and are stored at a configurable path -(by default, \fB/etc/cascade/policies\fP). You can add, modify, and remove -policy files, then update Cascade with \fBcascade policy reload\fP\&. Note that: -.INDENT 0.0 -.IP \(bu 2 -Cascade maintains an internal copy of all policies, and will use this until -\fBcascade policy reload\fP is used. If reloading fails, Cascade will continue -to use its existing internal copy. It won\(aqt reload policies if it restarts. -.IP \(bu 2 -Policies cannot be removed if they are attached to zones; those zones need -to be deleted or shifted to a different policy first. If you remove a used -policy and reload policies in Cascade, it will fail and continue to use its -internal copy of the policy. -.UNINDENT -.SH EXAMPLE -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -version = \(dqv1\(dq - -[loader] -[loader.review] -required = false - -[key\-manager] -ksk.validity = \(dq31536000\(dq -zsk.validity = \(dq2592000\(dq -csk.validity = \(dq31536000\(dq -ksk.auto\-start = true -zsk.auto\-start = true -csk.auto\-start = true -algorithm.auto\-start = true -ksk.auto\-report = true -zsk.auto\-report = true -csk.auto\-report = true -algorithm.auto\-report = true -ksk.auto\-expire = true -zsk.auto\-expire = true -csk.auto\-expire = true -algorithm.auto\-expire = true -ksk.auto\-done = true -zsk.auto\-done = true -csk.auto\-done = true -algorithm.auto\-done = true -ds\-algorithm = \(dqSHA256\(dq -auto\-remove = true - -[key\-manager.records] -ttl = 3600 -dnskey.signature\-inception\-offset = 86400 -cds.signature\-inception\-offset = 86400 -dnskey.signature\-lifetime = 1209600 -cds.signature\-lifetime = 1209600 -dnskey.signature\-remain\-time = 604800 -cds.signature\-remain\-time = 604800 - -[key\-manager.generation] -use\-csk = false -algorithm = \(dqECDSAP256SHA256\(dq - -[signer] -serial\-policy = \(dqdate\-counter\(dq -signature\-inception\-offset = 86400 -signature\-lifetime = 1209600 -signature\-remain\-time = 604800 - -[signer.denial] -type = \(dqnsec\(dq - -[signer.review] -required = false - -[server.outbound] -send\-notify\-to = [] -.EE -.UNINDENT -.UNINDENT -.SH GLOBAL OPTIONS -.INDENT 0.0 -.TP -.B version = \(dqv1\(dq -The policy file version. (REQUIRED) -.sp -This is the only required option. All other settings, and their defaults, -are associated with this version number. More versions may be added in the -future and Cascade may drop support for older versions over time. -.INDENT 7.0 -.IP \(bu 2 -\fBv1\fP: This format. -.UNINDENT -.UNINDENT -.SH HOW ZONES ARE LOADED. -.sp -The \fB[loader]\fP section. -.INDENT 0.0 -.TP -.B [loader.review] -How loaded zones are reviewed. -.sp -Review offers an opportunity to perform external checks on the zone contents -loaded by Cascade. -.UNINDENT -.INDENT 0.0 -.TP -.B required = false -Whether review is required. -.sp -If this is \fBtrue\fP, a loaded version of a zone will not be signed or -published until it is approved. If it is \fBfalse\fP, loaded zones will be -signed immediately. At the moment, the review hook will only be run if this -is set to true. -.UNINDENT -.INDENT 0.0 -.TP -.B cmd\-hook = \(dq\(dq -A hook for reviewing a loaded zone. This is a path to an executable. -.sp -This command string will be executed in the user\(aqs shell when a new version -of a zone is loaded. At the moment, it will only be run if \fBrequired\fP is -true. -.sp -It will receive the following information via environment variables: -.INDENT 7.0 -.IP \(bu 2 -\fBCASCADE_ZONE\fP: The name of the zone, formatted without a trailing dot. -.IP \(bu 2 -\fBCASCADE_SERIAL\fP: The serial number of the zone (decimal integer). -.IP \(bu 2 -\fBCASCADE_TOKEN\fP: A UUID associated with this review, for approving or -rejecting this version of the zone. -.IP \(bu 2 -\fBCASCADE_SERVER\fP: The TCP/UDP port where Cascade is serving the zone for -review, formatted \fB:\fP\&. -.IP \(bu 2 -\fBCASCADE_CONTROL\fP: The address of Cascade\(aqs HTTP API server, for sending -approvals and rejections. -.UNINDENT -.sp -The command will be called from an unspecified directory, and it must be -accessible to Cascade (i.e. after it has dropped privileges). -.sp -To approve the zone contents, send an HTTP GET request to -\fBhttp://$CASCADE_CONTROL/approve/$CASCADE_TOKEN?zone=$CASCADE_ZONE&serial=$CASCADE_SERIAL\fP\&. -\fBapprove\fP can be replaced by \fBreject\fP to reject the zone. If the command -exits without approving or rejecting the zone, Cascade will wait for the -user to approve it manually. -.UNINDENT -.SH DNSSEC KEY MANAGEMENT. -.sp -The \fB[key\-manager]\fP section. -.INDENT 0.0 -.TP -.B ksk.validity = \(dq31536000\(dq -.UNINDENT -.INDENT 0.0 -.TP -.B zsk.validity = \(dq2592000\(dq -.UNINDENT -.INDENT 0.0 -.TP -.B csk.validity = \(dq31536000\(dq -How long keys are considered valid for. -.sp -If a key has been used for longer than this time, it is considered expired, -and (if enabled) it will automatically be rolled over to a new key. Even if -automatic rollovers are not enabled, the key will be reported as expired. -This is a soft condition \-\- DNSSEC does not have a concept of key expiry, -and it will not break DNSSEC validation, but it is usually important to the -security of the zone. -.sp -Independent validity times are set for KSKs, ZSKs, and CSKs. An integer -value will be interpreted as seconds; \fBforever\fP means keys never expire. -.UNINDENT -.INDENT 0.0 -.TP -.B ksk.auto\-start = true -.UNINDENT -.INDENT 0.0 -.TP -.B zsk.auto\-start = true -.UNINDENT -.INDENT 0.0 -.TP -.B csk.auto\-start = true -.UNINDENT -.INDENT 0.0 -.TP -.B algorithm.auto\-start = true -Whether to automatically start key rollovers. -.sp -If this is enabled, Cascade will automatically start rolling over keys when -they expire (as per \fBvalidity\fP). When using this setting, \fBvalidity\fP must -not be set to \fBforever\fP\&. -.sp -The first step in a rollover will be to generate new keys to replace old -ones. By disabling this setting, the user can manually control how new keys -are generated, and when rollovers happen. -.UNINDENT -.INDENT 0.0 -.TP -.B ksk.auto\-report = true -.UNINDENT -.INDENT 0.0 -.TP -.B zsk.auto\-report = true -.UNINDENT -.INDENT 0.0 -.TP -.B csk.auto\-report = true -.UNINDENT -.INDENT 0.0 -.TP -.B algorithm.auto\-report = true -Whether to automatically check for record propagation. -.sp -If this is enabled, Cascade will automatically contact public DNS servers to -detect when new records (e.g. DNSKEY) are visible globally. It is necessary -to wait until some records are visible globally to progress key rollovers. If -this is disabled, the user will have to inform Cascade when these conditions -are reached manually. -.sp -For this setting to work, Cascade must have network access to the zone\(aqs -public nameservers and the parent zone\(aqs public nameservers. -.UNINDENT -.INDENT 0.0 -.TP -.B ksk.auto\-expire = true -.UNINDENT -.INDENT 0.0 -.TP -.B zsk.auto\-expire = true -.UNINDENT -.INDENT 0.0 -.TP -.B csk.auto\-expire = true -.UNINDENT -.INDENT 0.0 -.TP -.B algorithm.auto\-expire = true -Whether to automatically wait for cache expiry. -.sp -If this is enabled, Cascade will automatically progress through key rollover -steps that need to wait for downstream users\(aq DNS caches to expire. It will -estimate the right amount of time to wait based on record TTLs. -.UNINDENT -.INDENT 0.0 -.TP -.B ksk.auto\-done = true -.UNINDENT -.INDENT 0.0 -.TP -.B zsk.auto\-done = true -.UNINDENT -.INDENT 0.0 -.TP -.B csk.auto\-done = true -.UNINDENT -.INDENT 0.0 -.TP -.B algorithm.auto\-done = true -Whether to automatically check for rollover completion. -.sp -Like \fBauto\-report\fP, if this setting is enabled, Cascade will automatically -contact public DNS servers to detect when new records are visible globally. -\fBauto\-done\fP specifically affects automatic checks for the last step of key -rollovers, and is independent from \fBauto\-report\fP\&. -.sp -For this setting to work, Cascade must have network access to the zone\(aqs -public nameservers and the parent zone\(aqs public nameservers. -.UNINDENT -.INDENT 0.0 -.TP -.B ds\-algorithm = \(dqSHA256\(dq -The hash algorithm used by the parent zones\(aq DS records. -.sp -Supported options: -.INDENT 7.0 -.IP \(bu 2 -\fBSHA256\fP: SHA\-256. -.IP \(bu 2 -\fBSHA384\fP: SHA\-384. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B auto\-remove = true -Whether to automatically remove expired keys. -.sp -If this is set, expired keys will be removed automatically (by deleting the -files for on\-disk keys or removing it from the HSM). -.UNINDENT -.SH THE MANAGEMENT OF DNS RECORDS BY THE KEY MANAGER. -.sp -The \fB[key\-manager.records]\fP section. -.sp -The key manager generates and signs several records (DNSKEY and CDS). This -section controls its behaviour towards them. -.INDENT 0.0 -.TP -.B ttl = 3600 -The TTL for the generated records. -.UNINDENT -.INDENT 0.0 -.TP -.B dnskey.signature\-inception\-offset = 86400 -.UNINDENT -.INDENT 0.0 -.TP -.B cds.signature\-inception\-offset = 86400 -The offset for generated signature inceptions. -.sp -Record signatures have a fixed inception time, from when they are considered -valid. An imprecise computer clock could cause signatures to be considered -invalid, because their inception point appears to be some time in the future. -To prevent such cases, this setting allows the inception time to be offset -into the past. -.sp -Independent offsets can be set for each type of record. An integer value is -intepreted as seconds; inception times will be calculated as \fBnow \- offset\fP -at the time of signing. -.UNINDENT -.INDENT 0.0 -.TP -.B dnskey.signature\-lifetime = 1209600 -.UNINDENT -.INDENT 0.0 -.TP -.B cds.signature\-lifetime = 1209600 -The lifetime of generated signatures. -.sp -Record signatures have a fixed lifetime, after which they are considered -invalid. To keep the zone valid, the signatures should be regenerated before -they expire; see \fBsignature\-remain\-time\fP to control regeneration time. -.sp -Independent lifetimes can be set for each type of record. An integer value is -interpreted as seconds. -.UNINDENT -.INDENT 0.0 -.TP -.B dnskey.signature\-remain\-time = 604800 -.UNINDENT -.INDENT 0.0 -.TP -.B cds.signature\-remain\-time = 604800 -The amount of time remaining before expiry when signatures will be -regenerated. -.sp -In order to prevent a zone\(aqs signatures from appearing invalid, they -have to be regenerated before they expire. That hard limit is set by -\fBsignature\-lifetime\fP above. This setting controls how long before expiry -signatures will be regenerated; it must be less than the \fBsignature\-lifetime\fP -setting. -.sp -Independent waiting times can be set for each type of record. An integer -value is interpreted as seconds. -.UNINDENT -.SH HOW KEYS ARE GENERATED. -.sp -The \fB[key\-manager.generation]\fP section. -.INDENT 0.0 -.TP -.B hsm\-server\-id = \(dq\(dq -The HSM server to use. -.sp -If this is set, the named HSM server (which must be configured via \(aqcascade -hsm add\(aq) will be used for generating new DNSSEC keys. -.sp -See \X'tty: link https://cascade.docs.nlnetlabs.nl/en/latest/hsms.html'\fI\%https://cascade.docs.nlnetlabs.nl/en/latest/hsms.html\fP\X'tty: link' for more -information. -.UNINDENT -.INDENT 0.0 -.TP -.B use\-csk = false -Whether to generate CSKs, instead of separate ZSKs and KSKs. -.sp -A CSK (Combined Signing Key) takes the role of both ZSK and KSK for a zone, -unlike the standard practice of using separate keys for ZSK and KSK. This -setting does not affect how DNSSEC validation is performed, only procedures -for key rollovers. -.sp -If this is enabled, Cascade will generate CSKs for the associated zones. -.UNINDENT -.INDENT 0.0 -.TP -.B algorithm = \(dqECDSAP256SHA256\(dq -The cryptographic algorithm (and parameters) for generated keys. -.sp -DNSSEC supports various cryptographic algorithms for signatures; one must be -selected, and for some algorithms, additional parameters are also necessary. -The same algorithm and parameters will be applied to the ZSK and KSK. -.INDENT 7.0 -.IP \(bu 2 -\fBRSASHA256[:]\fP, algorithm 8, with a public key size of -\fB\fP (default 2048) bits. -.IP \(bu 2 -\fBRSASHA512[:]\fP, algorithm 10, with a public key size of -\fB\fP (default 2048) bits. -.IP \(bu 2 -\fBECDSAP256SHA256\fP, algorithm 13. -.IP \(bu 2 -\fBECDSAP384SHA384\fP, algorithm 14. -.IP \(bu 2 -\fBED25519\fP, algorithm 15. -.IP \(bu 2 -\fBED448\fP, algorithm 16. -.UNINDENT -.sp -There are additional algorithms, but many are now considered insecure, and -it is recommended or mandated to avoid them. In addition, RSA keys smaller -than 2048 bits are not recommended. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -At the moment, only RSASHA256 and ECDSAP256SHA256 work with HSMs. -Other algorithms cannot be used with HSMs, and will cause generation -failures. -.UNINDENT -.UNINDENT -.UNINDENT -.SH HOW ZONES ARE SIGNED. -.sp -The \fB[signer]\fP section. -.sp -Note that certain records (e.g. DNSKEY and CDS records at the apex of the -zone) are signed by the key manager, rather than the zone signer; see the -\fB[key\-manager.records]\fP section for configuring the signing of those records. -.INDENT 0.0 -.TP -.B serial\-policy = \(dqdate\-counter\(dq -How SOA serial numbers are generated for signed zones. -.sp -Supported options: -.INDENT 7.0 -.IP \(bu 2 -\fBkeep\fP: use the same serial number as the unsigned zone. -.IP \(bu 2 -\fBcounter\fP: increment the serial number every time. -.IP \(bu 2 -\fBunixtime\fP: use the current Unix time, in seconds. -.IP \(bu 2 -\fBdate\-counter\fP: format the number as \fB
\fP in decimal. -\fB\fP is a simple counter to allow up to 100 versions per day. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B signature\-inception\-offset = 86400 -The offset for generated signature inceptions. -.sp -Record signatures have a fixed inception time, from when they are considered -valid. An imprecise computer clock could cause signatures to be considered -invalid, because their inception point appears to be some time in the -future. To prevent such cases, this setting allows the inception time to be -offset into the past. -.sp -An integer value is interpreted as seconds; inception times will be -calculated as \fBnow \- offset\fP at the time of signing. -.UNINDENT -.INDENT 0.0 -.TP -.B signature\-lifetime = 1209600 -The lifetime of generated signatures. -.sp -Record signatures have a fixed lifetime, after which they are considered -invalid. To keep the zone valid, the signatures should be regenerated before -they expire; see \fBsignature\-remain\-time\fP to control regeneration time. -.sp -An integer value is interpreted as seconds. -.UNINDENT -.INDENT 0.0 -.TP -.B signature\-remain\-time = 604800 -The amount of time remaining before expiry when signatures will be -regenerated. -.sp -In order to prevent a zone\(aqs signatures from appearing invalid, they -have to be regenerated before they expire. That hard limit is set by -\fBsignature\-lifetime\fP above. This setting controls how long before expiry -signatures will be regenerated; it must be less than the \fBsignature\-lifetime\fP -setting. -.sp -An integer value is interpreted as seconds. -.UNINDENT -.SH HOW DENIAL-OF-EXISTENCE RECORDS ARE GENERATED. -.sp -The \fB[signer.denial]\fP section. -.INDENT 0.0 -.TP -.B type = \(dqnsec\(dq -The type of denial\-of\-existence records to generate. -.sp -Supported options: -\- \fBnsec\fP: Use NSEC records (RFC 4034). -\- \fBnsec3\fP: Use NSEC3 records (RFC 5155). -.UNINDENT -.INDENT 0.0 -.TP -.B opt\-out = false -(Only set when using NSEC3) -.sp -Whether to skip NSEC3 records for unsigned delegations. -.sp -This enables the NSEC3 Opt\-Out flag, and skips delegations to unsigned zones -when generating NSEC3 records. This affects the security of the zone, so be -careful if you wish to enable it. -.UNINDENT -.SH HOW SIGNED ZONES ARE REVIEWED. -.sp -The \fB[signer.review]\fP section. -.INDENT 0.0 -.TP -.B required = false -Whether review is required. -.sp -If this is \fBtrue\fP, a signed version of a zone will not be published until it -is approved. If it is \fBfalse\fP, signed zones will be published immediately. -At the moment, the review hook will only be run if this is set to true. -.UNINDENT -.INDENT 0.0 -.TP -.B cmd\-hook = \(dq\(dq -A hook for reviewing a signed zone. This is a path to an executable. -.sp -This command string will be executed in the user\(aqs shell when a new version of -a zone is signed. At the moment, it will only be run if \fBrequired\fP is true. -.sp -It will receive the following information via environment variables: -.INDENT 7.0 -.IP \(bu 2 -\fBCASCADE_ZONE\fP: The name of the zone, formatted without a trailing dot. -.IP \(bu 2 -\fBCASCADE_SERIAL\fP: The serial number of the signed zone (decimal integer). -.IP \(bu 2 -\fBCASCADE_UNSIGNED_SERIAL\fP: The serial number of the unsigned zone from which -the signed zone was generated (decimal integer). -.IP \(bu 2 -\fBCASCADE_TOKEN\fP: A UUID associated with this review, for approving or -rejecting this version of the zone. -.IP \(bu 2 -\fBCASCADE_SERVER\fP: The TCP/UDP port where Cascade is serving the zone for -review, formatted \fB:\fP\&. -.IP \(bu 2 -\fBCASCADE_UNSIGNED_SERVER\fP: The TCP/UDP port where Cascade is serving the -unsigned version of the zone for review, formatted \fB:\fP\&. -.IP \(bu 2 -\fBCASCADE_CONTROL\fP: The address of Cascade\(aqs HTTP API server, for sending -approvals and rejections. -.UNINDENT -.sp -The command will be called from an unspecified directory, and it must be -accessible to Cascade (i.e. after it has dropped privileges). -.sp -To approve the zone contents, send an HTTP GET request to -\fBhttp://$CASCADE_CONTROL/approve/$CASCADE_TOKEN?zone=$CASCADE_ZONE&serial=$CASCADE_SERIAL\fP\&. -\fBapprove\fP can be replaced by \fBreject\fP to reject the zone. If the -command exits without approving or rejecting the zone, Cascade will wait for -the user to approve it manually. -.UNINDENT -.SH HOW PUBLISHED ZONES ARE SERVED. -.sp -The \fB[server.outbound]\fP section. -.INDENT 0.0 -.TP -.B send\-notify\-to = [] -The set of nameservers to which NOTIFY messages should be sent. -.sp -If empty, no NOTIFY messages will be sent. -.sp -A collection of \fBIP:[port]\fP, defaulting to port 53 when not specified, e.g.: -\fBsend\-notify\-to = [\(dq[::1]:53\(dq]\fP -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2025–2025, NLnet Labs -.\" Generated by docutils manpage writer. -. From 9dd9ac1b3ab6be274199a7060be2686628d46ddf Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Fri, 17 Oct 2025 13:02:00 +0200 Subject: [PATCH 6/7] Attempt to overcome inability to create /etc/cascade/policies when started by systemd. Using ReadWritePaths didn't help so try pre-creating the directory instead. --- pkg/debian/postinst | 2 ++ pkg/debian/postrm | 2 +- pkg/rpm/rpmlintrc | 1 + pkg/rpm/scriptlets.toml | 3 +++ 4 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 pkg/rpm/rpmlintrc diff --git a/pkg/debian/postinst b/pkg/debian/postinst index 1aedffd6..906294fb 100755 --- a/pkg/debian/postinst +++ b/pkg/debian/postinst @@ -10,6 +10,8 @@ create_user() { case "$1" in configure) create_user + mkdir -p /etc/cascade/policies + chown -R ${USER_ID}: /etc/cascade ;; esac diff --git a/pkg/debian/postrm b/pkg/debian/postrm index 1dce1745..ae245cf0 100755 --- a/pkg/debian/postrm +++ b/pkg/debian/postrm @@ -11,7 +11,7 @@ purge) rm ${CONFIG_FILE_PATH} fi - # TODO: Remove the user account and home dir? + # TODO: Remove the user account and home dir and /etc/cascade/policies? ;; esac diff --git a/pkg/rpm/rpmlintrc b/pkg/rpm/rpmlintrc new file mode 100644 index 00000000..1ed344c0 --- /dev/null +++ b/pkg/rpm/rpmlintrc @@ -0,0 +1 @@ +addFilter('bad-manual-page-folder') diff --git a/pkg/rpm/scriptlets.toml b/pkg/rpm/scriptlets.toml index 7ff1e66b..b6f95de2 100644 --- a/pkg/rpm/scriptlets.toml +++ b/pkg/rpm/scriptlets.toml @@ -17,6 +17,9 @@ if [ $1 -eq 1 ] ; then useradd --system --user-group ${USER_ID} --home-dir /var/lib/${USER_ID} --create-home fi + mkdir -p /etc/cascade/policies + chown -R ${USER_ID}: /etc/cascade + # Run commands equivalent to what the RPM systemd macros would do systemd_post cascaded.service systemd_triggers From cc35fc4424748dc2d918c9d9fcba2e5611035a9b Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Fri, 17 Oct 2025 13:15:31 +0200 Subject: [PATCH 7/7] Maybe changing ownership isn't needed and is a step too far. --- pkg/debian/postinst | 1 - pkg/rpm/scriptlets.toml | 1 - 2 files changed, 2 deletions(-) diff --git a/pkg/debian/postinst b/pkg/debian/postinst index 906294fb..2d2ca533 100755 --- a/pkg/debian/postinst +++ b/pkg/debian/postinst @@ -11,7 +11,6 @@ case "$1" in configure) create_user mkdir -p /etc/cascade/policies - chown -R ${USER_ID}: /etc/cascade ;; esac diff --git a/pkg/rpm/scriptlets.toml b/pkg/rpm/scriptlets.toml index b6f95de2..ce07b4df 100644 --- a/pkg/rpm/scriptlets.toml +++ b/pkg/rpm/scriptlets.toml @@ -18,7 +18,6 @@ if [ $1 -eq 1 ] ; then fi mkdir -p /etc/cascade/policies - chown -R ${USER_ID}: /etc/cascade # Run commands equivalent to what the RPM systemd macros would do systemd_post cascaded.service