summaryrefslogtreecommitdiffstats
path: root/dehydrated/share
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@open-infrastructure.net>2022-06-14 05:24:57 +0000
committerDaniel Baumann <daniel.baumann@open-infrastructure.net>2022-06-14 11:59:26 +0000
commite89eb80f67b545e575fd9349b696f59558514b90 (patch)
tree346d0ef07d2e73add847053d4ee02164a4d46ea5 /dehydrated/share
parentHandling comments in TSIG keyfiles in dehydrated-nsupdate to support disablin... (diff)
downloadservice-tools-e89eb80f67b545e575fd9349b696f59558514b90.tar.xz
service-tools-e89eb80f67b545e575fd9349b696f59558514b90.zip
Completing existing dehydrated-tools manpages.
Signed-off-by: Daniel Baumann <daniel.baumann@open-infrastructure.net>
Diffstat (limited to 'dehydrated/share')
-rw-r--r--dehydrated/share/man/dehydrated-cron.1.rst36
-rw-r--r--dehydrated/share/man/dehydrated-hook.1.rst49
-rw-r--r--dehydrated/share/man/dehydrated-nsupdate.1.rst127
3 files changed, 133 insertions, 79 deletions
diff --git a/dehydrated/share/man/dehydrated-cron.1.rst b/dehydrated/share/man/dehydrated-cron.1.rst
index c060127..cd93a30 100644
--- a/dehydrated/share/man/dehydrated-cron.1.rst
+++ b/dehydrated/share/man/dehydrated-cron.1.rst
@@ -36,12 +36,25 @@ Synopsis
Description
===========
-**dehydrated** is a client for ACME-based Certificate Authorities, such as
-LetsEncrypt. It can be used to request and obtain TLS certificates from an
-ACME-based certificate authority.
+**dehydrated** is a client for ACME-based Certificate Authorities, such as LetsEncrypt. It can be used to request and obtain TLS certificates from an ACME-based certificate authority.
+
+The **dehydrated-cron** script runs dehydrated once per day and on system reboot for an automatic certificate renewal.
+
+It uses the dehydrated '--keep-going' option to keep going after encountering an error while creating/renewing multiple certificates. Afterwards it also removes all unused certificates by using the dehydrated '--cleanup-delete' option.
+
+Usage
+=====
+
+Installation
+------------
+
+| sudo ln -s /usr/bin/dehydrated-cron /etc/cron.d/dehydrated
+
+Removal
+-------
+
+| sudo rm -f /etc/cron.d/dehydrated
-The **dehydrated-cron** script runs dehydrated once per day and on system
-reboot for an automatic certificate renewal.
Files
=====
@@ -67,21 +80,16 @@ See also
Homepage
========
-More information about service-tools and the Open Infrastructure project can be
-found on the homepage (https://open-infrastructure.net).
+More information about service-tools and the Open Infrastructure project can be found on the homepage (https://open-infrastructure.net).
Contact
=======
-Bug reports, feature requests, help, patches, support and everything else are
-welcome on the Open Infrastructure Software Mailing List
-<software@lists.open-infrastructure.net>.
+Bug reports, feature requests, help, patches, support and everything else are welcome on the Open Infrastructure Software Mailing List <software@lists.open-infrastructure.net>.
-Debian specific bugs can also be reported in the Debian Bug Tracking System
-(https://bugs.debian.org).
+Debian specific bugs can also be reported in the Debian Bug Tracking System (https://bugs.debian.org).
Authors
=======
-service-tools were written by Daniel Baumann
-<daniel.baumann@open-infrastructure.net> and others.
+service-tools were written by Daniel Baumann <daniel.baumann@open-infrastructure.net> and others.
diff --git a/dehydrated/share/man/dehydrated-hook.1.rst b/dehydrated/share/man/dehydrated-hook.1.rst
index 607be92..de63127 100644
--- a/dehydrated/share/man/dehydrated-hook.1.rst
+++ b/dehydrated/share/man/dehydrated-hook.1.rst
@@ -36,43 +36,45 @@ Synopsis
Description
===========
-**dehydrated** is a client for ACME-based Certificate Authorities, such as
-LetsEncrypt. It can be used to request and obtain TLS certificates from an
-ACME-based certificate authority.
+**dehydrated** is a client for ACME-based Certificate Authorities, such as LetsEncrypt. It can be used to request and obtain TLS certificates from an ACME-based certificate authority.
-The **dehydrated-hook** makes it possible to run multiple scripts in every
-stage within the process of creating, signing and deploying a certificate.
+The **dehydrated-hook** makes it possible to run multiple scripts in every stage within the process of creating, signing and deploying a certificate.
-Scripts need to be placed in /etc/dehydrated/hook.d and need to be prefixed
-with the name of the handler, e.g. exit_hook.example1 or exit_hook.example2.sh
+Scripts need to be placed in /etc/dehydrated/hook.d and need to be prefixed with the name of the handler, e.g. exit_hook.example1 or exit_hook.example2.sh
Handlers
========
The following **dehydrated** handlers are available:
+|
| deploy_challenge
-
| clean_challenge
-
| sync_cert
-
| deploy_cert
-
| deploy_ocsp
-
| unchanged_cert
-
| invalid_challenge
-
| request_failure
-
| generate_csr
-
| startup_hook
-
| exit_hook
+Usage
+=====
+
+Installation
+------------
+
+| sudo echo HOOK="/usr/bin/dehydrated-hook" > /etc/dehydrated/conf.d/zz-hook.sh
+| sudo mkdir -p /etc/dehydrated/hook.d
+
+Removal
+-------
+
+| sudo rm -f /etc/dehydrated/conf.d/zz-hook.sh
+| sudo rmdir /etc/dehydrated/hook.d
+
Files
=====
@@ -91,21 +93,16 @@ See also
Homepage
========
-More information about service-tools and the Open Infrastructure project can be
-found on the homepage (https://open-infrastructure.net).
+More information about service-tools and the Open Infrastructure project can be found on the homepage (https://open-infrastructure.net).
Contact
=======
-Bug reports, feature requests, help, patches, support and everything else are
-welcome on the Open Infrastructure Software Mailing List
-<software@lists.open-infrastructure.net>.
+Bug reports, feature requests, help, patches, support and everything else are welcome on the Open Infrastructure Software Mailing List <software@lists.open-infrastructure.net>.
-Debian specific bugs can also be reported in the Debian Bug Tracking System
-(https://bugs.debian.org).
+Debian specific bugs can also be reported in the Debian Bug Tracking System (https://bugs.debian.org).
Authors
=======
-service-tools were written by Daniel Baumann
-<daniel.baumann@open-infrastructure.net> and others.
+service-tools were written by Daniel Baumann <daniel.baumann@open-infrastructure.net> and others.
diff --git a/dehydrated/share/man/dehydrated-nsupdate.1.rst b/dehydrated/share/man/dehydrated-nsupdate.1.rst
index db58d5c..059a269 100644
--- a/dehydrated/share/man/dehydrated-nsupdate.1.rst
+++ b/dehydrated/share/man/dehydrated-nsupdate.1.rst
@@ -36,15 +36,12 @@ Synopsis
Description
===========
-**dehydrated** is a client for ACME-based Certificate Authorities, such as
-LetsEncrypt. It can be used to request and obtain TLS certificates from an
-ACME-based certificate authority.
+**dehydrated** is a client for ACME-based Certificate Authorities, such as LetsEncrypt. It can be used to request and obtain TLS certificates from an ACME-based certificate authority.
-The **dehydrated-nsupdate** hook implements the dns-01 verification. It is
-typically run together with **dehydrated-hook** as:
+The **dehydrated-nsupdate** hook implements the dns-01 verification. It is typically run together with **dehydrated-hook** as:
+|
| /etc/dehydrated/hook.d/deploy_challenge.nsupdate
-
| /etc/dehydrated/hook.d/clean_challenge.nsupdate
Features
@@ -52,32 +49,87 @@ Features
**dehydrated-nsupdate** has the following features:
-| **automatic nameserver detection**
-| **dehydrated-nsupdate** automatically finds and updates all authoritative
-| nameservers for a given record by looking up the records in the DNS by itself,
-| supporting IPv6-only, IPv4-only, and dual-stacked environments.
+Automatic nameserver detection (IPv4 and IPv6)
+----------------------------------------------
+
+dehydrated-nsupdate automatically finds and updates all authoritative nameservers for a given record by looking up the records in the DNS by itself, supporting IPv6-only, IPv4-only, and dual-stacked environments.
+
+Proper CNAME support
+--------------------
+
+dehydrated-nsupdate follows CNAMEs delegating the TXT record update to another zone.
+
+Handling nameserver subzone shortcuts
+-------------------------------------
+
+dehydrated-nsupdate correctly handles authoritative nameserver answers that (wrongly) give shortcut answers for their own zones when using multiple authoritative subzones on the same nameservers.
+
+TSIG support
+------------
-| **proper CNAME support**
-| **dehydrated-nsupdate** follows CNAMEs delegating the TXT record creation to
-| another zone.
+dehydrated-nsupdate uses TSIG, if provided, to authenticate itself to the nameserver. Additionally to a global TSIG to be used for all record updates, separate TSIGs can individually be specified per record, per zone, and per nameserver.
-| **handling nameserver subzone shortcuts**
-| **dehydrated-nsupdate** correctly handles authoritative nameserver
-| answers that give shortcut answers for their own zones when using
-| multiple subzones.
+Proper removal of TXT records
+-----------------------------
-| **TSIG support**
-| **dehydrated-nsupdate** uses TSIG, if provided, to authenticate
-| itself to the nameserver.
+dehydrated-nsupdate removes records after succesfull verification.
+
+bind9-dnsutils and knot-dnsutils support
+----------------------------------------
+
+dehydrated-nsupdate works with both nsupdate (bind9) and knsupdate (knot).
+
+IDN handling
+------------
+
+dehydrated-nsupdate works with IDN domains by not expanding the punycode to update the correct records.
+
+Usage
+=====
-| **proper removal of TXT records**
-| **dehydrated-nsupdate** removes records after succesfull verification.
+dehydrated-hook(1) is a prerequisite for dehydrated-nsupdate.
-| **bind9-dnsutils and knot-dnsutils support*
-| **dehydrated-nsupdate** works with both nsupdate (bind9) and knsupdate (knot).
+Installation
+------------
-| **IDN handling**
-| **dehydrated-nsupdate** works with IDN domains by not expanding the punycode.
+| sudo echo CHALLENGETYPE="dns-01" > /etc/dehydrated/conf.d/zz-challengetype.sh
+| sudo ln -s /usr/bin/dehydrated-nsupdate /etc/dehydrated/hook.d/deploy_challenge.nsupdate
+| sudo ln -s /usr/bin/dehydrated-nsupdate /etc/dehydrated/hook.d/clean_challenge.nsupdate
+
+Removal
+-------
+
+| sudo rm -f /etc/dehydrated/conf.d/zz-challengetype.sh
+| sudo rm -f /etc/dehydrated/hook.d/deploy_challenge.nsupdate
+| sudo rm -f /etc/dehydrated/hook.d/clean_challenge.nsupdate
+
+Configuration
+=============
+
+Depending on the nameserver requirements, dehydrated-nsupdate can send record updates either unauthenticated or using a TSIG (recommended).
+
+A TSIG file consists of one single line containing the key (nsupdate/knsupdate do not allow comments), e.g.:
+
+|
+| hmac-sha512:example:/LXPy6U8HAWA+QmvulZWm0owsQgNf8qJ5MNLTvirzvVtDb+PzLKoBmVHjnL6TUffkvRYa7Do448dSIrAuJ1G/A==
+
+Instead of using a global TSIG for all record update, specific TSIGs can be used individually per record, zone, and nameserver.
+
+The lookup hierarchy is the following (earliest match wins):
+
+|
+| /etc/dehydrated/tsig/${record}.key
+| /etc/dehydrated/tsig/${zone}.key
+| /etc/dehydrated/tsig/${nameserver}.key
+| /etc/dehydrated/tsig.key
+|
+| TSIG_KEYFILE variable in /etc/default/dehydrated-nsupdate/*
+| TSIG_KEYFILE variable in /etc/default/dehydrated-nsupdate
+
+In order to explicitly not use a TSIG for a specific record, zone, or nameserver, an empty keyfile or a keyfile with only comments can be used, e.g.:
+
+|
+| echo "# disabled" > /etc/dehydrated/tsig/ns1.example.org.key
Files
=====
@@ -85,11 +137,13 @@ Files
The following files are used:
/etc/dehydrated/tsig.key:
- default location for the TSIG key to be used.
+ default location for global TSIG key to be used.
+
+/etc/dehydrated/tsig/${record}.key, /etc/dehydrated/tsig/${zone}.key, /etc/dehydrated/tsig/${nameserver}.key:
+ default locations for specific TSIG keys to be used individually per record, zone, or nameserver.
-/etc/default/dehydrated-nsupdate, /etc/default/dehydrated-nsupdate.d/*:
- configuration file, currently only used for TSIG_KEYFILE variable pointing
- to the tsig.key file to be used (default: /etc/dehydrated/tsig.key).
+/etc/default/dehydrated-nsupdate, /etc/default/dehydrated-nsupdate.d/\*:
+ configuration file, currently only used for TSIG_KEYFILE variable pointing to the location of the global TSIG key to be used (default: /etc/dehydrated/tsig.key).
See also
========
@@ -101,21 +155,16 @@ See also
Homepage
========
-More information about service-tools and the Open Infrastructure project can be
-found on the homepage (https://open-infrastructure.net).
+More information about service-tools and the Open Infrastructure project can be found on the homepage (https://open-infrastructure.net).
Contact
=======
-Bug reports, feature requests, help, patches, support and everything else are
-welcome on the Open Infrastructure Software Mailing List
-<software@lists.open-infrastructure.net>.
+Bug reports, feature requests, help, patches, support and everything else are welcome on the Open Infrastructure Software Mailing List <software@lists.open-infrastructure.net>.
-Debian specific bugs can also be reported in the Debian Bug Tracking System
-(https://bugs.debian.org).
+Debian specific bugs can also be reported in the Debian Bug Tracking System (https://bugs.debian.org).
Authors
=======
-service-tools were written by Daniel Baumann
-<daniel.baumann@open-infrastructure.net> and others.
+service-tools were written by Daniel Baumann <daniel.baumann@open-infrastructure.net> and others.