diff --git a/.gitignore b/.gitignore index f2ea745..9e310e9 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,7 @@ debug/ target/ # Currently generated man pages are checked in. -#/doc/manual/build/ +/doc/manual/build/ /doc/manual/build/doctrees /doc/manual/build/man/_static @@ -11,3 +11,6 @@ target/ # MSVC Windows builds of rustc generate these, which store debugging information *.pdb +# Added by goreleaser init: +dist/ +.intentionally-empty-file.o diff --git a/.goreleaser.yaml b/.goreleaser.yaml new file mode 100644 index 0000000..a089979 --- /dev/null +++ b/.goreleaser.yaml @@ -0,0 +1,437 @@ +# This is an example .goreleaser.yml file with some sensible defaults. +# Make sure to check the documentation at https://goreleaser.com + +# The lines below are called `modelines`. See `:help modeline` +# Feel free to remove those if you don't want/need to use them. +# yaml-language-server: $schema=https://goreleaser.com/static/schema.json +# vim: set ts=2 sw=2 tw=0 fo=cnqoj + +version: 2 + +before: + hooks: + # if you don't do these things before calling goreleaser, it might be a + # good idea to do them here: + - rustup default stable + - cargo install --locked cargo-zigbuild + - cargo fetch --locked + - ./pkg/generate-man-pages.sh + +# https://goreleaser.com/customization/builds/builders/rust/ +builds: + - builder: rust + id: dnst-cross + flags: + - --release + - --features=static-openssl + targets: + - aarch64-unknown-linux-musl + # - arm-unknown-linux-gnueabihf + # - armv7-unknown-linux-gnueabihf + - arm-unknown-linux-musleabihf + - armv7-unknown-linux-musleabihf + command: zigbuild + - builder: rust + # Build dnst for x86_64 with dynamic openssl + id: dnst + flags: + - --release + targets: + # OpenSSL requires minimum glibc 2.38 + - x86_64-unknown-linux-gnu.2.38 + command: zigbuild + env: + - OPENSSL_LIB_DIR=/usr/lib + - OPENSSL_INCLUDE_DIR=/usr/include + +# https://goreleaser.com/customization/package/archives/ +archives: + - formats: [tar.gz] + name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_\ + {{ .Arch }}{{ if not (eq .Arm \"6\") }}\ + {{ with .Arm }}v{{ . }}{{ end }}\ + {{ end }}{{ with .Mips }}_\ + {{ . }}{{ end }}{{ if not (eq .Amd64 \"v1\") }}{{ .Amd64 }}{{ end }}" + # use zip for windows archives + format_overrides: + - goos: windows + formats: [zip] + files: + - README.md + - LICENSE + - Changelog.md + - src: doc/manual/build/man/* + dst: docs + strip_parent: true + +# https://goreleaser.com/customization/package/nfpm/ +nfpms: + # note that this is an array of nfpm configs + - id: default + # file_name_template: "{{ .ConventionalFileName }}" + file_name_template: >- + {{- trimsuffix .ConventionalFileName .ConventionalExtension -}} + {{- if and (eq .Arm "6") (eq .ConventionalExtension ".deb") }}6{{ end -}} + {{- if not (eq .Amd64 "v1")}}{{ .Amd64 }}{{ end -}} + {{- .ConventionalExtension -}} + + vendor: NLnet Labs + homepage: https://nlnetlabs.nl/projects/domain/dnst/ + maintainer: NLnet Labs + description: Rust reimplementation of important ldns programs. + license: BSD-3-Clause + + # Formats to be generated. + formats: + - apk + - deb + - rpm + - archlinux + + # dependencies: + # provides: + # recommends: + # suggests: + # conflicts: + # replaces: + + # Section. + section: net + + # Priority. + priority: optional + + # Contents to add to the package. + # GoReleaser will automatically add the binaries. + contents: + - src: README.md + dst: /usr/share/doc/dnst/ + file_info: + mode: 644 + - src: doc/manual/build/man/dnst.1 + dst: /usr/share/man/man1/dnst.1 + file_info: + mode: 644 + - src: doc/manual/build/man/dnst-key2ds.1 + dst: /usr/share/man/man1/dnst-key2ds.1 + file_info: + mode: 644 + - src: doc/manual/build/man/dnst-keygen.1 + dst: /usr/share/man/man1/dnst-keygen.1 + file_info: + mode: 644 + - src: doc/manual/build/man/dnst-keyset.1 + dst: /usr/share/man/man1/dnst-keyset.1 + file_info: + mode: 644 + - src: doc/manual/build/man/dnst-notify.1 + dst: /usr/share/man/man1/dnst-notify.1 + file_info: + mode: 644 + - src: doc/manual/build/man/dnst-nsec3-hash.1 + dst: /usr/share/man/man1/dnst-nsec3-hash.1 + file_info: + mode: 644 + - src: doc/manual/build/man/dnst-signzone.1 + dst: /usr/share/man/man1/dnst-signzone.1 + file_info: + mode: 644 + - src: doc/manual/build/man/dnst-update.1 + dst: /usr/share/man/man1/dnst-update.1 + file_info: + mode: 644 + + # Date to be used as mtime for the package itself, and its internal files. + # You may also want to set the mtime on its contents. + mtime: "{{ .CommitDate }}" + + # All fields above marked as `overridable` can be overridden for a given + # package format in this section. + overrides: + # The dependencies override can for example be used to provide version + # constraints for dependencies where different package formats use + # different versions or for dependencies that are named differently. + deb: + dependencies: + - libc6 (>= 2.38) + - libssl3t64 (>= 3.0.0) + # ... + rpm: + dependencies: + - glibc >= 2.38 + - openssl-libs >= 3.0.0 + apk: + dependencies: + - gcompat + - openssl + archlinux: + dependencies: + - glibc + - openssl + + # Custom configuration applied only to the Deb packager. + deb: + # Lintian overrides + # lintian_overrides: + # - statically-linked-binary + # - changelog-file-missing-in-native-package + + # Additional fields for the control file. Empty fields are ignored. + # This will expand any env vars you set in the field values, e.g. Vcs-Browser: ${CI_PROJECT_URL} + fields: + # Bugs: https://github.com/goreleaser/nfpm/issues + Bugs: https://github.com/NLnetLabs/dnst/issues + + archlinux: + packager: "NLnet Labs " + + # Create ldns replacement package + - id: dnst-ldnsutils + + # Makes a meta package - an empty package that contains only supporting + # files and dependencies. + # When set to `true`, the `builds` option is ignored. + meta: true + + package_name: dnst-ldnsutils + # file_name_template: "{{ .ConventionalFileName }}" + file_name_template: >- + {{- trimsuffix .ConventionalFileName .ConventionalExtension -}} + {{- if and (eq .Arm "6") (eq .ConventionalExtension ".deb") }}6{{ end -}} + {{- if not (eq .Amd64 "v1")}}{{ .Amd64 }}{{ end -}} + {{- .ConventionalExtension -}} + vendor: NLnet Labs + homepage: https://nlnetlabs.nl/projects/domain/dnst/ + maintainer: NLnet Labs + description: Rust reimplementation of important ldns programs (replacement package for ldns-utils). + license: BSD-3-Clause + + # Formats to be generated. + formats: + - apk + - deb + - rpm + - archlinux + + # Packages your package depends on. (overridable) + dependencies: + - dnst + + # Section. + section: net + + # Priority. + priority: optional + + # Contents to add to the package. + # GoReleaser will automatically add the binaries. + contents: + - src: doc/manual/build/man/ldns-key2ds.1 + dst: /usr/share/man/man1/ldns-key2ds.1 + file_info: + mode: 644 + - src: doc/manual/build/man/ldns-keygen.1 + dst: /usr/share/man/man1/ldns-keygen.1 + file_info: + mode: 644 + - src: doc/manual/build/man/ldns-notify.1 + dst: /usr/share/man/man1/ldns-notify.1 + file_info: + mode: 644 + - src: doc/manual/build/man/ldns-nsec3-hash.1 + dst: /usr/share/man/man1/ldns-nsec3-hash.1 + file_info: + mode: 644 + - src: doc/manual/build/man/ldns-signzone.1 + dst: /usr/share/man/man1/ldns-signzone.1 + file_info: + mode: 644 + - src: doc/manual/build/man/ldns-update.1 + dst: /usr/share/man/man1/ldns-update.1 + file_info: + mode: 644 + + - src: /usr/bin/dnst + dst: /usr/bin/ldns-keygen + type: "symlink" + - src: /usr/bin/dnst + dst: /usr/bin/ldns-key2ds + type: "symlink" + - src: /usr/bin/dnst + dst: /usr/bin/ldns-nsec3-hash + type: "symlink" + - src: /usr/bin/dnst + dst: /usr/bin/ldns-notify + type: "symlink" + - src: /usr/bin/dnst + dst: /usr/bin/ldns-signzone + type: "symlink" + - src: /usr/bin/dnst + dst: /usr/bin/ldns-update + type: "symlink" + + # Date to be used as mtime for the package itself, and its internal files. + # You may also want to set the mtime on its contents. + # + # + # Templates: allowed. + mtime: "{{ .CommitDate }}" + + # All fields above marked as `overridable` can be overridden for a given + # package format in this section. + overrides: + # The dependencies override can for example be used to provide version + # constraints for dependencies where different package formats use + # different versions or for dependencies that are named differently. + deb: + conflicts: + - ldnsutils + replaces: + - ldnsutils + rpm: + replaces: + - ldns-utils + apk: + replaces: + - ldns-tools + archlinux: + # unfortunately, the Arch maintainer published the example binaries + # and the library in a single package... + replaces: + - ldns + +# Example packages config for splitting out rpm packages from other packages +# nfpms: +# - id: default +# package_name: dnst +# file_name_template: >- +# {{- trimsuffix .ConventionalFileName .ConventionalExtension -}} +# {{- if and (eq .Arm "6") (eq .ConventionalExtension ".deb") }}6{{ end -}} +# {{- if not (eq .Amd64 "v1")}}{{ .Amd64 }}{{ end -}} +# {{- .ConventionalExtension -}} +# maintainer: "NLnet Labs " +# # maintainer: "NLnet Labs " +# formats: +# - apk +# - deb +# - archlinux +# - id: rpmpkg +# # Separating generating the RPM files out into its own nfpms build step, +# # as the signing step's "if" option is only available in the PRO version. +# # Signing packages by ID is free, therefore we split it here. +# package_name: dnst +# file_name_template: >- +# {{- trimsuffix .ConventionalFileName .ConventionalExtension -}} +# {{- if and (eq .Arm "6") (eq .ConventionalExtension ".deb") }}6{{ end -}} +# {{- if not (eq .Amd64 "v1")}}{{ .Amd64 }}{{ end -}} +# {{- .ConventionalExtension -}} +# maintainer: "NLnet Labs " +# # maintainer: "NLnet Labs " +# formats: +# - rpm + +# Signature schemes: +# - Debian/Ubuntu: signs a `Release` file containing checksums of all packages. +# While there is the option to provide signed packages where the pacakge +# file itself is signed, this option is disabled by default +# (in Debian at least). +# - RPM: adds a PGP signature to each rpm file itself (and uses a repo +# metadata file that is also signed itself) +# https://goreleaser.com/customization/sign/sign/ +signs: + - # Sign RPM files using rpmsign --addsign + id: rpmsign + # GoReleaser calls the `cmd` for each artifact to sign. So with + # `artifacts: package` for all generated packages. However, we only want + # to sign rpm packages. The convenient `if` selector that allows to match + # on package file names, is only available in GoReleaser Pro. One approach + # is to create two separate `nfpms` configs, one for generating rpms (and + # give it an id, e.g. rpmpkg) and one for the rest with default treatment + # (see the commented out nfpms section above). + # Another approach is to use a wrapper script that skips signing packages + # that aren't rpms. + cmd: ./pkg/rpmsign-only.sh + # args: ["--addsign", "--key-id", "0xA144323DEAACDF45", "${artifact}"] # releases key + args: ["--addsign", "--key-id", "0x7677576016265A20", "${artifact}"] # jannik's key + artifacts: package + + # IDs of the artifacts to sign. + # ids: + # - rpmpkg + + - # Sign the generated checksums file with gpg (the default) + # args: ["-u", "0xA144323DEAACDF45", "--output", "${signature}", "--detach-sign", "${artifact}"] + # args: ["-u", "0x7677576016265A20", "--output", "${signature}", "--detach-sign", "${artifact}"] + artifacts: checksum + +# https://goreleaser.com/customization/package/dockers_v2/ +dockers_v2: + - # IDs to filter the binaries/packages. + # + # Make sure to only include the IDs of binaries you want to `COPY` in your + # Dockerfile. + # + # If you include IDs that don't exist or are not available for the current + # architecture being built, the build of the image will be skipped. + ids: + - dnst + - dnst-cross + + images: + - "nlnetlabs/dnst" + + tags: + - "v{{ .Version }}" + - "{{ if .IsNightly }}nightly{{ end }}" + - "{{ if not .IsNightly }}latest{{ end }}" + + labels: + "org.opencontainers.image.description": "Rust reimplementation of important ldns programs." + "org.opencontainers.image.created": "{{.Date}}" + "org.opencontainers.image.name": "{{.ProjectName}}" + "org.opencontainers.image.revision": "{{.FullCommit}}" + "org.opencontainers.image.version": "{{.Version}}" + "org.opencontainers.image.source": "{{.GitURL}}" + + platforms: + - linux/amd64 + - linux/arm64 + # - linux/arm/v6 # debian doesn't have a v6 image + - linux/arm/v7 + +# https://goreleaser.com/customization/sign/docker_sign/ +# docker_signs: + +# Automatically create releases on GitHub/GitLab/Gitea (and potentially +# Forgejo as it was forked from Gitea). +# https://goreleaser.com/customization/publish/scm/ +# release: + +# Automatically upload generated packages to packages.nlnetlabs.nl +# https://goreleaser.com/customization/publish/blob/ +# blobs: +# - provider: s3 + +# Automatically announce new release on Discourse, ... +# https://goreleaser.com/customization/announce/ +# announce: + +# TODO: Make use of the Changelog.md when generating the GitHub/Codeberg +# release? +changelog: + # Set this to true if you don't want any changelog at all. + # + # Warning: this will also ignore any changelog files passed via `--release-notes`, + # and will render an empty changelog. + # + # This may result in an empty release notes on GitHub/GitLab/Gitea. + # + # Templates: allowed. + disable: true + +release: + footer: >- + + --- + + Released by [GoReleaser](https://github.com/goreleaser/goreleaser). diff --git a/Dockerfile b/Dockerfile index 0d6637e..947c544 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,148 +1,15 @@ -# This is a multi-stage Dockerfile, with a selectable first stage. With this -# approach we get: -# -# 1. Separation of dependencies needed to build our app in the 'build' stage -# and those needed to run our app in the 'final' stage, as we don't want -# the build-time dependencies to be included in the final Docker image. -# -# 2. Support for either building our app for the architecture of the base -# image using MODE=build (the default) or for externally built app -# binaries (e.g. cross-compiled) using MODE=copy. -# -# In total there are four stages consisting of: -# - Two possible first stages: 'build' or 'copy'. -# - A special 'source' stage which selects either 'build' or 'copy' as the -# source of binaries to be used by ... -# - The 'final' stage. +# As we're building on a glibc system, the binary depends on glibc symbols and +# libraries. Therefore, we need to use a glibc base image (not apline). +ARG BASE_IMG=debian:13-slim +FROM ${BASE_IMG} -### -### ARG DEFINITIONS ########################################################### -### - -# This section defines arguments that can be overriden on the command line -# when invoking `docker build` using the argument form: -# -# `--build-arg =`. - -# MODE -# ==== -# Supported values: build (default), copy -# -# By default this Dockerfile will build our app from sources. If the sources -# have already been (cross) compiled by some external process and you wish to -# use the resulting binaries from that process, then: -# -# 1. Create a directory on the host called 'dockerbin/$TARGETPLATFORM' -# containing the already compiled app binaries (where $TARGETPLATFORM -# is a special variable set by Docker BuiltKit). -# 2. Supply arguments `--build-arg MODE=copy` to `docker build`. -ARG MODE=build - - -# BASE_IMG -# ======== -# -# Only used when MODE=build. -ARG BASE_IMG=alpine:3.23 - - -# CARGO_ARGS -# ========== -# -# Only used when MODE=build. -# -# This ARG can be used to control the features enabled when compiling the app -# or other compilation settings as necessary. -ARG CARGO_ARGS - - -### -### BUILD STAGES ############################################################## -### - - -# ----------------------------------------------------------------------------- -# Docker stage: build -# ----------------------------------------------------------------------------- -# -# Builds our app binaries from sources. -FROM ${BASE_IMG} AS build -ARG CARGO_ARGS - -RUN apk add --no-cache openssl-dev rust cargo - -WORKDIR /tmp/build -COPY . . - -# `CARGO_HTTP_MULTIPLEXING` forces Cargo to use HTTP/1.1 without pipelining -# instead of HTTP/2 with multiplexing. This seems to help with various -# "spurious network error" warnings when Cargo attempts to fetch from crates.io -# when building this image on Docker Hub and GitHub Actions build machines. -# -# `cargo install` is used instead of `cargo build` because it places just the -# binaries we need into a predictable output directory. We can't control this -# with arguments to cargo build as `--out-dir` is unstable and contentious and -# `--target-dir` still requires us to know which profile and target the -# binaries were built for. By using `cargo install` we can also avoid needing -# to hard-code the set of binary names to copy so that if we add or remove -# built binaries in future this will "just work". Note that `--root /tmp/out` -# actually causes the binaries to be placed in `/tmp/out/bin/`. `cargo install` -# will create the output directory for us. -RUN CARGO_HTTP_MULTIPLEXING=false cargo install \ - --locked \ - --path . \ - --root /tmp/out/ \ - ${CARGO_ARGS} - +# Install required runtime dependencies +RUN apt-get update && apt-get install -y --no-install-recommends tini +# apt cache get's cleaned automatically -# ----------------------------------------------------------------------------- -# Docker stage: copy -# ----------------------------------------------------------------------------- -# Only used when MODE=copy. -# -# Copy binaries from the host directory 'dockerbin/$TARGETPLATFORM' directory -# into this build stage to the same predictable location that binaries would be -# in if MODE were 'build'. -# -# Requires that `docker build` be invoked with variable `DOCKER_BUILDKIT=1` set -# in the environment. This is necessary so that Docker will skip the unused -# 'build' stage and so that the magic $TARGETPLATFORM ARG will be set for us. -FROM ${BASE_IMG} AS copy ARG TARGETPLATFORM -ONBUILD COPY dockerbin/$TARGETPLATFORM /tmp/out/bin/ - - -# ----------------------------------------------------------------------------- -# Docker stage: source -# ----------------------------------------------------------------------------- -# This is a "magic" build stage that "labels" a chosen prior build stage as the -# one that the build stage after this one should copy application binaries -# from. It also causes the ONBUILD COPY command from the 'copy' stage to be run -# if needed. Finally, we ensure binaries have the executable flag set because -# when copied in from outside they may not have the flag set, especially if -# they were uploaded as a GH actions artifact then downloaded again which -# causes file permissions to be lost. -# See: https://github.com/actions/upload-artifact#permission-loss -FROM ${MODE} AS source -RUN chmod a+x /tmp/out/bin/* - - -# ----------------------------------------------------------------------------- -# Docker stage: final -# ----------------------------------------------------------------------------- -# Create an image containing just the binaries, configs & scripts needed to run -# our app, and not the things needed to build it. -# -# The previous build stage from which binaries are copied is controlled by the -# MODE ARG (see above). -FROM ${BASE_IMG} AS final - -# Copy binaries from the 'source' build stage into the image we are building -COPY --from=source /tmp/out/bin/* /usr/local/bin/ - -# Install required runtime dependencies -RUN apk add --no-cache libgcc tini +COPY $TARGETPLATFORM/dnst /usr/bin/ # Set the working directory so that users can easily mount a host filesystem # path where the dnst commands can read from and write to, e.g. via docker @@ -152,4 +19,4 @@ WORKDIR /data # Use Tini to ensure that our application responds to CTRL-C when run in the # foreground without the Docker argument "--init" (which is actually another # way of activating Tini, but cannot be enabled from inside the Docker image). -ENTRYPOINT ["/sbin/tini", "--", "dnst"] +ENTRYPOINT ["/usr/bin/tini", "--", "dnst"] diff --git a/doc/manual/build/man/dnst-key2ds.1 b/doc/manual/build/man/dnst-key2ds.1 deleted file mode 100644 index cee7acd..0000000 --- a/doc/manual/build/man/dnst-key2ds.1 +++ /dev/null @@ -1,82 +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 "DNST-KEY2DS" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst-key2ds \- Generate DS RRs from the DNSKEYs in a keyfile -.SH SYNOPSIS -.sp -\fBdnst key2ds\fP \fB[OPTIONS]\fP \fB\fP -.SH DESCRIPTION -.sp -\fBdnst key2ds\fP generates a DS RR for each DNSKEY in \fB\fP\&. -.sp -The following file will be created for each key: \fBK++.ds\fP\&. The -base name \fBK++\fP will be printed to stdout. -.SH ARGUMENTS -.INDENT 0.0 -.TP -.B -\fB\fP must be a file containing one or more RFC 4034 \fBDNSKEY\fP -resource records in presentation format. -.UNINDENT -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-a , \-\-algorithm -Use the given algorithm for the digest. Defaults to the digest algorithm -used for the DNSKEY, and if it can\(aqt be determined SHA\-1. -.UNINDENT -.INDENT 0.0 -.TP -.B \-f, \-\-force -Overwrite existing \fB\&.ds\fP files. -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-ignore\-sep -Ignore the SEP flag and make DS records for any key. -.UNINDENT -.INDENT 0.0 -.TP -.B \-n -Write the generated DS records to stdout instead of a file. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/dnst-keygen.1 b/doc/manual/build/man/dnst-keygen.1 deleted file mode 100644 index 53b8ac0..0000000 --- a/doc/manual/build/man/dnst-keygen.1 +++ /dev/null @@ -1,170 +0,0 @@ -'\" t -.\" 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 "DNST-KEYGEN" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst-keygen \- Generate a new key pair for a domain name -.SH SYNOPSIS -.sp -\fBdnst keygen\fP \fB[OPTIONS]\fP \fB\-a \fP \fB\fP -.SH DESCRIPTION -.sp -\fBdnst keygen\fP generates a new key pair for a given domain name. -.sp -The following files will be created: -.INDENT 0.0 -.IP \(bu 2 -\fBK++.key\fP: The public key file containing a DNSKEY RR in -zone file format. -.IP \(bu 2 -\fBK++.private\fP: The private key file containing the private -key data fields in BIND\(aqs \fIPrivate\-key\-format\fP\&. -.IP \(bu 2 -\fBK++.ds\fP: The public key digest file containing the DS RR -in zone file format. It is only created for key signing keys. -.UNINDENT -.nf -\fB\fP is the fully\-qualified owner name for the key (with a trailing dot). -\fB\fP is the algorithm number of the key, zero\-padded to 3 digits. -\fB\fP is the 16\-bit tag of the key, zero\-padded to 5 digits. -.fi -.sp -.sp -Upon completion, \fBK++\fP will be printed. -.SH ARGUMENTS -.INDENT 0.0 -.TP -.B -The owner name of the apex of the zone which the generated key is -intended to sign. -.UNINDENT -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-a -Use the given signing algorithm. Mandatory. -.sp -Possible values are: -.TS -box center; -l|l|l. -T{ -\fBMnemonic\fP -T} T{ -\fBNumber\fP -T} T{ -\fBDescription\fP -T} -_ -T{ -\fBlist\fP -T} T{ -T} T{ -List available algorithms -T} -_ -T{ -\fBRSASHA256\fP -T} T{ -8 -T} T{ -RSA with SHA\-256 -T} -_ -T{ -\fBECDSAP256SHA256\fP -T} T{ -13 -T} T{ -ECDSA P\-256 with SHA\-256 -T} -_ -T{ -\fBECDSAP384SHA384\fP -T} T{ -14 -T} T{ -ECDSA P\-384 with SHA\-384 -T} -_ -T{ -\fBED25519\fP -T} T{ -15 -T} T{ -ED25519 -T} -_ -T{ -\fBED448\fP -T} T{ -16 -T} T{ -ED448 -T} -.TE -.UNINDENT -.INDENT 0.0 -.TP -.B \-k -Generate a key signing key (KSK) instead of a zone signing key (ZSK). -.UNINDENT -.INDENT 0.0 -.TP -.B \-b -The length of the key (for RSA keys only). Defaults to 2048. -.UNINDENT -.INDENT 0.0 -.TP -.B \-r -The randomness source to use for generation. Defaults to \fB/dev/urandom\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-s -Create symlinks \fB\&.key\fP and \fB\&.private\fP to the generated keys. -.UNINDENT -.INDENT 0.0 -.TP -.B \-f -Overwrite existing symlinks (for use with \fB\-s\fP). -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/dnst-keyset.1 b/doc/manual/build/man/dnst-keyset.1 deleted file mode 100644 index 179f13c..0000000 --- a/doc/manual/build/man/dnst-keyset.1 +++ /dev/null @@ -1,1040 +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 "DNST-KEYSET" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst-keyset \- Manage DNSSEC signing keys for a domain -.SH SYNOPSIS -.sp -\fBdnst keyset\fP \fB\-c \fP \fB[OPTIONS]\fP \fB\fP \fB[ARGS]\fP -.SH DESCRIPTION -.sp -The \fBkeyset\fP subcommand manages a set of DNSSEC (\X'tty: link https://www.rfc-editor.org/rfc/rfc9364'\fI\%RFC 9364\fP\X'tty: link') signing keys -and generates a signed DNSKEY RRset. -This subcommand is meant to be part of a DNSSEC signing solution. -A separate zone signer (not part of dnst) is expected to use the zone -signing keys in the key set, -sign the zone and include the DNSKEY RRset (as well as the CDS and CDNSKEY -RRsets). -The keyset subcommand supports keys stored in files and, when the dnst -program is built with the kmip feature flag, keys stored in a -Hardware Security Module (HSM) that can be accessed using the -Key Management Interoperability Protocol (KMIP). -.sp -The keyset subcommand operates on one zone at a time. -For each zone, keyset maintains a configuration file that stores configuration parameters for -key generation (which algorithm to use, whether to use a CSK or a -KSK and ZSK pair), parameters for key rolls (whether key rolls are automatic -or not), the lifetimes of keys and signatures, etc. -The keyset subcommand also maintains a state file for each zone. -The state file lists the keys in the key set, the current key roll state, -and has the DNSKEY, CDS, and CDNSKEY RRsets. -key generation (which algorithm to use, whether to use a CSK and a -KSK and a ZSK), parameters for key rolls (whether key rolls are automatic -or not), the lifetimes of keys and signatures, etc. -The keyset subcommand also maintains state file for each zone. -.sp -In addition to the configuration and state files, keyset maintains files for -keys that are stored in the filesystem. -Additionally, keyset can optionally maintain a credentials file that -contains user names and passwords for the KMIP connections. -.sp -The keyset subcommand uses the Keyset type from the Rust Domain crate to store -the set of keys together with their properties such as whether a key -should sign the zone, timestamps when keys are created or become stale. -The Keyset data type also implements the basic logic of key rolls. -.sp -The keyset subcommand supports importing existing keys, both standalone -public keys as well as public/private key pairs can be imported. -A standalone public key can only be imported from a file whereas public/private -key pairs can be either files or references to keys stored in an HSM. -Note that the public and private key either need to be both files or both -stored in an HSM. -.SS Signer -.sp -The zone signer is expected to read the state file that is maintained by -keyset to find the current zone signing keys, to find the signed -DNSKEY/CDS/CDNSKEY RRset and to find the KMIP configuration. -.sp -See for a description of the state file. -.sp -The signer needs to poll the state file for changes. -If the signer is in full control of running keyset, then the state file needs -to be checked for changes after running keyset with commands the can -potientially change the state file (status subcommands, etc. do not change -the state file). -If however keyset can be invoked independently of the signer then the signer needs -to periodically check for changes, for example, at least every hour. -.SS Cron -.sp -The signatures of the DNSKEY, CDS and CDNSKEY RRsets need to updated -periodically. -In addition, key roll automation requires periodic invocation of keyset -to start new key rolls and to make progress on ones that are currently -executing. -.sp -For this purpose, keyset has a cron subcommand. -This subcommand handles any house keeping work that needs to be done. -The cron subcommand can be executed at regular times, for example, -once an hour from the cron(1) utility. -.sp -However, keyset also maintains a field in the state file, called -\fBcron\-next\fP, that specifies when the cron subcommand should be run next. -Running the cron subcommand early is fine, the current time is compared -again the \fBcron\-next\fP field and the subcommand exits early if -\fBcron\-next\fP is in the future. -Running the cron subcommand late may cause signatures to expire. -.SS Create / Init -.sp -The initialisation of a key set for a zone consists of two steps. -First the create subcommand create a configuration file with mostly default -values and a state file without any keys. -The init subcommand finishes the initialisation. -.sp -This two step procedure allows configuration parameters to be set between -the create and the init subcommand, for example, the algorithm to use. -It also allows existing public/private key pairs to be imported. -.sp -The init subcommand checks if any public/private key pairs have been imported. -If so, init checks if both a both roles (KSK and ZSK) are present. -A single CSK combines both rolls. -Absent a CSK, both a KSK and a ZSK need to be present otherwise the init command -fails. -Any imported public keys are ignored by init. -.sp -If no public/private key pairs have been imported then the init subcommand -will start an algorithm roll. -The algorithm roll will create new keys based on the current configuration: -either as files or in an HSM and either a CSK or a pair of KSK and ZSK. -.SS Key Rolls -.sp -The keyset subcommand can perform four different types of key rolls: -KSK rolls, ZSK rolls, CSK rolls and algorithm rolls. -A KSK roll replaces one KSK with a new KSK. -Similarly, a ZSK roll replaces one ZSK with a new ZSK. -A CSK roll also replaces a CSK with a new CSK but the roll also treats a -pair of KSK and ZSK keys as equivalent to a CSK. -So a CSK roll can also roll from KSK plus ZSK to a new CSK or from a CSK -to new a KSK and ZSK pair. -Note that a roll from KSK plus ZSK to a new KSK plus ZSK pair -is also supported. -Finally, an algorithm roll is similar to a CSK roll, but designed in -a specific way to handle the case where the new key or keys have an algorithm -that is different from one used by the current signing keys. -.sp -The KSK and ZSK rolls are completely independent and can run in parallel. -Consistency checks are performed at the start of a key roll. -For example, a KSK key roll cannot start when another KSK is in progress or -when a CSK or algorithm roll is in progress. -A KSK roll cannot start either when the current signing key is a CSK or -when the configuration specifies that the new signing key has to be a CSK. -Finally, KSK rolls are also prevented when the algorithm for new keys is -different from the one used by the current key. -Similar limitations apply to the other roll types. Note however that an -algorithm roll can be started even when it is not needed. -.sp -A key roll consists of six steps: \fBstart\-roll\fP, \fBpropagation1\-complete\fP, -\fBcache\-expired1\fP, \fBpropagation2\-complete\fP, \fBcache\-expired2\fP, and -\fBroll\-done\fP\&. -For each key roll these six steps follow in the same order. -Associated which each step is a (possibly empty) list of actions. -Actions fall in three categories. -The first category consists of actions that require updating the zone or the -parent zone. -The second category consists of actions that require checking if changes -have propagated to all nameservers and require reporting of the -TTLs of the changed RRset as seen at the nameservers. -Finally, the last category requires waiting for changes to propagate to -all nameservers but there is no need to report the TTL. -.sp -Typically, in a list of actions, an action of the first category is paired -with one from the second of third category. -For example, \fBUpdateDnskeyRrset\fP is paired with either -\fBReportDnskeyPropagated\fP or \fBWaitDnskeyPropagated\fP\&. -.sp -A key roll starts with the \fBstart\-roll\fP step, which creates new keys. -The next step, \fBpropagation1\-complete\fP has a TTL argument which is the -maximum of the TTLs of the Report actions. -The \fBcache\-expired1\fP and \fBcache\-expired2\fP have no associated actions. -They simply require waiting for the TTL (in seconds) reported by the -previous \fBpropagation1\-complete\fP or \fBpropagation2\-complete\fP\&. -The \fBpropagation2\-complete\fP step is similar to the \fBpropagation1\-complete\fP step. -Finally, the \fBroll\-done\fP step typically has associated Wait actions. -These actions are cleanup actions and are harmless but confusing if they -are skipped. -.sp -The keyset subcommand provides fine grained control over automation. -Automation is configured separately for each of the four roll types. -For each roll type, there are four booleans called \fBstart\fP, \fBreport\fP, -\fBexpire\fP and \fBdone\fP\&. -.sp -When set, the \fBstart\fP boolean directs the cron subcommand to start a key roll -when a relevant key has expired. -A KSK or a ZSK key roll can start automatically if respectively a KSK or a ZSK -has expired. -A CSK roll can start automatically when a CSK has expired but also when a KSK or -ZSK has expired and the new key will be a CSK. -Finally, an algorithm roll can start automatically when the new algorithm is -different from the one used by the existing keys and any key has expired. -.sp -The \fBreport\fP flags control the automation of the \fBpropagation1\-complete\fP -and \fBpropagation2\-complete\fP steps. -When enabled, the cron subcommand contacts the nameservers of the zone or -(in the case of \fBReportDsPropagated\fP, the nameservers of the parent zone) -to check if changes have propagated to all nameservers. -The check obtains the list of nameservers from the apex of the (parent) zone -and collects all IPv4 and IPv6 addresses. -For the \fBReportDnskeyPropagated\fP and \fBReportDsPropagated\fP actions, each address is -the queried to see if the DNSKEY RRset or DS RRset match -the KSKs. -The \fBReportRrsigPropagated\fP action is more complex. -First the entire zone is transferred from the nameservers specified via -\fBset publication\-nameservers\fP, or if not set form the primary nameserver -listed in the SOA record. -Then all relevant signatures are checked if they have the expected key tags. -The maximum TTL in the zone is recorded to be reported. -Finally, all addresses of listed nameservers are checked to see if they -have a SOA serial that is greater than or equal to the one that was checked. -.sp -Automation of \fBcache\-expired1\fP and \fBcache\-expired2\fP is enabled by the -\fBexpire\fP boolean. -When enabled, the cron subcommand simply checks if enough time has passed -to invoke \fBcache\-expired1\fP or \fBcache\-expired2\fP\&. -.sp -Finally the \fBdone\fP boolean enables automation of the \fBroll\-done\fP step. -This automation is very similar to the \fBreport\fP automation. -The only difference is that the Wait actions are automated so propagation -is tracked but no TTL is reported. -.sp -Fine grained control of over automation makes it possible to automate -KSK or algorithm without starting them automatically. -Or let a key roll progress automatically except that the \fBcache\-expired\fP -steps must be done manually in order to be able to insert extra manual steps. -.sp -The \fBreport\fP and \fBdone\fP automations require that keyset has network access -to all nameservers of the zone and all nameservers of the parent. -.sp -The configuration variables \fBautoremove\fP and \fBautoremove\-delay\fP -control the automatic removal of keys that are no longer needed. -The variable \fBautoremove\fP defaults to false. -In this case, stale keys have to be removed manually. -When \fBautoremove\fP is set to true, the \fBcron\fP subcommand checks if any -keys have been stale for at least \fBautoremove\-delay\fP, and if so, removes -those keys. -The \fBautoremove\-delay\fP variable defaults to one week. -.SS HSM Support (KMIP) -.sp -The keyset subcommand supports keys in Hardware Security Modules (HSM) through -the KMIP protocol. -The most common way to access keys in HSMs is through the PKCS #11 interface. -The PKCS #11 interface involves loading a shared library into the process -that needs to access the HSM. -This is unattractive for two reasons: -.INDENT 0.0 -.IP 1. 3 -Loading an arbitrary (binary) shared libary negates the memory security -features of an application written in Rust. A mistake in the shared library -could corrupt memory that is used by the application. For this reason it is -attractive to load the shared library into a separate process. -.IP 2. 3 -Setting up the run\-time environment of the shared library is often complex. -The library may require specific environment variables or access to specific -files or devices. This complexity impacts every application that wants -to use the shared library. -.UNINDENT -.sp -For these reasons it was decided to write a separate program, called -kmip2kpcs11, that uses the PKCS #11 standard to have access to an HSM and -provides a KMIP server interface. This makes it possible to contain both -the configuration complexity and the possibility of memory corruption in -a single program. -Other programs, such as the keyset subcommand then use the KMIP protocol to -indirectly access the HSM via the kmip2kpcs11 program. -Support for the KMIP protocol also makes it possible to directly connect to -KMIP capable HSMs. -.sp -The keyset subcommand stores two pieces of KMIP configuration. -The first is a list of KMIP servers. -Each KMIP server has a \fBserver ID\fP that is used in key references to specify -in which server the key is stored. -A server also has a DNS name or IP address and a port to connect to the server. -The second piece of configuration is the ID of the server to be used for -creating new keys. -It is possible to specify that no server is to be used for new keys, in that -case new keys will be created by keyset and stored as files. -.sp -Authentication can be done either with a user name and password or with -a client\-side certificate. -The user name and password are KMIP concepts that are mapped by the -cascade\-hsm\-bridge server to a PKCS #11 slot or token name and the PIN. -With this approach the cascade\-hsm\-bridge server des not have to store secrets -that provide access to the HSM. -User names and passwords are stored in a separate file to avoid storing -secrets in the keyset configuration or state files. -.sp -Unlike other configuration, the list of KMIP servers is stored in the state -file. -The reason for doing that is that signers also need the same KMIP server list -to be able to sign a zone. -By storing the server list in the state file, a signer has to read only the -state file to be able to use KMIP keys. -.sp -Options that can be configured for a server include not checking the -server\(aqs certificate, specifying the server\(aqs certificate or certificate -authority, various connection parameters such as connect timeout, read -timeout, write timeout and maximum response size. -.sp -When generating new keys, the label of the key can have a user supplied prefix. -This can be used, for example, to show that a key is for -development or testing. -Finally, some HSMs allow longer labels than others. -On HSMs that allow longer labels than the 32 character default, raising the -maximum label length can avoid truncation for longer domain names. -On HSMs that have a limit that is lower than the default, setting the correct -length avoids errors when creating keys. -.SS Importing Keys -.sp -There are three basic ways to import exiting keys: public\-key, -a public/private key pair from files or a public/private key pair in an HSM. -.sp -A public key can only be imported from a file. -When the key is imported the name of the file is converted to a URL and stored in the key set and -the key will be included in the DNSKEY RRset. -This is useful for certain migrations and to manually implement a -multi\-signer DNSSEC signing setup. -Note that automation does not work for this case. -.sp -A public/private key pair can be imported from files. -It is sufficient to give the name of the file that holds the public key if -the filename ends in \fB\&.key\fP and the filename of the private key is the -same except that it ends in \fB\&.private\fP\&. -If this is not the case then the private key filename must be specified -separately. -.sp -In order to use keys stored in a HSM the \fBdnst keyset kmip add\-server\fP -subcommand must first be used to associate the KMIP server connection settings -with a user defined server ID. -.sp -The first server defined becomes the default. If a default KMIP server has -been defined it will be used to generate all future keys, unless the \fBdnst -keyset kmip disable\fP command is issued. If more than one KMIP server is -defined, only one can be the default server at any time. Use the \fBdnst -keyset kmip set\-default\fP command to change which KMIP server will be used -to generate future keys. Note that like all \fBdnst keyset\fP subcommands, the -KMIP subcommands set behaviour for a single zone. Additionally there are -\fBlist\-servers\fP, \fBget\-server\fP, \fBmodify\-server\fP and \fBremove\-server\fP -subcommands for inspecting and altering the configured KMIP server settings. -.sp -Importing a public/private key stored in an HSM requires specifying the KMIP -server ID, the ID of the public key, the ID of the private key, the -DNSSEC algorithm of the key and the flags (typically 256 for a ZSK and -257 for a KSK). -.sp -Normally, keyset assumes ownership of any keys it holds. -This means that when a key is deleted from the key set, the keyset subcommand -will also delete the files that hold the public and private keys or delete the -keys from the HSM that was used to create them. -.sp -For an imported public/private key pair this is considered too dangerous -because another signer may need the keys. -For this reason keys are imported in so\-called \fBdecoupled\fP state. -When a decoupled key is deleted, only the reference to the key is deleted -from the key set, the underlying keys are left untouched. -There is a \fB\-\-coupled\fP option to tell keyset to take ownership of the key. -.SS Migration -.sp -The keyset subcommand has no direct support for migration. -Migration has to be done manually using the import commands. -The semantics of the import commands are described in the previous section. -This section focuses on how the import command can be used to perform a -migration. -.sp -There are three migration strategies: 1) importing the existing signer\(aqs -(private) signing keys, 2) a full multi\-signer migration and 3) -a partial multi\-signer migration. -.SS Importing the existing signer\(aqs signing keys -.sp -Importing the existing signer\(aqs public/private keys pairs is the easiest -migration mechanism. -The basic process is the following: -.INDENT 0.0 -.IP \(bu 2 -Disable (automatic) key rolls on the existing signer. -.IP \(bu 2 -Disable automatic key rolls before executing the create command. -For example by setting the KSK, ZSK, and CSK validities to \fBoff\fP\&. -.IP \(bu 2 -Import the KSK and ZSK (or CSK) as files or using KMIP between the -create and init commands. -.IP \(bu 2 -Check with tools such as ldns\-verify\-zone that the new zone is secure with -the existing DS record at the parent. -.IP \(bu 2 -Switch the downstream secondaries that serve the zone to receive the -signed zone from the new signer. -.IP \(bu 2 -Perform key rolls for the KSK and ZSK (or the CSK). -.IP \(bu 2 -(If wanted) enable automatic key rolls. -.IP \(bu 2 -Remove the zone from the old signer. -.UNINDENT -.sp -Note that after the key roll, the signer has to make sure that it -keeps access to signing keys. -In case of KMIP keys, the old signer can also delete the keys from the HSM. -For this reason it is best to perform key rolls of all keys before removing -the zone from the old signer. -.sp -This document describes key management. Care should be taken that other -parameters, such as the use of NSEC or NSEC3, are -the same (to avoid confusion) and that the SOA serial policy is the same -(to avoid problems with zone transfers). -.SS Full multi\-signer migration -.sp -The basic idea is to execute the following steps: -.INDENT 0.0 -.IP \(bu 2 -Disable (automatic) key rolls on the existing signer. -.IP \(bu 2 -If the parent supports automatic updating of the DS record using CDS/CDNSKEY -(RFC 8078) then disable the generation of CDS/CDNSKEY records on the -existing signer or disable CDS/CDNSKEY processing for this zone at the parent. -.IP \(bu 2 -Issue the create command. -.IP \(bu 2 -Disable automatic key rolls. -.IP \(bu 2 -(Disable CDS/CDNSKEY generation. Keyset cannot disable CDS/CDNSKEY generation at the moment) -.IP \(bu 2 -Import the public key of the existing signer\(aqs ZSK (or CSK) use the -\fBkeyset import public\-key\fP subcommand. -.IP \(bu 2 -Issue the init command. -.IP \(bu 2 -Make sure in the next step to only add a DS record at the parent, not -delete the existing one. -.IP \(bu 2 -Complete the initial algorithm roll. -.IP \(bu 2 -Verify using tools such as ldns\-verify\-zone that the zone is correctly -signed. -.IP \(bu 2 -Import the public key of the new ZSK (or CSK) in the existing signer. -.IP \(bu 2 -Verify that all nameservers that serve the zone have the new ZSK in the -DNSKEY RRset of the existing signer. -.IP \(bu 2 -Transition the nameservers from the existing signer to the new signer. -.IP \(bu 2 -Let caches expire for the DNSKEY RRset of the old signer and the -zone RRSIGs of the old signer. -.IP \(bu 2 -Remove the DS record for the old signer from the parent. -.IP \(bu 2 -Remove the imported public key. -.IP \(bu 2 -(If wanted) enable automatic key rolls and generation of CDS/CDNSKEY -records. -.UNINDENT -.SS Partial multi\-signer migration -.sp -A partial multi\-signer migration is the right approach when the existing -signer cannot import the new signers ZSK. -A requirement is that the new signer can transfer the signed zone from the -existing signer and that the new signer supports so\-called \(dqpass\-through\(dq -mode. -In pass\-through mode a signer leaves signatures for zone records unchanged -but does replace the DNSKEY, CDS and CDNSKEY RRset with the ones from -this subcommand. -.sp -The basic idea is to execute the following steps: -.INDENT 0.0 -.IP \(bu 2 -Disable (automatic) key rolls on the existing signer. -.IP \(bu 2 -If the parent supports automatic updating of the DS record using CDS/CDNSKEY -(RFC 8078) then disable the generation of CDS/CDNSKEY records in the -existing signer or disable CDS/CDNSKEY processing for this zone at the parent. -.IP \(bu 2 -Issue the create command. -.IP \(bu 2 -Disable automatic key rolls. -.IP \(bu 2 -(Disable CDS/CDNSKEY generation. Keyset cannot disable CDS/CDNSKEY generation at the moment) -.IP \(bu 2 -Import the public key of the existing signer\(aqs ZSK (or CSK). -.IP \(bu 2 -Issue the init command. -.IP \(bu 2 -Switch the new signer to pass\-through mode. The signer has to transfer the -signed zone from the existing signer. -.IP \(bu 2 -Make sure in the next step to only add a DS record at the parent, not -the delete the existing one. -.IP \(bu 2 -Complete the initial algorithm roll. -.IP \(bu 2 -Verify using tools such as ldns\-verify\-zone that the zone is correctly -signed. -.IP \(bu 2 -Transition the nameservers from the existing signer to the new signer. -.IP \(bu 2 -Let caches expire for the DNSKEY RRset of the old signer. -.IP \(bu 2 -Remove the DS record for the old signer from the parent. -.IP \(bu 2 -Switch off pass\-through mode. -.IP \(bu 2 -Let caches expire for the zone RRSIGs of the old signer. -.IP \(bu 2 -Remove the imported public key. -.IP \(bu 2 -(If wanted) enable automatic key rolls and generation of CDS/CDNSKEY -records. -.UNINDENT -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-c -Configuration file. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.SH COMMANDS -.sp -The keyset subcommand provides the following commands: -.INDENT 0.0 -.IP \(bu 2 -create -.sp -Create empty configuration and state files for a domain. -.INDENT 2.0 -.TP -.B \-n -The name of the domain for which signing keys will be managed. -.UNINDENT -.INDENT 2.0 -.TP -.B \-s -The name of the state file. -.UNINDENT -.IP \(bu 2 -init -.sp -Initialize the keyset. -If a KSK and ZSK (or a CSK) have been imported then the DNSKEY RRset will -be created and signed. -If there are no keys, then a KSK and a ZSK will be created (unless the -use\-csk option is set to true) and an algorithm roll will be started. -The init command will fail if the keyset has been initialized already. -.IP \(bu 2 -ksk, zsk, csk, and algorithm -.sp -The ksk, zsk, csk, and algorithm commands perform manual key roll steps. -These commands have the following subcommands: -.INDENT 2.0 -.IP \(bu 2 -start\-roll -.sp -Start a key roll of the type specified by the command. -.IP \(bu 2 -propagation1\-complete -.sp -Inform keyset that the changed RRsets and signatures have propagated. -Report the maximum TTL of the report actions. -.IP \(bu 2 -cache\-expired1 -.sp -Inform keyset that enough time has passed that caches should have expired. -Note that this command will fail if invoked too early. -.IP \(bu 2 -propagation2\-complete -.sp -This command is similar to propagation1\-complete. -.IP \(bu 2 -cache\-expired2 -.sp -This command is similar to cache\-expired1. -.IP \(bu 2 -roll\-done -.sp -Inform keyset that the changed RRsets and signatures have propagated -and that any wait actions have been executed successfully. -.UNINDENT -.IP \(bu 2 -import -.sp -The import command can either import a public key in a file or a -public/private key pair in either files or as KMIP references. -.INDENT 2.0 -.IP \(bu 2 -public\-key -.sp -A reference to a public key in is added to the keyset. -Imported public keys are added to the DNSKEY RRset. -.IP \(bu 2 -ksk, zsk, csk -.sp -A key pair is imported as a KSK, ZSK, or CSK. -When a key is imported, there is the question what to do when the -imported key is later deleted. -By default, keyset imports keys in \fBdecoupled\fP state. -When a decoupled key is later removed, only the reference is deleted from -the key set. -The file that contains the key is not deleted and the key is not deleted -from an HSM. -Passing the option \fB\-\-coupled\fP when importing a key, directs keyset to -take ownership of the key. -.sp -The key pair can be imported in two ways: -.INDENT 2.0 -.IP \(bu 2 -file -.sp -The argument refers to the public key. The filename of the -private key is derived from the public key unless the \fB\-\-private\-key\fP -option is used to specify the filename that holds the private key. -.INDENT 2.0 -.TP -.B \-\-coupled -Take ownership of the imported keys. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-private\-key -Explicitly pass the name of the file that holds the private key. -.UNINDENT -.IP \(bu 2 -kmip -.sp -The argument specifies one of the KMIP servers that has been -configured using the \fBkmip add\-server\fP command. -The and arguments are the KMIP identifiers of -the public key and the private key respectively. -The DNSSEC algorithm is specified using the argument and -finally the argument (usually 256 or 257) is the value of -the flags field in the DNSKEY record for the public key. -.INDENT 2.0 -.TP -.B \-\-coupled -Take ownership of the imported keys. -.UNINDENT -.UNINDENT -.UNINDENT -.IP \(bu 2 -remove\-key -.sp -Remove a key or key pair from the key set. -The argument is the URL of the public key. -If the key is \fBcoupled\fP then the files that hold the keys are also removed -or, in case of KMIP keys, the keys are removed from the HSM. -Normally, keys are only removed when they are stale. -.INDENT 2.0 -.TP -.B \-\-force -Force a key to be removed even if the key is not stale. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-continue -Continue when removing a key file fails or when a key cannot be removed -from an HSM. -.UNINDENT -.IP \(bu 2 -status -.sp -Provide status information about key rolls, key expiration and signature -expiration. -.INDENT 2.0 -.TP -.B \-v \-\-verbose -Make status verbose. -.UNINDENT -.IP \(bu 2 -actions -.sp -Show the actions that have to be executed for any key rolls. -.IP \(bu 2 -keys -.sp -Give detailed information about all keys in the key set. -.IP \(bu 2 -get -.sp -Get the values of the following configuration variables: use\-csk, -autoremove, autoremove\-delay, algorithm, ds\-algorithm, dnskey\-lifetime, -cds\-lifetime. -This is a subset of all configuration variables. -.sp -Additionally, the dnskey argument returns the current DNSKEY RRset plus -signatures, cds returns the CDS and CDNSKEY RRsets plus signatures and -ds returns DS records that should be added to the parent zone. -.IP \(bu 2 -set -.sp -Set configuation variables. -Note that setting configuration variables after the create command but -before the init command can be used to affect the initial key creation. -.INDENT 2.0 -.IP \(bu 2 -use\-csk -.sp -When true, new keys will be created as CSK otherwise a KSK and a ZSK -will be created. -.IP \(bu 2 -autoremove -.sp -When true, keys that are stale will be removed automatically. -.IP \(bu 2 -autoremove\-delay -.sp -Set the delay between the time keys become stale and automatic -removal. -.IP \(bu 2 -algorithm -.sp -Set the algorithm to be used when creating new keys. Supported values -are RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, -and ED448. -Not all values are supported for KMIP keys. -.INDENT 2.0 -.TP -.B \-b -For RSA keys, the length of the key in bits. -.UNINDENT -.IP \(bu 2 -ksk\-roll\-type -.sp -The type of KSK roll to use. Possible values are double\-signature\-ksk\-roll -and double\-ds\-ksk\-roll. -.IP \(bu 2 -zsk\-roll\-type -.sp -The type of ZSK roll to use. Possible values are pre\-publish\-zsk\-roll -and double\-signature\-zsk\-roll. -.IP \(bu 2 -auto\-ksk, auto\-zsk, auto\-csk, auto\-algorithm -.sp -These commands take four boolean arguments: . -When set to true, the corresponding step or steps of the key roll specified -by the command are executed automatically. -.sp -For example, \fBauto\-csk true false true false\fP means that -CSK rolls will start automatically, that the propagation1\-complete, -propagation2\-complete, and roll\-done need to be executed manually. -The cache\-expired1 and cache\-expired2 steps are executed automatically. -.IP \(bu 2 -ds\-algorithm -.sp -Set the hash algorithm to be used for generating DS records. -Possible values are \fBSHA\-256\fP and \fBSHA\-384\fP\&. -.IP \(bu 2 -dnskey\-lifetime , cds\-lifetime -.sp -When a DNSKEY RRset is signed (dnskey\-lifetime) or when CDS or CDNSKEY -RRsets are signed (cds\-lifetime), how far in the future are the signatures -set to expire. -The duration is an integer followed by a suffix, \fBs\fP or \fBsecs\fP for -seconds, \fBm\fP or \fBmins\fP for minutes, \fBh\fP or \fBhours\fP, \fBd\fP or \fBdays\fP, \fBw\fP or \fBweeks\fP\&. -.IP \(bu 2 -dnskey\-remain\-time , cds\-remain\-time -.sp -The minimum amount of remaining time that signatures for the DNSKEY RRset -(dnskey\-remain\-time) or the CDS or CDNSKEY RRsets (cds\-remain\-time) have -to be valid. -New signatures are generated when the remaining time drops below the -specified duration. -For the syntax of see \fBdnskey\-lifetime\fP\&. -.IP \(bu 2 -dnskey\-inception\-offset , cds\-inception\-offset -.sp -When generating signatures for the DNSKEY RRset (dnskey\-inception\-offset) -or the CDS and CDNSKEY RRsets (cds\-inception\-offset), set the inception -timestamp this amount in the past to compensate for clocks that are a -bit off or in the wrong time zone. -For the syntax of see \fBdnskey\-lifetime\fP\&. -.IP \(bu 2 -ksk\-validity | \fBoff\fP, zsk\-validity | \fBoff\fP, csk\-validity | \fBoff\fP -.sp -Set how long a KSK, ZSK, or CSK is considered valid. -The special value \fBoff\fP means that no limit has been set. -For the syntax of see \fBdnskey\-lifetime\fP\&. -.sp -When a key is no longer considered valid and automatic starting of the -appropriate key roll has been enabled then a key roll will start at the -next invocation of the cron command. -.sp -The status command shows which keys are no longer valid or when their -validity will end. -.IP \(bu 2 -update\-ds\-command -.sp -Set a command to to run when the DS records in the parent zone need -to be updated. -This command can, for example, alert the operator or use an API provided -by the parent zone to update the DS records automatically. -.IP \(bu 2 -tsig\-store\-path -.sp -Set the path to a TSIG key store file to use. -.sp -Keys defined in the store file must use one of the following algorithms: -.INDENT 2.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -hmac\-sha1 -.IP \(bu 2 -hmac\-sha256 -.IP \(bu 2 -hmac\-sha384 -.IP \(bu 2 -hmac\-sha512 -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Currently there is no way to create this file using \fBdnst keyset\fP\&. -The file is in JSON format and defines zero or more TSIG keys as -entries in a map. The example below defines a single TSIG key with name -\fBtsig\-zonedata\-ch\-public\-21\-03\fP using algorithm \fBhmac\-sha512\fP with a -base64 encoded secret. -.INDENT 2.0 -.INDENT 3.5 -.sp -.EX -{ - \(dqversion\(dq: \(dqv1\(dq, - \(dqmap\(dq: { - \(dqtsig\-zonedata\-ch\-public\-21\-01\(dq: { - \(dqalg\(dq: \(dqhmac\-sha512\(dq, - \(dqdata\(dq: \(dqstZw...iJ3Q==\(dq - } - } -} -.EE -.UNINDENT -.UNINDENT -.IP \(bu 2 -publication\-nameservers -.sp -Set the nameservers to transfer from when checking a zone. -.sp -If no nameserver values are specified the default behaviour of querying -the primary nameserver defined in the SOA record will be used. -.sp -Nameservers should be specified as space separated -arguments, each nameserver being one argument in the form: -.INDENT 2.0 -.INDENT 3.5 -:[^] -.UNINDENT -.UNINDENT -.IP \(bu 2 -fake\-time -.sp -Set the \(aqwall clock\(aq time to be used for testing. -The argument is either the Unix time as seconds since Epoch or the string -\(aqoff\(aq to disable fake\-time. -.UNINDENT -.IP \(bu 2 -show -.sp -Show all configuration variables. -.sp -Note that \(aqfake\-time\(aq is only printed when it is set. -.IP \(bu 2 -cron -.sp -Execute any automatic steps such a refreshing signatures or automatic steps -in key rolls. -.IP \(bu 2 -kmip -.sp -The kmip command manages the list of configured KMIP servers and the -default server to use for generating new keys. -The kmip command has the following subcommands: -.INDENT 2.0 -.IP \(bu 2 -disable -.sp -Disable use of KMIP for generating new keys. -.IP \(bu 2 -add\-server -.sp -Add a KMIP server with name and DNS name or IP address -. -The name of the server is used in a key reference to identify which KMIP -server holds the key. -.INDENT 2.0 -.TP -.B \-\-port -TCP port to connect to the KMIP server on. The default port is 5696. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-pending -Add the server but don\(aqt make it the default. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-credential\-store -Optional path to a JSON file to read/write username/password -credentials from/to. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-username -Optional username to authenticate to the KMIP server as. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-password -Optional password to authenticate to the KMIP server with. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-client\-cert -Optional path to a TLS certificate to authenticate to the KMIP server -with. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-client\-key -Optional path to a private key for client certificate authentication. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-insecure -Accept the KMIP server TLS certificate without verifying it. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-server\-cert -Optional path to a TLS PEM certificate for the server. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-ca\-cert -Optional path to a TLS PEM certificate for a Certificate Authority. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-connect\-timeout -TCP connect timeout. Default 3 seconds. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-read\-timeout -TCP response read timeout. Default 30 seconds. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-write\-timeout -TCP request write timeout. Default 3 seconds. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-max\-response\-bytes -Maximum KMIP response size to accept (in bytes). Default 8192 bytes. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-key\-label\-prefix -Can be used to denote the s/w that created the key, and/or to indicate -which installation/environment it belongs to, e.g. dev, test, prod, -etc. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-key\-label\-max\-bytes -Maximum label length (in bytes) permitted by the HSM. Default 32 bytes. -.UNINDENT -.IP \(bu 2 -modify\-server -.sp -Modify the settings of the server with ID . This subcommand -takes most of the options documented at \fBkmip add\-server\fP\&. -Some options have the same name but are slightly different. -There are also a few additional options. -The new and modified options are listed below. -.INDENT 2.0 -.TP -.B \-\-address -Modify the hostname or IP address of the KMIP server. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-no\-credentials -Disable use of username / password authentication. -Note: This will remove any credentials from the credential\-store for -this server id. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-no\-client\-auth -Disable use of TLS client certificate authentication. -.UNINDENT -.INDENT 2.0 -.TP -.B \-\-insecure -Modify whether or not to accept the KMIP server TLS certificate -without verifying it. -.UNINDENT -.IP \(bu 2 -remove\-server -.sp -Remove an existing non\-default KMIP server. -To remove the default KMIP server use \fIkmip disable\fP first. -A server cannot be removed if there are keys that reference it. -.IP \(bu 2 -set\-default\-server -.sp -Set the default KMIP server to use for key generation. -.IP \(bu 2 -get\-server -.sp -Get the details of an existing KMIP server. -.IP \(bu 2 -list\-servers -.sp -List all configured KMIP servers. -.UNINDENT -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/dnst-notify.1 b/doc/manual/build/man/dnst-notify.1 deleted file mode 100644 index e19ff75..0000000 --- a/doc/manual/build/man/dnst-notify.1 +++ /dev/null @@ -1,105 +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 "DNST-NOTIFY" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst-notify \- Send a NOTIFY message to a list of name servers -.SH SYNOPSIS -.sp -\fBdnst notify\fP \fB[OPTIONS]\fP \fB\-z \fP \fB...\fP -.SH DESCRIPTION -.sp -\fBdnst notify\fP sends a NOTIFY message to the specified name servers. -.sp -This tells them that an updated zone is available at the primaries. It can -perform TSIG signatures, and it can add a SOA serial number of the updated -zone. If a server already has that serial number it will disregard the message. -.SH ARGUMENTS -.INDENT 0.0 -.TP -.B ... -One or more name servers to which NOTIFY messages will be sent, by -default on port 53. -.sp -Each name server can be specified as a domain name or IP address. -.UNINDENT -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-z -The zone to send the NOTIFY for. Mandatory. -.UNINDENT -.INDENT 0.0 -.TP -.B \-I
-Source IP to send the message from. -.UNINDENT -.INDENT 0.0 -.TP -.B \-I
-Source IP to send the message from. -.UNINDENT -.INDENT 0.0 -.TP -.B \-s -SOA version number to include in the NOTIFY message. -.UNINDENT -.INDENT 0.0 -.TP -.B \-y, \-\-tsig -A base64 TSIG key and optional algorithm to use for the NOTIFY message. -The algorithm defaults to \fBhmac\-sha512\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-p, \-\-port -Destination port to send the UDP packet to. Defaults to 53. -.UNINDENT -.INDENT 0.0 -.TP -.B \-d, \-\-debug -Print debug information. -.UNINDENT -.INDENT 0.0 -.TP -.B \-r, \-\-retries -Max number of retries. Defaults to 15. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/dnst-nsec3-hash.1 b/doc/manual/build/man/dnst-nsec3-hash.1 deleted file mode 100644 index 986dabb..0000000 --- a/doc/manual/build/man/dnst-nsec3-hash.1 +++ /dev/null @@ -1,81 +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 "DNST-NSEC3-HASH" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst-nsec3-hash \- Print out the NSEC3 hash of a domain name -.SH SYNOPSIS -.sp -\fBdnst nsec3\-hash\fP \fB[OPTIONS]\fP \fB\fP -.SH DESCRIPTION -.sp -\fBdnst nsec3\-hash\fP prints the NSEC3 hash of a given domain name. -.SH ARGUMENTS -.INDENT 0.0 -.TP -.B -The domain name to generate an NSEC3 hash for. -.UNINDENT -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-a , \-\-algorithm -Use the given algorithm number for the hash calculation. Defaults to -1 (SHA\-1). -.UNINDENT -.INDENT 0.0 -.TP -.B \-i , \-t , \-\-iterations -Use the given number of additional iterations for the hash -calculation. Defaults to 0. -.UNINDENT -.INDENT 0.0 -.TP -.B \-s , \-\-salt -Use the given salt for the hash calculation. The salt value should be -in hexadecimal format. Defaults to an empty salt. -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-find\-prefix -Find a label that result in an NSEC3 hash that starts with a given -string. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/dnst-signzone.1 b/doc/manual/build/man/dnst-signzone.1 deleted file mode 100644 index 6ce30bd..0000000 --- a/doc/manual/build/man/dnst-signzone.1 +++ /dev/null @@ -1,205 +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 "DNST-SIGNZONE" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst-signzone \- Sign the zone with the given key(s) -.SH SYNOPSIS -.sp -\fBdnst signzone\fP \fB[OPTIONS]\fP \fB\-o \fP \fB\fP \fB...\fP -.SH DESCRIPTION -.sp -\fBdnst signzone\fP signs the zonefile with the given key(s). -.sp -Signing a zone adds DNS Security Extensions (DNSSEC) resource records -.sp -Keys must be specified by their base name (usually \fBK++\fP), -i.e. WITHOUT the \fB\&.private\fP or \fB\&.key\fP extension. Both \fB\&.private\fP and -\fB\&.key\fP files are required. -.SH ARGUMENTS -.INDENT 0.0 -.TP -.B -The zonefile to sign. Any existing NSEC(3) and/or RRSIG resource records -will be skipped when loading the file. -.UNINDENT -.INDENT 0.0 -.TP -.B ... -The keys to sign the zonefile with. -.UNINDENT -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-d -Do not add used keys to the resulting zonefile. -.UNINDENT -.INDENT 0.0 -.TP -.B \-e -Set the expiration date of signatures to this date (see -\fI\%DATES\fP). Defaults to 4 weeks from now. -.UNINDENT -.INDENT 0.0 -.TP -.B \-f -Write signed zone to file. Use \fB\-f \-\fP to output to stdout. Defaults to -\fB.signed\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-i -Set the inception date of signatures to this date (see -\fI\%DATES\fP). Defaults to now. -.UNINDENT -.INDENT 0.0 -.TP -.B \-o -Use this owner name as the apex of the zone. Mandatory. -.UNINDENT -.INDENT 0.0 -.TP -.B \-u -Set SOA serial to the number of seconds since Jan 1st 1970. -.sp -If this would NOT result in the SOA serial increasing it will be -incremented instead. -.UNINDENT -.INDENT 0.0 -.TP -.B \-n -Use NSEC3 instead of NSEC. By default, RFC 9276 best practice settings -are used: SHA\-1, no extra iterations, empty salt. To use different NSEC3 -settings see \fI\%NSEC3 options\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-A -Sign DNSKEYs with all keys instead of the minimal set. -.UNINDENT -.INDENT 0.0 -.TP -.B \-U -Sign with every unique algorithm in the provided keys. -.UNINDENT -.INDENT 0.0 -.TP -.B \-z <[SCHEME:]HASH> -Add a ZONEMD resource record. Accepts both mnemonics and numbers. -This option can be provided more than once to add multiple ZONEMD RRs. -However, only one per scheme\-hash tuple will be added. -.nf -HASH supports \fBSHA384\fP (1) and \fBSHA512\fP (2). -SCHEME supports \fBSIMPLE\fP (1), the default. -.fi -.sp -.UNINDENT -.INDENT 0.0 -.TP -.B \-Z -Allow adding ZONEMD RRs without signing the zone. With this option, the -... argument becomes optional and determines whether to sign the -zone. -.UNINDENT -.INDENT 0.0 -.TP -.B \-H -Hash only, don\(aqt sign. With this option, the normally mandatory ... -argument can be omitted. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.SH OUTPUT FORMATTING OPTIONS -.sp -The following options can be used to affect the format of the output. -.INDENT 0.0 -.TP -.B \-b -Add comments on DNSSEC records. Without this option only DNSKEY RRs -will have their key tag annotated in the comment. -.UNINDENT -.INDENT 0.0 -.TP -.B \-L -Preceed the zone output by a list that contains the NSEC3 hashes of the -original ownernames. -.UNINDENT -.INDENT 0.0 -.TP -.B \-O -Order NSEC3 RRs by unhashed owner name. -.UNINDENT -.INDENT 0.0 -.TP -.B \-R -Order RRSIG RRs by the record type that they cover. -.UNINDENT -.INDENT 0.0 -.TP -.B \-T -Output YYYYMMDDHHmmSS RRSIG timestamps instead of seconds since epoch. -.UNINDENT -.SH NSEC3 OPTIONS -.sp -The following options can be used with \fB\-n\fP to override the default NSEC3 -settings used. -.INDENT 0.0 -.TP -.B \-s -Specify the salt as a hex string. Defaults to \fB\-\fP, meaning empty salt. -.UNINDENT -.INDENT 0.0 -.TP -.B \-t -Set the number of extra hash iterations. Defaults to 0. -.UNINDENT -.INDENT 0.0 -.TP -.B \-p -Set the opt\-out flag on all NSEC3 RRs. -.UNINDENT -.INDENT 0.0 -.TP -.B \-P -Set the opt\-out flag on all NSEC3 RRs and skip unsigned delegations. -.UNINDENT -.SH DATES -.sp -A date can be a UNIX timestamp as seconds since the Epoch (1970\-01\-01 -00:00 UTC), or of the form \fB\fP\&. -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/dnst-update.1 b/doc/manual/build/man/dnst-update.1 deleted file mode 100644 index b4014e5..0000000 --- a/doc/manual/build/man/dnst-update.1 +++ /dev/null @@ -1,198 +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 "DNST-UPDATE" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst-update \- Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name -.SH SYNOPSIS -.sp -\fBdnst update\fP \fB[OPTIONS]\fP \fB\fP \fB\fP -.sp -\fBdnst update\fP \fB[OPTIONS]\fP \fB\fP \fBadd\fP \fB\fP \fB[RDATA]...\fP -.sp -\fBdnst update\fP \fB[OPTIONS]\fP \fB\fP \fBdelete\fP \fB\fP \fB[RDATA]...\fP -.sp -\fBdnst update\fP \fB[OPTIONS]\fP \fB\fP \fBclear\fP \fB\fP -.SH DESCRIPTION -.sp -\fBdnst update\fP sends an RFC 2136 Dynamic Update message to the name servers -for a zone to add, update, or delete arbitrary Resource Records for a domain -name. -.sp -The message to be sent can be optionally authenticated using a given TSIG key. -.sp -\fBdnst update [...] add\fP adds the given RRs to the domain. -.sp -\fBdnst update [...] delete\fP deletes the given RRs from the domain. It can be -used to delete individual RRs or a whole RRset. -.sp -\fBdnst update [...] clear\fP clears (deletes) all RRs of any type from the -domain name. -.SH ARGUMENTS -.INDENT 0.0 -.TP -.B -The domain name of the RR(s) to update. -.UNINDENT -.INDENT 0.0 -.TP -.B -Which action to take: add, delete, or clear. -.UNINDENT -.SH OPTIONS: -.INDENT 0.0 -.TP -.B \-c, \-\-class -Class -.sp -Defaults to IN. -.UNINDENT -.INDENT 0.0 -.TP -.B \-t, \-\-ttl -TTL in seconds or with unit suffix (s, m, h, d). -.sp -Is only used by the \fBadd\fP command and is otherwise ignored. -.sp -Defaults to 3600. -.UNINDENT -.INDENT 0.0 -.TP -.B \-s, \-\-server -The name server to send the update to. -.sp -By default, the update will be sent to the list of name servers fetched -from the zone\(aqs NS RRset as per RFC 2136. -.UNINDENT -.INDENT 0.0 -.TP -.B \-z, \-\-zone -The zone the domain name belongs to (to skip a SOA query) -.UNINDENT -.INDENT 0.0 -.TP -.B \-y, \-\-tsig -TSIG credentials for the UPDATE packet -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-rrset\-exists -Require that at least one RR with the given NAME and TYPE exists. -This option can be provided multiple times, with format \fB -\fP each, to build up a list of RRs. -.sp -If the domain name is relative, it will be relative to the zone\(aqs apex. -.sp -[aliases: \-\-rrset] -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-rrset\-exists\-exact -Require that an RRset exists and contains exactly the RRs with the given -NAME, TYPE, and RDATA. This option can be provided multiple times, each -with one RR in zonefile format, to build up one or more RRsets that is -required to exist. CLASS and TTL can be omitted. -.sp -If the domain name is relative, it will be relative to the zone\(aqs apex. -.sp -[aliases: \-\-rrset\-exact] -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-rrset\-non\-existent -RRset does not exist. This option can be provided multiple times, with -format \fB \fP each, to build up a list of RRs that -specify that no RRs with a specified NAME and TYPE can exist. -.sp -If the domain name is relative, it will be relative to the zone\(aqs apex. -.sp -[aliases: \-\-rrset\-empty] -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-name\-in\-use -Name is in use. This option can be provided multiple times, with format -\fB\fP each, to collect a list of NAMEs that must own at least -one RR. -.sp -Note that this prerequisite is NOT satisfied by empty nonterminals. -.sp -If the domain name is relative, it will be relative to the zone\(aqs apex. -.sp -[aliases: \-\-name\-used] -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-name\-not\-in\-use -Name is not in use. This option can be provided multiple times, with -format \fB\fP each, to collect a list of NAMEs that must NOT -own any RRs. -.sp -Note that this prerequisite IS satisfied by empty nonterminals. -.sp -If the domain name is relative, it will be relative to the zone\(aqs apex. -.sp -[aliases: \-\-name\-unused] -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). Can also be used on the individual sub commands. -.UNINDENT -.SH ARGUMENTS FOR ADD AND DELETE -.INDENT 0.0 -.TP -.B -The RR type to add or delete. -.UNINDENT -.INDENT 0.0 -.TP -.B [RDATA]... -One or more RDATA arguments for \fBadd\fP, and zero or more for -\fBdelete\fP\&. -.sp -Each argument corresponds to a single RR\(aqs RDATA, so beware of (shell and -DNS) quoting rules. -.sp -Each RDATA argument will be parsed as if it was read from a zone file. -.nf -Examples: -\fBdnst update some.example.com add AAAA ::1 2001:db8::\fP -\fBdnst update some.example.com add TXT \(aq\(dqSpacious String\(dq \(dqAnother -string for the same TXT record\(dq\(aq \(aq\(dqThis is another TXT RR\(dq\(aq\fP -.fi -.sp -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/dnst.1 b/doc/manual/build/man/dnst.1 deleted file mode 100644 index a1299bb..0000000 --- a/doc/manual/build/man/dnst.1 +++ /dev/null @@ -1,92 +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 "DNST" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -dnst \- DNS Management Tools -.SH SYNOPSIS -.sp -\fBdnst\fP \fB[OPTIONS]\fP \fB\fP \fB[ARGS]\fP -.SH DESCRIPTION -.sp -Manage various aspects of the Domain Name System (DNS). -.sp -\fBdnst\fP provides a number of commands that perform various tasks related to -managing DNS servers and DNS zones. -.sp -Please consult the manual pages for these individual commands for more -information. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-v, \-\-verbosity -Set the verbosity to 0\-5 or a level name (\fBoff\fP, \fBerror\fP, \fBwarn\fP, -\fBinfo\fP, \fBdebug\fP or \fBtrace\fP). Defaults to \fBwarn\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.INDENT 0.0 -.TP -.B \-V, \-\-version -Print the version. -.UNINDENT -.SH COMMANDS -.INDENT 0.0 -.TP -.B \fI\%dnst\-key2ds\fP (1) -Generate DS RRs from the DNSKEYs in a keyfile. -.TP -.B \fI\%dnst\-keygen\fP (1) -Generate a new key pair for a domain name. -.TP -.B \fI\%dnst\-keyset\fP (1) -Manage DNSSEC signing keys for a domain. -.TP -.B \fI\%dnst\-notify\fP (1) -Send a NOTIFY message to a list of name servers. -.TP -.B \fI\%dnst\-nsec3\-hash\fP (1) -Print out the NSEC3 hash of a domain name. -.TP -.B \fI\%dnst\-signzone\fP (1) -Sign the zone with the given key(s). -.TP -.B \fI\%dnst\-update\fP (1) -Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name. -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/ldns-key2ds.1 b/doc/manual/build/man/ldns-key2ds.1 deleted file mode 100644 index 7473fa9..0000000 --- a/doc/manual/build/man/ldns-key2ds.1 +++ /dev/null @@ -1,77 +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 "LDNS-KEY2DS" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -ldns-key2ds \- Generate DS RRs from the DNSKEYs in a keyfile -.SH SYNOPSIS -.sp -\fBldns\-key2ds\fP \fB[OPTIONS]\fP \fB\fP -.SH DESCRIPTION -.sp -\fBldns\-key2ds\fP is used to transform a public DNSKEY RR to a DS RR. When run -it will read \fB\fP with a DNSKEY RR in it, and it will create a .ds -file with the DS RR in it. -.sp -It prints out the basename for this file (\fBK++\fP). -.sp -By default, it takes a pick of algorithm similar to the key algorithm, -SHA1 for RSASHA1, and so on. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-f -Ignore SEP flag (i.e. make DS records for any key) -.UNINDENT -.INDENT 0.0 -.TP -.B \-n -Write the result DS Resource Record to stdout instead of a file -.UNINDENT -.INDENT 0.0 -.TP -.B \-1 -Use SHA1 as the hash function. -.UNINDENT -.INDENT 0.0 -.TP -.B \-2 -Use SHA256 as the hash function -.UNINDENT -.INDENT 0.0 -.TP -.B \-4 -Use SHA383 as the hash function -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/ldns-keygen.1 b/doc/manual/build/man/ldns-keygen.1 deleted file mode 100644 index 4bf2a93..0000000 --- a/doc/manual/build/man/ldns-keygen.1 +++ /dev/null @@ -1,96 +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 "LDNS-KEYGEN" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -ldns-keygen \- Generate a new key pair for a domain name -.SH SYNOPSIS -.sp -\fBldns\-keygen\fP \fB[OPTIONS]\fP \fB\fP -.SH DESCRIPTION -.sp -\fBldns\-keygen\fP is used to generate a private/public keypair. -.sp -When run, it will create 3 files; a \fB\&.key\fP file with the public DNSKEY, a -\fB\&.private\fP file with the private keydata and a \fB\&.ds\fP file with the DS -record of the DNSKEY record. -.sp -\fBldns\-keygen\fP prints the basename for the key files: \fBK++\fP -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-a -Create a key with this algorithm. Specifying \(aqlist\(aq here gives a list of -supported algorithms. Several alias names are also accepted (from older -versions and other software), the list gives names from the RFC. Also the -plain algorithm number is accepted. -.sp -Note: Unlike the original LDNS, this implementation does not support -creation of symmetric keys (for TSIG). -.UNINDENT -.INDENT 0.0 -.TP -.B \-b -Use this many bits for the key length. -.UNINDENT -.INDENT 0.0 -.TP -.B \-k -When given, generate a key signing key. This just sets the flag field to -257 instead of 256 in the DNSKEY RR in the .key file. -.UNINDENT -.INDENT 0.0 -.TP -.B \-r -Make ldns\-keygen use this file to seed the random generator with. This -will default to /dev/random. -.UNINDENT -.INDENT 0.0 -.TP -.B \-s -ldns\-keygen will create symbolic links named \fB\&.private\fP to the new -generated private key, \fB\&.key\fP to the public DNSKEY and \fB\&.ds\fP to the -file containing DS record data. -.UNINDENT -.INDENT 0.0 -.TP -.B \-f -Force symlinks to be overwritten if they exist. -.UNINDENT -.INDENT 0.0 -.TP -.B \-v -Show the version and exit -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/ldns-notify.1 b/doc/manual/build/man/ldns-notify.1 deleted file mode 100644 index 4f9ca4e..0000000 --- a/doc/manual/build/man/ldns-notify.1 +++ /dev/null @@ -1,98 +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 "LDNS-NOTIFY" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -ldns-notify \- Send a NOTIFY message to a list of name servers -.SH SYNOPSIS -.sp -\fBldns\-notify\fP \fB[OPTIONS]\fP \fB\-z \fP \fB...\fP -.SH DESCRIPTION -.sp -\fBldns\-notify\fP sends a NOTIFY packet to the specified name servers. A name -server can be specified as a domain name or IP address. -.sp -This tells them that an updated zone is available at the primaries. It can -perform TSIG signatures, and it can add a SOA serial number of the updated -zone. If a server already has that serial number it will disregard the message. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-z -The zone that is updated. -.UNINDENT -.INDENT 0.0 -.TP -.B \-I
-Source IP to send the message from. -.UNINDENT -.INDENT 0.0 -.TP -.B \-s -Append a SOA record indicating the serial number of the updated zone. -.UNINDENT -.INDENT 0.0 -.TP -.B \-p -Destination port to send the UDP packet to. Defaults to 53. -.UNINDENT -.INDENT 0.0 -.TP -.B \-y -A base64 TSIG key and optional algorithm to use for the NOTIFY message. -The algorithm defaults to hmac\-sha512. -.UNINDENT -.INDENT 0.0 -.TP -.B \-d -Print verbose debug information. The query that is sent and the query -that is received. -.UNINDENT -.INDENT 0.0 -.TP -.B \-r -Specify the maximum number of retries before notify gives up trying to -send the UDP packet. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h -Print the help text and exit. -.UNINDENT -.INDENT 0.0 -.TP -.B \-v -Print the version and exit. -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/ldns-nsec3-hash.1 b/doc/manual/build/man/ldns-nsec3-hash.1 deleted file mode 100644 index 4d2cf0a..0000000 --- a/doc/manual/build/man/ldns-nsec3-hash.1 +++ /dev/null @@ -1,65 +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 "LDNS-NSEC3-HASH" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -ldns-nsec3-hash \- Print out the NSEC3 hash of a domain name -.SH SYNOPSIS -.sp -\fBldns\-nsec3\-hash\fP \fB[OPTIONS]\fP \fB\fP -.SH DESCRIPTION -.sp -\fBldns\-nsec3\-hash\fP is used to print out the NSEC3 hash for the given domain name. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-a -Use the given algorithm number for the hash calculation. Defaults to -1 (SHA\-1). -.UNINDENT -.INDENT 0.0 -.TP -.B \-s -Use the given salt for the hash calculation. The salt value should be -in hexadecimal format. Defaults to an empty salt. -.UNINDENT -.INDENT 0.0 -.TP -.B \-t -Use the given number of additional iterations for the hash -calculation. Defaults to 0. Note that this differs to the default value -used by the original \fIldns\-nsec3\-hash\fP command to comply with latest -best practice per RFC 9276. -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/ldns-signzone.1 b/doc/manual/build/man/ldns-signzone.1 deleted file mode 100644 index 7158359..0000000 --- a/doc/manual/build/man/ldns-signzone.1 +++ /dev/null @@ -1,242 +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 "LDNS-SIGNZONE" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -ldns-signzone \- Sign the zone with the given key(s) -.SH SYNOPSIS -.sp -\fBldns\-signzone\fP \fB[OPTIONS]\fP \fB\fP \fB...\fP -.SH DESCRIPTION -.sp -\fBldns\-signzone\fP is used to generate a DNSSEC signed zone. When run it will -create a new zonefile that contains RRSIG and NSEC(3) resource records, as -specified in RFC 4033, RFC 4034, RFC 4035 and RFC 5155. -.sp -This is a re\-implementation of the original \fBldns\-signzone\fP which is largely -compatible with the original with some exceptions which are noted below. -.SH ARGUMENTS -.INDENT 0.0 -.TP -.B -The zonefile to sign. -.sp -Note: Unlike the original LDNS, any existing NSEC(3), NSEC3PARAM and/or -RRSIG resource records will be skipped when loading the zonefile. -.sp -Note: Unlike the original LDNS, the origin must be explicitly specified -either via an \fB$ORIGIN\fP directive in the zonefile or using the \fB\-o\fP -command line argument. -.UNINDENT -.INDENT 0.0 -.TP -.B ... -The keys to sign the zonefile with. -.sp -Keys must be specified by their base file name (usually -\fBK++\fP), i.e. WITHOUT the \fB\&.private\fP or \fB\&.key\fP -extension, with an optional path prefix. The \fB\&.private\fP file is -required to exist. The \fB\&.key\fP file will be used if a \fBDNSKEY\fP record -corresponding to the \fB\&.private\fP key cannot be found. -.sp -Multiple keys can be specified. Key Signing Keys are used as such when -they are either already present in the zone, or specified in a \fB\&.key\fP -file, and have the Secure Entry Point flag set. -.INDENT 7.0 -.TP -.B Note: Unlike the original LDNS: -.INDENT 7.0 -.IP \(bu 2 -Public keys corresponding to \fB\&.private\fP key MUST be supplied, -either as DNSKEY RRs in the given zone or as \fB\&.key\fP files. This -implementation is not able to generate missing public keys. -.IP \(bu 2 -Supported DNSKEY algorithms are the ones supported by the -domain crate. Supported algorithms include RSASHA256, -ECDSAP256SHA256, and ED25519 but exclude RSHASHA1 and -RSASHA1\-NSEC3\-SHA1. -.UNINDENT -.UNINDENT -.UNINDENT -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-a -Sign the DNSKEY records with all keys. By default it is signed with a -minimal number of keys, to keep the response size for the DNSKEY query -small, only the SEP keys that are passed are used. If there are no -SEP keys, the DNSKEY RRset is signed with the non\-SEP keys. This option -turns off the default and all keys are used to sign the DNSKEY RRset. -.UNINDENT -.INDENT 0.0 -.TP -.B \-b -Augments the zone and the RR\(aqs with extra comment texts for a more -readable layout, easier to debug. NSEC3 records will have the unhashed -owner names in the comment text. -.sp -Without this option, only DNSKEY RR\(aqs will have their Key Tag annotated -in the comment text. -.sp -Note: This option is ignored if the \fB\-f \-\fP is used. -.sp -Note: Unlike the original LDNS, DS records are printed without a -bubblebabble version of the data in the comment text, and some ordering -for easier consumption by humans is ONLY done if \fB\-b\fP is in effect, -e.g. ordering RRSIGs after the record they cover, and ordering NSEC3 -hashes by unhashed owner name rather than by hashed owner name. -.UNINDENT -.INDENT 0.0 -.TP -.B \-d -Do not add used keys to the resulting zonefile. -.UNINDENT -.INDENT 0.0 -.TP -.B \-e -Set the expiration timestamp of signatures to the given date (and time, -optionally, see \fI\%Engine Options\fP for details about acceptable -formats for the given \fB\fP value). Defaults to 4 weeks from now. -.UNINDENT -.INDENT 0.0 -.TP -.B \-f -Write signed zone to file. Use \fB\-f \-\fP to output to stdout. Defaults to -\fB.signed\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h -Print the help text. -.UNINDENT -.INDENT 0.0 -.TP -.B \-i -Set the inception timestamp of signatures to the given date (and time, -optionally, see \fI\%Engine Options\fP for details about acceptable -formats for the given \fB\fP value). Defaults to now. -.UNINDENT -.INDENT 0.0 -.TP -.B \-n -Use NSEC3 instead of NSEC. If specified, you can use extra options (see -\fI\%NSEC3 options\fP). -.UNINDENT -.INDENT 0.0 -.TP -.B \-o -Use this owner name as the apex of the zone. -.sp -If not specified the owner name of the first SOA record will be used as -the apex of the zone. -.UNINDENT -.INDENT 0.0 -.TP -.B \-u -Set the SOA serial in the resulting zonefile to the given number of -seconds since January 1st 1970. -.UNINDENT -.INDENT 0.0 -.TP -.B \-u -Sign with every unique algorithm in the provided keys. The DNSKEY set is -signed with all the SEP keys, plus all the non\-SEP keys that have an -algorithm that was not present in the SEP key set. -.UNINDENT -.INDENT 0.0 -.TP -.B \-v -Print the version and exit. -.UNINDENT -.INDENT 0.0 -.TP -.B \-z <[SCHEME:]HASH> -Add a ZONEMD resource record. Accepts both mnemonics and numbers. -This option can be provided more than once to add multiple ZONEMD RRs. -However, only one per scheme\-hash tuple will be added. -.nf -HASH supports \fBsha384\fP (1) and \fBsha512\fP (2). -SCHEME supports \fBsimple\fP (1), the default. -.fi -.sp -.UNINDENT -.INDENT 0.0 -.TP -.B \-Z -Allow adding ZONEMD RRs without signing the zone. With this option, the -... argument becomes optional and determines whether to sign the -zone. -.UNINDENT -.SH NSEC3 OPTIONS -.sp -The following options can be used with \fB\-n\fP to override the default NSEC3 -settings used. -.INDENT 0.0 -.TP -.B \-a -Specify the hashing algorithm. Only SHA\-1 is supported. -.UNINDENT -.INDENT 0.0 -.TP -.B \-t -Set the number of extra hash iterations. Defaults to 0. -.sp -Note: The default value differs to that of the original LDNS which has a -default of 1. The new default value is in accordance with RFC 9276 -\(dqGuidance for NSEC3 Parameter Settings\(dq. -.UNINDENT -.INDENT 0.0 -.TP -.B \-s -Specify the salt as a hex string. Defaults to \fB\-\fP, meaning empty salt. -.UNINDENT -.INDENT 0.0 -.TP -.B \-p -Set the opt\-out flag on all NSEC3 RRs. -.UNINDENT -.SH ENGINE OPTIONS -.sp -Unlike the original LDNS, OpenSSL engines and their associated command line -arguments are not supported by this re\-implementation. -.SH DATES -.sp -A date can be a UNIX timestamp as seconds since the Epoch (1970\-01\-01 -00:00 UTC), or of the form \fB\fP\&. -.sp -Note: RRSIG inception and expiration timestamps in the signed output zone will -be in unsigned decimal integer form (indicating seconds since 1 January 1970 -00:00:00 UTC) unlike the original LDNS which produced timestamps in the form -\fBYYYYMMDDHHmmSS\fP\&. -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/doc/manual/build/man/ldns-update.1 b/doc/manual/build/man/ldns-update.1 deleted file mode 100644 index f88eb19..0000000 --- a/doc/manual/build/man/ldns-update.1 +++ /dev/null @@ -1,83 +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 "LDNS-UPDATE" "1" "Apr 09, 2026" "0.2.0-alpha1" "dnst" -.SH NAME -ldns-update \- Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name -.SH SYNOPSIS -.sp -\fBldns\-update\fP \fB\fP \fB[ZONE]\fP \fB\fP -\fB[ ]\fP -.SH DESCRIPTION -.sp -\fBldns\-update\fP sends a dynamic update packet to update an IP (or delete all -existing IPs) for a domain name. -.SH OPTIONS -.INDENT 0.0 -.TP -.B -The domain name to update the IP address of -.UNINDENT -.INDENT 0.0 -.TP -.B -The zone to send the update to (if omitted, derived from SOA record) -.UNINDENT -.INDENT 0.0 -.TP -.B -The IP to update the domain with (\fBnone\fP to remove any existing IPs) -.UNINDENT -.INDENT 0.0 -.TP -.B -TSIG key name -.UNINDENT -.INDENT 0.0 -.TP -.B -TSIG algorithm (e.g. \(dqhmac\-sha256\(dq) -.UNINDENT -.INDENT 0.0 -.TP -.B -Base64 encoded TSIG key data. -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -Print the help text (short summary with \fB\-h\fP, long help with -\fB\-\-help\fP). -.UNINDENT -.SH AUTHOR -NLnet Labs -.SH COPYRIGHT -2024–2026, NLnet Labs -.\" Generated by docutils manpage writer. -. diff --git a/pkg/generate-man-pages.sh b/pkg/generate-man-pages.sh new file mode 100755 index 0000000..b87e04c --- /dev/null +++ b/pkg/generate-man-pages.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +set -e + +cd doc/manual + +tempdir=$(mktemp -d venv.XXXX) + +uv venv "$tempdir" +# shellcheck disable=1091 +source "$tempdir/bin/activate" + +uv pip install -r source/requirements.txt + +make man diff --git a/pkg/rpmsign-only.sh b/pkg/rpmsign-only.sh new file mode 100755 index 0000000..9a9c11e --- /dev/null +++ b/pkg/rpmsign-only.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash + +set -e + +# if the last argument is an rpm file, use rpmsign +# shellcheck disable=2199 +if [[ "${@: -1}" == *.rpm ]]; then + rpmsign "$@" +else + # shellcheck disable=2145 + echo "rpmsign-only: Not signing ${@: -1}" >&2 +fi