summaryrefslogtreecommitdiffstats
path: root/dehydrated
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--dehydrated/TODO4
-rwxr-xr-xdehydrated/bin/dehydrated-nsupdate44
-rwxr-xr-xdehydrated/share/hooks/exit_hook.service-reload8
-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
6 files changed, 174 insertions, 94 deletions
diff --git a/dehydrated/TODO b/dehydrated/TODO
index 1576ab5..9af54a5 100644
--- a/dehydrated/TODO
+++ b/dehydrated/TODO
@@ -1,9 +1,7 @@
TODO
====
+ * add manpages for individual dehydrated hooks
* use /etc/default for dehydrated-cron
* use /etc/default for dehydrated-hook
- * maybe handling multiple different CNAMEs
- (not sure if letsencrypt allows that, however, dehydrated-nsupdate only
- processes one CNAME)
* use settings from _dehydrated.$domain.$tld
diff --git a/dehydrated/bin/dehydrated-nsupdate b/dehydrated/bin/dehydrated-nsupdate
index 96c95eb..05027ab 100755
--- a/dehydrated/bin/dehydrated-nsupdate
+++ b/dehydrated/bin/dehydrated-nsupdate
@@ -109,12 +109,12 @@ NAMESERVERS_IPV4=""
for NAMESERVER in ${NAMESERVERS}
do
- if [ -n "$(${DIG} +nocomments +noquestion +short AAAA ${NAMESERVER})" ]
+ if [ -n "$(${DIG} +nocomments +noquestion +short AAAA "${NAMESERVER}")" ]
then
NAMESERVERS_IPV6="${NAMESERVERS_IPV6} ${NAMESERVER}"
fi
- if [ -n "$(${DIG} +nocomments +noquestion +short A ${NAMESERVER})" ]
+ if [ -n "$(${DIG} +nocomments +noquestion +short A "${NAMESERVER}")" ]
then
NAMESERVERS_IPV4="${NAMESERVERS_IPV4} ${NAMESERVER}"
fi
@@ -133,16 +133,44 @@ then
NAMESERVERS="${NAMESERVERS} ${NAMESERVERS_IPV4}"
fi
-NAMESERVERS="$(echo ${NAMESERVERS} | sed -e 's| |\n|g' | sort -u -V)"
+NAMESERVERS="$(echo "${NAMESERVERS}" | sed -e 's| |\n|g' | sort -u -V)"
# update nameservers
-if [ -n "${TSIG_KEYFILE}" ] && [ -e "${TSIG_KEYFILE}" ]
-then
- NSUPDATE_OPTIONS="-k ${TSIG_KEYFILE}"
-fi
-
for NAMESERVER in ${NAMESERVERS}
do
+ if [ -e "/etc/dehydrated/tsig/$(basename "${TXT_RECORD}" .).key" ]
+ then
+ # specific key per record
+ KEY="/etc/dehydrated/tsig/$(basename "${TXT_RECORD}" .).key"
+ elif [ -e "/etc/dehydrated/tsig/$(basename "${ZONE}" .).key" ]
+ then
+ # specific key per zone
+ KEY="/etc/dehydrated/tsig/$(basename "${ZONE}" .).key"
+ elif [ -e "/etc/dehydrated/tsig/$(basename "${NAMESERVER}" .).key" ]
+ then
+ # specific key per nameserver
+ KEY="/etc/dehydrated/tsig/$(basename "${NAMESERVER}" .).key"
+ elif [ -e "/etc/dehydrated/tsig.key" ]
+ then
+ # global key (filesystem)
+ KEY="/etc/dehydrated/tsig.key"
+ elif [ -n "${TSIG_KEYFILE}" ] && [ -e "${TSIG_KEYFILE}" ]
+ then
+ # global key (conffile)
+ KEY="${TSIG_KEYFILE}"
+ else
+ # no key
+ KEY=""
+ fi
+
+ # ignoring comments to allow empty keyfiles to disable TSIG individually
+ TSIG="$(grep -sv '^#' "${KEY}" || true)"
+
+ if [ -n "${KEY}" ] && [ -n "${TSIG}" ]
+ then
+ NSUPDATE_OPTIONS="-k ${KEY}"
+ fi
+
echo -n " + sending '${HOOK_ACTION}' for ${TXT_RECORD} to ${NAMESERVER}..."
# shellcheck disable=SC2086
diff --git a/dehydrated/share/hooks/exit_hook.service-reload b/dehydrated/share/hooks/exit_hook.service-reload
index ebe2d23..486c62f 100755
--- a/dehydrated/share/hooks/exit_hook.service-reload
+++ b/dehydrated/share/hooks/exit_hook.service-reload
@@ -27,17 +27,17 @@ echo " + Reloading services..."
for SERVICE in ${SERVICES}
do
- if service ${SERVICE} status > /dev/null 2>&1
+ if service "${SERVICE}" status > /dev/null 2>&1
then
echo -n " + ${SERVICE}:"
- service ${SERVICE} reload || service ${SERVICE} restart
+ service "${SERVICE}" reload || service "${SERVICE}" restart
echo " done."
fi
done
-if service kresd@1 status > /dev/null 2>&1
+if grep -r -qs '^net.tls' /etc/knot-resolver/* && service kresd@1 status > /dev/null 2>&1
then
NUMBER="$(systemctl | grep -c 'kresd@[0-9].service')"
@@ -48,7 +48,7 @@ then
for NUMBER in $(seq 1 "${NUMBER}")
do
echo -n " #${NUMBER}"
- service kresd@${NUMBER} restart
+ service kresd@"${NUMBER}" restart
done
echo " done."
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.