diff options
Diffstat (limited to 'dehydrated/share/man')
| -rw-r--r-- | dehydrated/share/man/dehydrated-cron.1.rst | 36 | ||||
| -rw-r--r-- | dehydrated/share/man/dehydrated-hook.1.rst | 49 | ||||
| -rw-r--r-- | dehydrated/share/man/dehydrated-nsupdate.1.rst | 127 |
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. |