1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
.. Open Infrastructure: service-tools
.. Copyright (C) 2014-2023 Daniel Baumann <daniel.baumann@open-infrastructure.net>
..
.. SPDX-License-Identifier: GPL-3.0+
..
.. This program is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, either version 3 of the License, or
.. (at your option) any later version.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <https://www.gnu.org/licenses/>.
===================
dehydrated-nsupdate
===================
---------------------------------------
dehydrated hook for dns-01 verification
---------------------------------------
:manual section: 1
:manual group: Open Infrastructure
Synopsis
========
| **dehydrated-nsupdate**
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.
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
========
**dehydrated-nsupdate** has the following features:
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
------------
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.
Proper removal of TXT records
-----------------------------
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
=====
dehydrated-hook(1) is a prerequisite for dehydrated-nsupdate.
Installation
------------
| 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 (first 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
=====
The following files are used:
/etc/dehydrated/tsig.key:
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 location of the global TSIG key to be used (default: /etc/dehydrated/tsig.key).
See also
========
| dehydrated(1),
| dehydrated-cron(1),
| dehydrated-hook(1).
Homepage
========
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>.
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.
|
