<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/"><channel><title>TSIG | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/tsig/</link><description>Hands-on DevOps and homelab content: Kubernetes clusters, self-hosted services, CI/CD pipelines and infrastructure as code, by Patrick de Ruiter of We Build Your Cloud.</description><language>en</language><image><url>https://blog.bsdserver.nl/images/app-icon.svg</url><title>A DevOps Blog</title><link>https://blog.bsdserver.nl/</link></image><lastBuildDate>Wed, 18 Nov 2026 09:00:00 +0100</lastBuildDate><atom:link href="https://blog.bsdserver.nl/tag/tsig/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>Setting Up Dynamic DNS Updates with BIND and TSIG Authentication</title><link>https://blog.bsdserver.nl/setting-up-dynamic-dns-updates-with-bind-and-tsig-authentication/</link><guid isPermaLink="false">693b6c4e79eb54000160a567</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:13:50 +0000</pubDate><description>Dynamic DNS (DDNS) allows automated systems to update DNS records in real-time.</description><category>BIND</category><category>DNS</category><category>Dynamic DNS</category><category>TSIG</category><category>DHCP</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-dyndns-tsig.png" medium="image"/><content:encoded><![CDATA[<p>Dynamic DNS (DDNS) allows automated systems to update DNS records in real-time. DHCP servers register client hostnames, Kubernetes publishes services, and ACME clients add challenge records, all without anyone editing a zone file.</p>
<p>This post sets up BIND to accept those updates securely with TSIG (Transaction Signature) keys: one key per client, each limited to the names and record types it needs. It ends with Kea DHCP registering every lease in DNS.</p>
<h2 id="why-dynamic-dns-with-tsig">Why Dynamic DNS with TSIG? <a class="anchor" data-pagefind-ignore href="#why-dynamic-dns-with-tsig" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>No zone file editing</strong>: records change through the DNS protocol itself, from scripts or services.</li>
<li><strong>Authenticated</strong>: only clients holding the right key can change anything.</li>
<li><strong>Fine-grained</strong>: <code>update-policy</code> limits each key to specific names and record types.</li>
<li><strong>Standard</strong>: <code>nsupdate</code>, Kea, external-dns and ACME clients all speak it.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when records change often or are owned by software: DHCP leases, Kubernetes services, ACME DNS-01 challenges.</li>
<li><strong>Skip it</strong> for zones that only change by hand or through configuration management. A static zone file in Git is easier to review, and a dynamic zone should not be edited by hand (see <a href="#managing-journal-files">Managing Journal Files</a>).</li>
</ul>
<h2 id="how-dynamic-dns-works">How Dynamic DNS Works <a class="anchor" data-pagefind-ignore href="#how-dynamic-dns-works" aria-label="Link to this section">#</a></h2>
<p>Dynamic DNS updates use the DNS UPDATE protocol (RFC 2136). A client sends an update request to the authoritative DNS server, which validates the request and modifies the zone. TSIG keys provide cryptographic authentication to ensure only authorized clients can make changes.</p>
<p>The process:</p>
<ol>
<li>Client generates an update request</li>
<li>Client signs the request with a TSIG key</li>
<li>Server receives and validates the signature</li>
<li>Server applies the update to the zone</li>
<li>Server responds with success or error</li>
</ol>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>TSIG key</td>
					<td>Both sides, same name and secret</td>
					<td>Signs the update; the server checks the signature.</td>
			</tr>
			<tr>
					<td>Zone (<code>type primary</code>) with <code>allow-update</code> / <code>update-policy</code></td>
					<td>BIND</td>
					<td>Decides which key may change which names and types.</td>
			</tr>
			<tr>
					<td>Journal (<code>.jnl</code>)</td>
					<td>BIND, next to the zone file</td>
					<td>Records each update; BIND merges it into the zone file later.</td>
			</tr>
			<tr>
					<td>Update client</td>
					<td><code>nsupdate</code>, Kea D2, external-dns</td>
					<td>Builds and sends the signed update.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client signs update → BIND checks key → checks policy → writes journal → answers with the new record.</p>
<h2 id="generating-tsig-keys">Generating TSIG Keys <a class="anchor" data-pagefind-ignore href="#generating-tsig-keys" aria-label="Link to this section">#</a></h2>
<p>A TSIG key is a shared secret with a name. The server identifies the client by the key name, so the name matters as much as the secret.</p>
<p>Create a dedicated key for dynamic updates and save it where <code>named.conf</code> will include it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p /etc/named/keys
</span></span><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 ddns-key &gt; /etc/named/keys/ddns.key
</span></span></code></pre></div><p>The paths in this post are the RHEL ones. On Debian/Ubuntu, AppArmor only lets <code>named</code> read <code>/etc/bind</code> and write <code>/var/lib/bind</code> and <code>/var/cache/bind</code>, so it is denied anything under <code>/etc/named</code> or <code>/var/named</code>. Use these paths there instead, everywhere they appear below (or add a local AppArmor override in <code>/etc/apparmor.d/local/usr.sbin.named</code>):</p>
<table>
	<thead>
			<tr>
					<th>RHEL</th>
					<th>Debian/Ubuntu</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>/etc/named/keys/</code></td>
					<td><code>/etc/bind/keys/</code></td>
			</tr>
			<tr>
					<td><code>/var/named/dynamic/</code></td>
					<td><code>/var/lib/bind/dynamic/</code></td>
			</tr>
	</tbody>
</table>
<p>The SELinux steps are RHEL only.</p>
<p>The file contains:</p>
<pre tabindex="0"><code>key &#34;ddns-key&#34; {
    algorithm hmac-sha256;
    secret &#34;X7s8F2pL+Kd9mN1vQ4rT6wY0zA3cE5hG7jU2nM4xB8=&#34;;
};
</code></pre><p>Create one key per client. A leaked key then only exposes what that client may change, and you can revoke it alone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 dhcp-update-key &gt; /etc/named/keys/dhcp.key
</span></span><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 k8s-update-key &gt; /etc/named/keys/kubernetes.key
</span></span><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 admin-update-key &gt; /etc/named/keys/admin.key
</span></span></code></pre></div><p>Secure the key files. <code>named</code> must read them, nobody else:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/named/keys/*.key
</span></span><span class="line"><span class="cl">chown root:named /etc/named/keys/*.key    <span class="c1"># Debian/Ubuntu: root:bind</span>
</span></span></code></pre></div><h2 id="configuring-bind-for-dynamic-updates">Configuring BIND for Dynamic Updates <a class="anchor" data-pagefind-ignore href="#configuring-bind-for-dynamic-updates" aria-label="Link to this section">#</a></h2>
<p>Two ways to say who may update a zone:</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>allow-update { key &quot;…&quot;; }</code></td>
					<td>One trusted client that may change anything in the zone</td>
			</tr>
			<tr>
					<td><code>update-policy { grant … }</code></td>
					<td>Several clients, each limited to certain names and record types</td>
			</tr>
	</tbody>
</table>
<p>The two cannot be combined in one zone.</p>
<h3 id="basic-update-configuration">Basic Update Configuration <a class="anchor" data-pagefind-ignore href="#basic-update-configuration" aria-label="Link to this section">#</a></h3>
<p>Include the key and configure the zone. <code>allow-update</code> gives <code>ddns-key</code> full control over <code>dynamic.example.com</code>. The journal lists every change so BIND can replay it after a restart.</p>
<pre tabindex="0"><code>// /etc/named.conf

include &#34;/etc/named/keys/ddns.key&#34;;

zone &#34;dynamic.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/dynamic.example.com.zone&#34;;
    allow-update { key &#34;ddns-key&#34;; };
    
    // Journal file for tracking updates
    journal &#34;/var/named/dynamic/dynamic.example.com.zone.jnl&#34;;
};
</code></pre><h3 id="multiple-keys-with-different-permissions">Multiple Keys with Different Permissions <a class="anchor" data-pagefind-ignore href="#multiple-keys-with-different-permissions" aria-label="Link to this section">#</a></h3>
<p>Grant different access levels to different keys. Dynamic zones need a directory <code>named</code> can write to for the journal (see <a href="#directory-and-file-permissions">Directory and File Permissions</a>), so they live in <code>/var/named/dynamic</code>:</p>
<ul>
<li>DHCP may only touch A, AAAA and TXT records below <code>internal.example.com</code>.</li>
<li>Kubernetes owns everything below <code>k8s.example.com</code>.</li>
<li>The admin key can change any name in <code>example.com</code>.</li>
</ul>
<pre tabindex="0"><code>include &#34;/etc/named/keys/dhcp.key&#34;;
include &#34;/etc/named/keys/kubernetes.key&#34;;
include &#34;/etc/named/keys/admin.key&#34;;

zone &#34;internal.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/internal.example.com.zone&#34;;
    
    // DHCP can only update specific record types
    update-policy {
        grant dhcp-update-key wildcard *.internal.example.com A AAAA;
        grant dhcp-update-key wildcard *.internal.example.com TXT;
    };
};

zone &#34;k8s.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/k8s.example.com.zone&#34;;
    
    // Kubernetes can manage its subdomain
    update-policy {
        grant k8s-update-key subdomain k8s.example.com ANY;
    };
};

zone &#34;example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/example.com.zone&#34;;
    
    // Admin has full control
    update-policy {
        grant admin-update-key zonesub ANY;
    };
};
</code></pre><h3 id="update-policy-rules">Update Policy Rules <a class="anchor" data-pagefind-ignore href="#update-policy-rules" aria-label="Link to this section">#</a></h3>
<p>Each <code>grant</code> line names a key, a rule type that says which names match, and optionally the record types allowed:</p>
<pre tabindex="0"><code>update-policy {
    // Grant based on key name
    grant keyname ruletype name [types];
};
</code></pre><table>
	<thead>
			<tr>
					<th>Rule type</th>
					<th>Matches</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>name</code></td>
					<td>Exact name match (<code>name *.example.com</code> matches only the literal wildcard record, not <code>host1.example.com</code>)</td>
			</tr>
			<tr>
					<td><code>subdomain</code></td>
					<td>Name and all names below it</td>
			</tr>
			<tr>
					<td><code>wildcard</code></td>
					<td>Pattern match with wildcards</td>
			</tr>
			<tr>
					<td><code>zonesub</code></td>
					<td>Any name in the zone</td>
			</tr>
			<tr>
					<td><code>self</code></td>
					<td>Client can update its own name (based on key name)</td>
			</tr>
			<tr>
					<td><code>selfsub</code></td>
					<td>Client can update its name and below</td>
			</tr>
			<tr>
					<td><code>selfwild</code></td>
					<td>Client can update wildcards of its name</td>
			</tr>
	</tbody>
</table>
<p>Examples:</p>
<pre tabindex="0"><code>update-policy {
    // DHCP can add A records for any host in clients subdomain
    grant dhcp-key subdomain clients.example.com A AAAA PTR;
    
    // Let-encrypt can update TXT records for ACME challenges
    grant acme-key name _acme-challenge.example.com TXT;
    
    // Monitoring can update health check records
    grant monitoring-key name health.example.com A TXT;
    
    // Self-registration: any key may update the record that
    // matches its own key name
    grant * self * A AAAA;
};
</code></pre><h2 id="directory-and-file-permissions">Directory and File Permissions <a class="anchor" data-pagefind-ignore href="#directory-and-file-permissions" aria-label="Link to this section">#</a></h2>
<p>BIND writes the journal next to the zone file and rewrites the zone file when it syncs, so it needs write access to that directory. On RHEL, SELinux must also allow it: <code>named_zone_t</code> is the label for writable zone data.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Create directory for dynamic zones</span>
</span></span><span class="line"><span class="cl">mkdir -p /var/named/dynamic
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set ownership</span>
</span></span><span class="line"><span class="cl">chown named:named /var/named/dynamic
</span></span><span class="line"><span class="cl">chmod <span class="m">750</span> /var/named/dynamic
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># If using SELinux</span>
</span></span><span class="line"><span class="cl">semanage fcontext -a -t named_zone_t <span class="s2">&#34;/var/named/dynamic(/.*)?&#34;</span> 
</span></span><span class="line"><span class="cl">restorecon -Rv /var/named/dynamic
</span></span></code></pre></div><h2 id="sending-dynamic-updates">Sending Dynamic Updates <a class="anchor" data-pagefind-ignore href="#sending-dynamic-updates" aria-label="Link to this section">#</a></h2>
<h3 id="using-nsupdate">Using nsupdate <a class="anchor" data-pagefind-ignore href="#using-nsupdate" aria-label="Link to this section">#</a></h3>
<p><code>nsupdate</code> is the standard client. <code>-k</code> signs the update with the key; <code>send</code> applies everything entered since the last <code>send</code> as one update.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Interactive mode</span>
</span></span><span class="line"><span class="cl">nsupdate -k /etc/named/keys/ddns.key
</span></span><span class="line"><span class="cl">&gt; server ns1.example.com
</span></span><span class="line"><span class="cl">&gt; zone dynamic.example.com
</span></span><span class="line"><span class="cl">&gt; update add newhost.dynamic.example.com <span class="m">300</span> A 192.168.1.100
</span></span><span class="line"><span class="cl">&gt; send
</span></span><span class="line"><span class="cl">&gt; quit
</span></span></code></pre></div><p>From a script:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">nsupdate -k /etc/named/keys/ddns.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone dynamic.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update delete oldhost.dynamic.example.com A
</span></span></span><span class="line"><span class="cl"><span class="s">update add newhost.dynamic.example.com 300 A 192.168.1.100
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><h3 id="update-operations">Update Operations <a class="anchor" data-pagefind-ignore href="#update-operations" aria-label="Link to this section">#</a></h3>
<p>The commands you combine in an update. There is no &ldquo;replace&rdquo;: delete the old record and add the new one in the same <code>send</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Add a record</span>
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.10
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Delete specific record</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com A 192.168.1.10
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Delete all records of a type</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Delete all records for a name</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update (delete + add)</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com A
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.20
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add multiple records</span>
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.10
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.11
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add different record types</span>
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.10
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> AAAA 2001:db8::10
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> TXT <span class="s2">&#34;v=spf1 -all&#34;</span>
</span></span></code></pre></div><h3 id="prerequisites-conditional-updates">Prerequisites (Conditional Updates) <a class="anchor" data-pagefind-ignore href="#prerequisites-conditional-updates" aria-label="Link to this section">#</a></h3>
<p>A <code>prereq</code> line makes the update apply only if the condition holds; otherwise the server refuses the whole update. Use it to avoid overwriting a record another client owns.</p>
<table>
	<thead>
			<tr>
					<th>Prerequisite</th>
					<th>Condition</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>nxdomain</code></td>
					<td>The name does not exist</td>
			</tr>
			<tr>
					<td><code>yxdomain</code></td>
					<td>The name exists</td>
			</tr>
			<tr>
					<td><code>yxrrset</code></td>
					<td>The record set exists (with this value, if given)</td>
			</tr>
	</tbody>
</table>
<p>These run against <code>example.com</code>, so they use the admin key that the zone&rsquo;s <code>update-policy</code> grants. Comments inside nsupdate input start with <code>;</code>. A <code>#</code> line makes nsupdate abort with <code>incorrect section name: #</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">nsupdate -k /etc/named/keys/admin.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone example.com
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">; Only add if record doesn&#39;t exist
</span></span></span><span class="line"><span class="cl"><span class="s">prereq nxdomain newhost.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update add newhost.example.com 300 A 192.168.1.10
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">; Only update if record exists
</span></span></span><span class="line"><span class="cl"><span class="s">prereq yxdomain oldhost.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update delete oldhost.example.com A
</span></span></span><span class="line"><span class="cl"><span class="s">update add oldhost.example.com 300 A 192.168.1.20
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">; Only update if specific record exists
</span></span></span><span class="line"><span class="cl"><span class="s">prereq yxrrset oldhost.example.com A 192.168.1.20
</span></span></span><span class="line"><span class="cl"><span class="s">update delete oldhost.example.com A
</span></span></span><span class="line"><span class="cl"><span class="s">update add oldhost.example.com 300 A 192.168.1.30
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><h2 id="integrating-with-kea-dhcp">Integrating with Kea DHCP <a class="anchor" data-pagefind-ignore href="#integrating-with-kea-dhcp" aria-label="Link to this section">#</a></h2>
<p>ISC DHCP (<code>dhcpd</code>) reached end of life in 2022; its successor is ISC Kea. Kea splits the work over two daemons:</p>
<ul>
<li><code>kea-dhcp4</code> hands out leases and queues DNS changes.</li>
<li><code>kea-dhcp-ddns</code> (D2) sends the signed updates to BIND, adding A, DHCID and PTR records when a lease is assigned and removing them again when the lease is released.</li>
</ul>
<p>On Debian/Ubuntu:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo apt install -y kea-dhcp4-server kea-dhcp-ddns-server
</span></span></code></pre></div><h3 id="dhcp-server-configuration">DHCP Server Configuration <a class="anchor" data-pagefind-ignore href="#dhcp-server-configuration" aria-label="Link to this section">#</a></h3>
<p><code>kea-dhcp4</code> decides what name a client gets and hands the DNS work to D2. The DDNS settings:</p>
<ul>
<li><code>dhcp-ddns.enable-updates</code>: send DNS changes to D2 on localhost.</li>
<li><code>ddns-send-updates</code> with <code>ddns-override-client-update</code>: Kea updates forward and reverse zones itself, even if the client offers to do its own.</li>
<li><code>ddns-qualifying-suffix</code>: appended to the client&rsquo;s hostname, giving <code>host.internal.example.com.</code>.</li>
<li><code>ddns-replace-client-name: when-not-present</code> with <code>ddns-generated-prefix</code>: clients without a hostname get a generated name like <code>dhcp-192-168-1-100</code>.</li>
<li><code>hostname-char-set</code> / <code>hostname-char-replacement</code>: characters not allowed in DNS names become <code>-</code>.</li>
</ul>
<pre tabindex="0"><code>// /etc/kea/kea-dhcp4.conf
{
  &#34;Dhcp4&#34;: {
    &#34;interfaces-config&#34;: {
      &#34;interfaces&#34;: [ &#34;eth0&#34; ]
    },

    &#34;lease-database&#34;: {
      &#34;type&#34;: &#34;memfile&#34;,
      &#34;persist&#34;: true,
      &#34;name&#34;: &#34;/var/lib/kea/kea-leases4.csv&#34;
    },

    // Hand DNS work to kea-dhcp-ddns (D2) on localhost
    &#34;dhcp-ddns&#34;: {
      &#34;enable-updates&#34;: true
    },

    // Kea updates both forward and reverse zones itself,
    // even if the client asks to do its own forward update
    &#34;ddns-send-updates&#34;: true,
    &#34;ddns-override-client-update&#34;: true,
    &#34;ddns-qualifying-suffix&#34;: &#34;internal.example.com.&#34;,

    // Clients without a hostname get dhcp-192-168-1-100 etc.
    &#34;ddns-replace-client-name&#34;: &#34;when-not-present&#34;,
    &#34;ddns-generated-prefix&#34;: &#34;dhcp&#34;,
    &#34;hostname-char-set&#34;: &#34;[^A-Za-z0-9.-]&#34;,
    &#34;hostname-char-replacement&#34;: &#34;-&#34;,

    &#34;subnet4&#34;: [
      {
        &#34;id&#34;: 1,
        &#34;subnet&#34;: &#34;192.168.1.0/24&#34;,
        &#34;pools&#34;: [ { &#34;pool&#34;: &#34;192.168.1.100 - 192.168.1.200&#34; } ],
        &#34;option-data&#34;: [
          { &#34;name&#34;: &#34;routers&#34;, &#34;data&#34;: &#34;192.168.1.1&#34; },
          { &#34;name&#34;: &#34;domain-name&#34;, &#34;data&#34;: &#34;internal.example.com&#34; },
          { &#34;name&#34;: &#34;domain-name-servers&#34;, &#34;data&#34;: &#34;192.168.1.10&#34; }
        ]
      }
    ]
  }
}
</code></pre><h3 id="dhcp-ddns-d2-configuration">DHCP-DDNS (D2) Configuration <a class="anchor" data-pagefind-ignore href="#dhcp-ddns-d2-configuration" aria-label="Link to this section">#</a></h3>
<p>D2 holds the TSIG key and knows which server is authoritative for each zone. Paste the secret from <code>tsig-keygen -a hmac-sha256 dhcp-key</code>:</p>
<ul>
<li><code>tsig-keys</code>: same name and secret as the key in BIND.</li>
<li><code>forward-ddns</code> / <code>reverse-ddns</code>: per zone, the key to sign with and the DNS server to send updates to.</li>
</ul>
<pre tabindex="0"><code>// /etc/kea/kea-dhcp-ddns.conf
{
  &#34;DhcpDdns&#34;: {
    &#34;ip-address&#34;: &#34;127.0.0.1&#34;,
    &#34;port&#34;: 53001,

    // Key for DNS updates (same name and secret as in BIND)
    &#34;tsig-keys&#34;: [
      {
        &#34;name&#34;: &#34;dhcp-key&#34;,
        &#34;algorithm&#34;: &#34;HMAC-SHA256&#34;,
        &#34;secret&#34;: &#34;your-secret-from-tsig-keygen&#34;
      }
    ],

    // Forward zone
    &#34;forward-ddns&#34;: {
      &#34;ddns-domains&#34;: [
        {
          &#34;name&#34;: &#34;internal.example.com.&#34;,
          &#34;key-name&#34;: &#34;dhcp-key&#34;,
          &#34;dns-servers&#34;: [ { &#34;ip-address&#34;: &#34;192.168.1.10&#34; } ]
        }
      ]
    },

    // Reverse zone
    &#34;reverse-ddns&#34;: {
      &#34;ddns-domains&#34;: [
        {
          &#34;name&#34;: &#34;1.168.192.in-addr.arpa.&#34;,
          &#34;key-name&#34;: &#34;dhcp-key&#34;,
          &#34;dns-servers&#34;: [ { &#34;ip-address&#34;: &#34;192.168.1.10&#34; } ]
        }
      ]
    }
  }
}
</code></pre><p>The file contains the secret and the daemons run as <code>_kea</code>, so protect it, check both files and restart the services:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo chown root:_kea /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">sudo chmod <span class="m">640</span> /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">sudo kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
</span></span><span class="line"><span class="cl">sudo kea-dhcp-ddns -t /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">sudo systemctl restart kea-dhcp-ddns-server kea-dhcp4-server
</span></span></code></pre></div><h3 id="bind-configuration-for-dhcp">BIND Configuration for DHCP <a class="anchor" data-pagefind-ignore href="#bind-configuration-for-dhcp" aria-label="Link to this section">#</a></h3>
<p>The matching zones on the BIND side. <code>dhcp-key</code> may only manage address, PTR and DHCID records. DHCID records let Kea tell its own records apart from ones it did not create.</p>
<pre tabindex="0"><code>// Forward zone
zone &#34;internal.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/internal.example.com.zone&#34;;
    update-policy {
        grant dhcp-key subdomain internal.example.com A AAAA DHCID;
    };
};

// Reverse zone
zone &#34;1.168.192.in-addr.arpa&#34; {
    type primary;
    file &#34;/var/named/dynamic/192.168.1.rev&#34;;
    update-policy {
        grant dhcp-key subdomain 1.168.192.in-addr.arpa PTR DHCID;
    };
};
</code></pre><p>Kea also writes a DHCID record next to the PTR in the reverse zone, so the reverse policy must allow <code>DHCID</code> as well; without it D2 logs <code>DHCP_DDNS_REVERSE_REPLACE_REJECTED ... RCODE: 5</code> and the PTR is never created.</p>
<h2 id="reverse-dns-updates">Reverse DNS Updates <a class="anchor" data-pagefind-ignore href="#reverse-dns-updates" aria-label="Link to this section">#</a></h2>
<p>Without Kea you send the PTR records yourself. Reverse zones are separate zones, so each needs its own update.</p>
<p>Use a key that the target zone&rsquo;s <code>allow-update</code>/<code>update-policy</code> grants. With the DHCP configuration above, that is <code>dhcp-key</code> for both zones; any other key gets <code>REFUSED</code> (or <code>NOTAUTH(BADKEY)</code> if the server doesn&rsquo;t know it):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">nsupdate -k /etc/named/keys/ddns.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone 1.168.192.in-addr.arpa
</span></span></span><span class="line"><span class="cl"><span class="s">update add 100.1.168.192.in-addr.arpa 300 PTR hostname.example.com.
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><p>Script for simultaneous forward and reverse updates. It derives the reverse name and zone from the IP (assuming a /24 reverse zone), then replaces the A and PTR records:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># Stop on the first failed nsupdate instead of reporting success</span>
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HOSTNAME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">IP</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$2</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">ZONE</span><span class="o">=</span><span class="s2">&#34;internal.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">KEY</span><span class="o">=</span><span class="s2">&#34;/etc/named/keys/ddns.key&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">SERVER</span><span class="o">=</span><span class="s2">&#34;ns1.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">TTL</span><span class="o">=</span><span class="m">300</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate reverse zone from IP</span>
</span></span><span class="line"><span class="cl"><span class="nv">IFS</span><span class="o">=</span><span class="s1">&#39;.&#39;</span> <span class="nb">read</span> -ra OCTETS <span class="o">&lt;&lt;&lt;</span> <span class="s2">&#34;</span><span class="nv">$IP</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">REVERSE</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[3]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[2]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[1]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[0]</span><span class="si">}</span><span class="s2">.in-addr.arpa&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">REVZONE</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[2]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[1]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[0]</span><span class="si">}</span><span class="s2">.in-addr.arpa&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update forward zone</span>
</span></span><span class="line"><span class="cl">nsupdate -k <span class="s2">&#34;</span><span class="nv">$KEY</span><span class="s2">&#34;</span> <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server $SERVER
</span></span></span><span class="line"><span class="cl"><span class="s">zone $ZONE
</span></span></span><span class="line"><span class="cl"><span class="s">update delete ${HOSTNAME}.${ZONE} A
</span></span></span><span class="line"><span class="cl"><span class="s">update add ${HOSTNAME}.${ZONE} $TTL A $IP
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update reverse zone</span>
</span></span><span class="line"><span class="cl">nsupdate -k <span class="s2">&#34;</span><span class="nv">$KEY</span><span class="s2">&#34;</span> <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server $SERVER
</span></span></span><span class="line"><span class="cl"><span class="s">zone $REVZONE
</span></span></span><span class="line"><span class="cl"><span class="s">update delete $REVERSE PTR
</span></span></span><span class="line"><span class="cl"><span class="s">update add $REVERSE $TTL PTR ${HOSTNAME}.${ZONE}.
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Updated: </span><span class="si">${</span><span class="nv">HOSTNAME</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">ZONE</span><span class="si">}</span><span class="s2"> -&gt; </span><span class="nv">$IP</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h2 id="managing-journal-files">Managing Journal Files <a class="anchor" data-pagefind-ignore href="#managing-journal-files" aria-label="Link to this section">#</a></h2>
<p>BIND stores dynamic updates in journal files before merging them with the zone file. The zone file on disk can therefore be behind what BIND serves. Never edit it while updates are enabled.</p>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>What it does</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>rndc freeze</code></td>
					<td>Writes the journal into the zone file and stops updates</td>
					<td>Manual edits</td>
			</tr>
			<tr>
					<td><code>rndc thaw</code></td>
					<td>Reloads the zone file and enables updates again</td>
					<td>After manual edits</td>
			</tr>
			<tr>
					<td><code>rndc sync</code></td>
					<td>Writes the journal into the zone file, updates keep working</td>
					<td>Backups, reading the file</td>
			</tr>
			<tr>
					<td><code>rndc sync -clean</code></td>
					<td>Same, and removes the journal</td>
					<td>Cleaning up a large journal</td>
			</tr>
	</tbody>
</table>
<h3 id="freeze-and-thaw">Freeze and Thaw <a class="anchor" data-pagefind-ignore href="#freeze-and-thaw" aria-label="Link to this section">#</a></h3>
<p>To manually edit a dynamic zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Freeze zone (syncs journal to zone file)</span>
</span></span><span class="line"><span class="cl">rndc freeze example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Edit the zone file manually</span>
</span></span><span class="line"><span class="cl">vim /var/named/dynamic/example.com.zone
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update serial number!</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Thaw zone (re-enables dynamic updates)</span>
</span></span><span class="line"><span class="cl">rndc thaw example.com
</span></span></code></pre></div><h3 id="sync-without-freezing">Sync Without Freezing <a class="anchor" data-pagefind-ignore href="#sync-without-freezing" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Sync journal to zone file without freezing</span>
</span></span><span class="line"><span class="cl">rndc sync example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sync and clear journal</span>
</span></span><span class="line"><span class="cl">rndc sync -clean example.com
</span></span></code></pre></div><h3 id="viewing-zone-contents">Viewing Zone Contents <a class="anchor" data-pagefind-ignore href="#viewing-zone-contents" aria-label="Link to this section">#</a></h3>
<p>To see what BIND actually serves, dump it from memory or transfer the zone. AXFR only works from a host the zone&rsquo;s <code>allow-transfer</code> permits.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Dump zone including dynamic updates</span>
</span></span><span class="line"><span class="cl">rndc dumpdb -zones
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL: /var/named/data/cache_dump.db, Debian/Ubuntu: /var/cache/bind/named_dump.db</span>
</span></span><span class="line"><span class="cl">cat /var/named/data/cache_dump.db <span class="p">|</span> grep -A100 <span class="s2">&#34;example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or view via dig</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com AXFR
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="enable-update-logging">Enable Update Logging <a class="anchor" data-pagefind-ignore href="#enable-update-logging" aria-label="Link to this section">#</a></h3>
<p>The <code>update</code> category logs every update; <code>update-security</code> logs the ones that were refused. Send both to a file while debugging:</p>
<pre tabindex="0"><code>logging {
    channel update_log {
        file &#34;/var/log/named/update.log&#34; versions 5 size 10m;
        severity debug;
        print-time yes;
        print-category yes;
    };
    
    category update { update_log; };
    category update-security { update_log; };
};
</code></pre><h3 id="common-errors">Common Errors <a class="anchor" data-pagefind-ignore href="#common-errors" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Error</th>
					<th>Causes</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>NOTAUTH(BADKEY)</code></td>
					<td>Key not configured on the server, or key name mismatch</td>
			</tr>
			<tr>
					<td><code>NOTAUTH(BADSIG)</code></td>
					<td>Same key name, but the secret doesn&rsquo;t match</td>
			</tr>
			<tr>
					<td><code>REFUSED</code></td>
					<td>Update policy doesn&rsquo;t allow the operation for this key, name or type; or update sent without a key to a zone that requires one</td>
			</tr>
			<tr>
					<td><code>NOTAUTH</code></td>
					<td>Server is not authoritative for the zone; or zone name incorrect</td>
			</tr>
			<tr>
					<td><code>SERVFAIL</code></td>
					<td>Zone file or journal file permission issues; filesystem full</td>
			</tr>
	</tbody>
</table>
<p>What each looks like in nsupdate:</p>
<p><strong>NOTAUTH(BADKEY) / NOTAUTH(BADSIG)</strong></p>
<pre tabindex="0"><code>; TSIG error with server: tsig indicates error
update failed: NOTAUTH(BADKEY)
</code></pre><p><strong>REFUSED</strong></p>
<pre tabindex="0"><code>update failed: REFUSED
</code></pre><p><strong>NOTAUTH</strong></p>
<pre tabindex="0"><code>update failed: NOTAUTH
</code></pre><p><strong>SERVFAIL</strong></p>
<pre tabindex="0"><code>update failed: SERVFAIL
</code></pre><h3 id="debug-mode">Debug Mode <a class="anchor" data-pagefind-ignore href="#debug-mode" aria-label="Link to this section">#</a></h3>
<p><code>-d</code> prints debug output for each step, including the reply from the server:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verbose nsupdate</span>
</span></span><span class="line"><span class="cl">nsupdate -d -k /etc/named/keys/admin.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update add test.example.com 300 A 192.168.1.99
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><h3 id="check-permissions">Check Permissions <a class="anchor" data-pagefind-ignore href="#check-permissions" aria-label="Link to this section">#</a></h3>
<p>For <code>SERVFAIL</code>, check file ownership and, on RHEL, SELinux labels and denials:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Zone file and directory permissions</span>
</span></span><span class="line"><span class="cl">ls -la /var/named/dynamic/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># SELinux context</span>
</span></span><span class="line"><span class="cl">ls -laZ /var/named/dynamic/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check for SELinux denials</span>
</span></span><span class="line"><span class="cl">ausearch -m AVC -ts recent <span class="p">|</span> grep named
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<h3 id="limit-update-scope">Limit Update Scope <a class="anchor" data-pagefind-ignore href="#limit-update-scope" aria-label="Link to this section">#</a></h3>
<p>Never use <code>allow-update { any; }</code>. Always restrict updates:</p>
<pre tabindex="0"><code>// Bad - anyone can update
allow-update { any; };

// Good - only authenticated clients
allow-update { key &#34;update-key&#34;; };

// Better - granular policy
update-policy {
    grant update-key subdomain clients.example.com A AAAA;
};
</code></pre><h3 id="separate-keys-per-service">Separate Keys per Service <a class="anchor" data-pagefind-ignore href="#separate-keys-per-service" aria-label="Link to this section">#</a></h3>
<p>Each service should have its own key with minimum required permissions:</p>
<pre tabindex="0"><code>update-policy {
    // DHCP only manages client records
    grant dhcp-key subdomain clients.internal.example.com A AAAA PTR DHCID;
    
    // Let&#39;s Encrypt only manages ACME challenges
    grant acme-key name _acme-challenge.example.com TXT;
    
    // Kubernetes only manages its namespace
    grant k8s-key subdomain k8s.example.com A AAAA SRV;
};
</code></pre><h3 id="protect-key-files">Protect Key Files <a class="anchor" data-pagefind-ignore href="#protect-key-files" aria-label="Link to this section">#</a></h3>
<p>Anyone with the key file can change your zone. Keep the server&rsquo;s copies readable only by <code>named</code>, and give each client only its own key:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># 440, not 400: named runs as the named user and reads keys via the group</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">440</span> /etc/named/keys/*.key
</span></span><span class="line"><span class="cl">chown root:named /etc/named/keys/*.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># For client systems, only the specific key they need</span>
</span></span><span class="line"><span class="cl"><span class="c1"># (Kea keeps it inside the D2 config, read by the _kea user)</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">chown root:_kea /etc/kea/kea-dhcp-ddns.conf
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-dynamic-dns" rel="noopener">pderuiter/blog-bind-dynamic-dns</a>. It creates a BIND server with the dynamic zones, keys and update policies from this post, plus a Kea DHCP server whose D2 daemon registers every lease in DNS; put your TSIG secrets in an ansible-vault file, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>TSIG keys plus <code>update-policy</code> let DHCP, Kubernetes and automation update DNS safely, each within its own part of the zone.</p>
<p>The next post will cover integrating BIND with Kubernetes external-dns for automated service discovery and DNS management.</p>
]]></content:encoded></item><item><title>How to Configure BIND RNDC and TSIG Keys for Remote DNS Management</title><link>https://blog.bsdserver.nl/how-to-configure-bind-rndc-and-tsig-keys-for-remote-dns-management/</link><guid isPermaLink="false">693b6bae79eb54000160a54e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:11:10 +0000</pubDate><description>RNDC (Remote Name Daemon Control) is the administrative tool for managing BIND DNS servers.</description><category>BIND</category><category>DNS</category><category>rndc</category><category>TSIG</category><category>Security</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-rndc-tsig.png" medium="image"/><content:encoded><![CDATA[<p>RNDC (Remote Name Daemon Control) is the administrative tool for managing BIND DNS servers. It reloads zones, flushes caches and shows statistics without restarting the service.</p>
<p>This post sets up RNDC keys for local and remote administration, a read-only channel for monitoring, and TSIG keys that authenticate zone transfers between master and slave.</p>
<h2 id="why-rndc-and-tsig">Why RNDC and TSIG? <a class="anchor" data-pagefind-ignore href="#why-rndc-and-tsig" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>No restarts</strong>: reload a zone or the configuration while <code>named</code> keeps answering.</li>
<li><strong>Remote control</strong>: manage several DNS servers from one admin workstation.</li>
<li><strong>Authenticated</strong>: every command and every zone transfer is signed with a shared secret.</li>
<li><strong>Least privilege</strong>: separate keys and read-only channels for monitoring.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> on every BIND server: local RNDC is the normal way to reload zones. Add remote access and TSIG when you run more than one server.</li>
<li><strong>Skip</strong> remote RNDC if you manage servers only over SSH; keep the local channel.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Piece</th>
					<th>Protects</th>
					<th>Where</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>RNDC key + <code>controls</code></td>
					<td>Admin commands to <code>named</code></td>
					<td>TCP port 953 (by default)</td>
			</tr>
			<tr>
					<td><code>rndc.conf</code></td>
					<td>Which key and server the <code>rndc</code> client uses</td>
					<td>Admin workstation or the server itself</td>
			</tr>
			<tr>
					<td>TSIG transfer key</td>
					<td>Zone transfers and NOTIFY between master and slave</td>
					<td>Port 53, inside the DNS messages</td>
			</tr>
	</tbody>
</table>
<p>Both use the same mechanism: a shared HMAC secret. <strong>RNDC</strong> signs each command with it; <strong>TSIG</strong> (Transaction Signature) signs DNS messages with it. A message without a valid signature is rejected.</p>
<p>The flow for a remote reload: <code>rndc -s dns1 reload</code> → the client signs the command with the key from <code>rndc.conf</code> → <code>named</code> checks the source IP against <code>allow</code> and the signature against <code>keys</code> → runs the command.</p>
<h2 id="generating-rndc-keys">Generating RNDC Keys <a class="anchor" data-pagefind-ignore href="#generating-rndc-keys" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>rndc-confgen -a</code></td>
					<td>Local administration only; writes a key file <code>named</code> reads automatically</td>
			</tr>
			<tr>
					<td><code>rndc-confgen</code></td>
					<td>Remote administration; prints a full <code>rndc.conf</code> and the matching <code>named.conf</code> snippet</td>
			</tr>
			<tr>
					<td><code>tsig-keygen</code></td>
					<td>Zone transfer and dynamic update keys (see below)</td>
			</tr>
	</tbody>
</table>
<h3 id="automatic-generation">Automatic Generation <a class="anchor" data-pagefind-ignore href="#automatic-generation" aria-label="Link to this section">#</a></h3>
<p>The simplest way to set up RNDC is using <code>rndc-confgen</code> with the <code>-a</code> flag:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen -a
</span></span></code></pre></div><p>This creates <code>/etc/rndc.key</code> (RHEL) or <code>/etc/bind/rndc.key</code> (Debian/Ubuntu) with a randomly generated key:</p>
<pre tabindex="0"><code>key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;base64-encoded-secret&#34;;
};
</code></pre><p>BIND automatically includes this file, so no additional configuration is needed for local administration. However, <code>rndc-confgen -a</code> creates the file mode <code>0600</code> and owned by root, so <code>named</code>, which runs as <code>named</code> (RHEL) or <code>bind</code> (Debian/Ubuntu), cannot read it. The log then shows <code>open: /etc/rndc.key: permission denied</code> and <code>rndc</code> fails with <code>connection to remote host closed</code>. Either pass the daemon user with <code>-u</code>, or fix ownership afterwards and restart <code>named</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen -a -u named          <span class="c1"># Debian/Ubuntu: -u bind</span>
</span></span><span class="line"><span class="cl"><span class="c1"># or</span>
</span></span><span class="line"><span class="cl">chown root:named /etc/rndc.key <span class="o">&amp;&amp;</span> chmod <span class="m">640</span> /etc/rndc.key
</span></span></code></pre></div><h3 id="manual-generation">Manual Generation <a class="anchor" data-pagefind-ignore href="#manual-generation" aria-label="Link to this section">#</a></h3>
<p>For remote administration you need the key on both sides. Without <code>-a</code>, <code>rndc-confgen</code> prints both halves:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen
</span></span></code></pre></div><p>This outputs both the <code>rndc.conf</code> content and the corresponding <code>named.conf</code> additions:</p>
<pre tabindex="0"><code># Start of rndc.conf
key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
};

options {
    default-key &#34;rndc-key&#34;;
    default-server 127.0.0.1;
    default-port 953;
};
# End of rndc.conf

# Use with the following in named.conf, adjusting the allow list as needed:
# key &#34;rndc-key&#34; {
#     algorithm hmac-sha256;
#     secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
# };
#
# controls {
#     inet 127.0.0.1 port 953
#         allow { 127.0.0.1; } keys { &#34;rndc-key&#34;; };
# };
# End of named.conf
</code></pre><h3 id="specifying-key-algorithm">Specifying Key Algorithm <a class="anchor" data-pagefind-ignore href="#specifying-key-algorithm" aria-label="Link to this section">#</a></h3>
<p>BIND supports several HMAC algorithms. <code>-A</code> picks the algorithm and <code>-k</code> the key name; both sides must use the same.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># SHA-256 (recommended)</span>
</span></span><span class="line"><span class="cl">rndc-confgen -a -A hmac-sha256
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># SHA-512 (strongest)</span>
</span></span><span class="line"><span class="cl">rndc-confgen -a -A hmac-sha512
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Custom key name</span>
</span></span><span class="line"><span class="cl">rndc-confgen -a -k my-admin-key
</span></span></code></pre></div><h2 id="configuring-namedconf">Configuring named.conf <a class="anchor" data-pagefind-ignore href="#configuring-namedconf" aria-label="Link to this section">#</a></h2>
<h3 id="the-controls-statement">The Controls Statement <a class="anchor" data-pagefind-ignore href="#the-controls-statement" aria-label="Link to this section">#</a></h3>
<p>The <code>controls</code> statement decides where <code>named</code> listens for RNDC, who may connect and with which key. Without a <code>controls</code> statement, <code>named</code> listens on localhost and uses <code>rndc.key</code>.</p>
<pre tabindex="0"><code>controls {
    inet 127.0.0.1 port 953
        allow { 127.0.0.1; } keys { &#34;rndc-key&#34;; };
};
</code></pre><ul>
<li><code>inet 127.0.0.1</code>: listen address.</li>
<li><code>port 953</code>: TCP port (953 is the default).</li>
<li><code>allow { 127.0.0.1; }</code>: IP addresses allowed to connect.</li>
<li><code>keys { &quot;rndc-key&quot;; }</code>: keys accepted for authentication. A client needs both an allowed IP and a valid key.</li>
</ul>
<h3 id="enabling-remote-administration">Enabling Remote Administration <a class="anchor" data-pagefind-ignore href="#enabling-remote-administration" aria-label="Link to this section">#</a></h3>
<p>To manage BIND from remote hosts, add a second <code>inet</code> line on the server&rsquo;s LAN address. The <code>admin-hosts</code> ACL limits it to the admin network; the localhost channel stays for local use.</p>
<pre tabindex="0"><code>key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
};

acl &#34;admin-hosts&#34; {
    127.0.0.1;
    192.168.1.10;        # Admin workstation
    192.168.1.0/24;      # Admin network
};

controls {
    inet 127.0.0.1 port 953
        allow { 127.0.0.1; } keys { &#34;rndc-key&#34;; };
    inet 192.168.1.1 port 953
        allow { admin-hosts; } keys { &#34;rndc-key&#34;; };
};
</code></pre><h3 id="multiple-keys-for-different-access-levels">Multiple Keys for Different Access Levels <a class="anchor" data-pagefind-ignore href="#multiple-keys-for-different-access-levels" aria-label="Link to this section">#</a></h3>
<p>Separate keys let you revoke one system without touching the others. Every key listed on a control channel gets full control (including <code>rndc stop</code>) unless that channel is marked <code>read-only yes</code>. One <code>inet</code> address/port has only one read-only setting, so give the monitoring key its own port:</p>
<table>
	<thead>
			<tr>
					<th>Channel</th>
					<th>Key</th>
					<th>Access</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>127.0.0.1:953</code></td>
					<td><code>admin-key</code></td>
					<td>Full, local</td>
			</tr>
			<tr>
					<td><code>192.168.1.1:953</code></td>
					<td><code>admin-key</code></td>
					<td>Full, from the admin network</td>
			</tr>
			<tr>
					<td><code>192.168.1.1:954</code></td>
					<td><code>monitoring-key</code></td>
					<td>Read-only (status, stats)</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code>key &#34;admin-key&#34; {
    algorithm hmac-sha256;
    secret &#34;first-secret-here&#34;;
};

key &#34;monitoring-key&#34; {
    algorithm hmac-sha256;
    secret &#34;second-secret-here&#34;;
};

key &#34;secondary-ns-key&#34; {
    algorithm hmac-sha256;
    secret &#34;third-secret-here&#34;;
};

controls {
    inet 127.0.0.1 port 953
        allow { 127.0.0.1; } keys { &#34;admin-key&#34;; };
    inet 192.168.1.1 port 953
        allow { 192.168.1.0/24; } keys { &#34;admin-key&#34;; };
    // Monitoring: status/stats only, write commands are rejected
    inet 192.168.1.1 port 954
        allow { 192.168.1.0/24; } keys { &#34;monitoring-key&#34;; } read-only yes;
};
</code></pre><p>The monitoring system then connects with <code>rndc -p 954 ... status</code>.</p>
<h2 id="configuring-rndcconf">Configuring rndc.conf <a class="anchor" data-pagefind-ignore href="#configuring-rndcconf" aria-label="Link to this section">#</a></h2>
<p><code>rndc.conf</code> is the client side: which key to sign with and which server to talk to. It lives in <code>/etc/rndc.conf</code> (RHEL) or <code>/etc/bind/rndc.conf</code> (Debian/Ubuntu; <code>rndc</code> ignores <code>/etc/rndc.conf</code> there). When it exists it takes precedence over <code>rndc.key</code>.</p>
<ul>
<li><code>options</code>: the defaults when you run <code>rndc</code> without <code>-s</code>.</li>
<li><code>server</code> blocks: per-server key and port, selected with <code>rndc -s &lt;name&gt;</code>.</li>
</ul>
<pre tabindex="0"><code>key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
};

options {
    default-key &#34;rndc-key&#34;;
    default-server 127.0.0.1;
    default-port 953;
};

# Define additional servers
server dns1.example.com {
    key &#34;rndc-key&#34;;
    port 953;
};

server dns2.example.com {
    key &#34;rndc-key&#34;;
    port 953;
};
</code></pre><p>With multiple servers defined, specify which to manage:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc -s dns1.example.com reload
</span></span><span class="line"><span class="cl">rndc -s dns2.example.com reload
</span></span></code></pre></div><h2 id="tsig-keys-for-zone-transfers">TSIG Keys for Zone Transfers <a class="anchor" data-pagefind-ignore href="#tsig-keys-for-zone-transfers" aria-label="Link to this section">#</a></h2>
<p>Without TSIG, a zone transfer is only protected by the IP in <code>allow-transfer</code>. A TSIG key proves that the slave is who it says it is, and that the zone data was not altered on the way.</p>
<table>
	<thead>
			<tr>
					<th>Server</th>
					<th>IP</th>
					<th>Role</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Master</td>
					<td><code>192.168.1.2</code></td>
					<td>Holds the zone file, allows transfers signed with <code>transfer-key</code></td>
			</tr>
			<tr>
					<td>Slave</td>
					<td><code>192.168.1.3</code></td>
					<td>Transfers the zone, signing its requests with <code>transfer-key</code></td>
			</tr>
	</tbody>
</table>
<h3 id="generating-a-transfer-key">Generating a Transfer Key <a class="anchor" data-pagefind-ignore href="#generating-a-transfer-key" aria-label="Link to this section">#</a></h3>
<p><code>tsig-keygen</code> prints a ready-to-include <code>key</code> block. Generate it once and copy the same block to both servers.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 transfer-key
</span></span></code></pre></div><p>Output:</p>
<pre tabindex="0"><code>key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;generated-secret&#34;;
};
</code></pre><h3 id="master-server-configuration">Master Server Configuration <a class="anchor" data-pagefind-ignore href="#master-server-configuration" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>server 192.168.1.3 { keys ... }</code>: sign everything sent to the slave, such as NOTIFY messages, with the key.</li>
<li><code>allow-transfer { key &quot;transfer-key&quot;; }</code>: only requests signed with this key may transfer the zone.</li>
<li><code>also-notify</code>: tell the slave about changes straight away.</li>
</ul>
<pre tabindex="0"><code>key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;generated-secret&#34;;
};

server 192.168.1.3 {
    keys { &#34;transfer-key&#34;; };
};

zone &#34;example.com&#34; {
    type primary;
    file &#34;/var/named/zones/example.com.zone&#34;;
    allow-transfer { key &#34;transfer-key&#34;; };
    also-notify { 192.168.1.3; };
};
</code></pre><p>The zone and key paths in this section and in <a href="#avoid-storing-keys-in-main-config">Avoid Storing Keys in Main Config</a> are the RHEL ones. On Debian/Ubuntu, AppArmor only lets <code>named</code> read <code>/etc/bind</code> and write <code>/var/lib/bind</code> and <code>/var/cache/bind</code>, so use <code>/var/lib/bind/zones/</code> instead of <code>/var/named/zones/</code> and <code>/etc/bind/keys/</code> instead of <code>/etc/named/keys/</code> (or add a local AppArmor override in <code>/etc/apparmor.d/local/usr.sbin.named</code>).</p>
<h3 id="slave-server-configuration">Slave Server Configuration <a class="anchor" data-pagefind-ignore href="#slave-server-configuration" aria-label="Link to this section">#</a></h3>
<p>The mirror image: the <code>server</code> block makes the slave sign its transfer requests to the master with the same key.</p>
<pre tabindex="0"><code>key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;generated-secret&#34;;
};

server 192.168.1.2 {
    keys { &#34;transfer-key&#34;; };
};

zone &#34;example.com&#34; {
    type secondary;
    file &#34;/var/named/zones/example.com.zone&#34;;
    primaries { 192.168.1.2; };
};
</code></pre><h2 id="essential-rndc-commands">Essential RNDC Commands <a class="anchor" data-pagefind-ignore href="#essential-rndc-commands" aria-label="Link to this section">#</a></h2>
<p>The commands you will use most, grouped by job.</p>
<h3 id="zone-management">Zone Management <a class="anchor" data-pagefind-ignore href="#zone-management" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>reload</code>: re-read zone files on the master after an edit.</li>
<li><code>refresh</code> / <code>retransfer</code>: on a slave; check the serial now, or force a full transfer regardless of the serial.</li>
<li><code>freeze</code> / <code>thaw</code>: pause dynamic updates so you can edit a dynamic zone&rsquo;s file by hand.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Reload all zones</span>
</span></span><span class="line"><span class="cl">rndc reload
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload specific zone</span>
</span></span><span class="line"><span class="cl">rndc reload example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload zone in specific view</span>
</span></span><span class="line"><span class="cl">rndc reload example.com IN internal
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Force zone refresh (secondary)</span>
</span></span><span class="line"><span class="cl">rndc refresh example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Re-transfer zone (secondary)</span>
</span></span><span class="line"><span class="cl">rndc retransfer example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign zone with DNSSEC keys (zones with a dnssec-policy only)</span>
</span></span><span class="line"><span class="cl">rndc sign example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Freeze zone for manual editing (dynamic zones only)</span>
</span></span><span class="line"><span class="cl">rndc freeze example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Thaw zone after editing</span>
</span></span><span class="line"><span class="cl">rndc thaw example.com
</span></span></code></pre></div><h3 id="cache-management">Cache Management <a class="anchor" data-pagefind-ignore href="#cache-management" aria-label="Link to this section">#</a></h3>
<p>On a resolver, flush a name after a record changed upstream and clients keep getting the old answer. <code>flushtree</code> also removes everything below the name.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Flush entire cache</span>
</span></span><span class="line"><span class="cl">rndc flush
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Flush specific name from cache</span>
</span></span><span class="line"><span class="cl">rndc flushname example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Flush entire domain tree</span>
</span></span><span class="line"><span class="cl">rndc flushtree example.com
</span></span></code></pre></div><h3 id="server-control">Server Control <a class="anchor" data-pagefind-ignore href="#server-control" aria-label="Link to this section">#</a></h3>
<p><code>reconfig</code> only picks up configuration changes and new zones; use it when you have not edited existing zone files. <code>stop</code> saves pending changes first, <code>halt</code> does not.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Reload configuration (not zones)</span>
</span></span><span class="line"><span class="cl">rndc reconfig
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check server status</span>
</span></span><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Stop the server</span>
</span></span><span class="line"><span class="cl">rndc stop
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Halt immediately</span>
</span></span><span class="line"><span class="cl">rndc halt
</span></span></code></pre></div><h3 id="logging-and-debugging">Logging and Debugging <a class="anchor" data-pagefind-ignore href="#logging-and-debugging" aria-label="Link to this section">#</a></h3>
<p><code>dumpdb</code> and <code>stats</code> write to files in the server&rsquo;s working directory. <code>trace</code> raises the debug level by one per call.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Dump cache to file</span>
</span></span><span class="line"><span class="cl">rndc dumpdb -cache
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Dump zones to file</span>
</span></span><span class="line"><span class="cl">rndc dumpdb -zones
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Write server statistics</span>
</span></span><span class="line"><span class="cl">rndc stats
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Increment debug level</span>
</span></span><span class="line"><span class="cl">rndc trace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Disable debugging</span>
</span></span><span class="line"><span class="cl">rndc notrace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Toggle query logging</span>
</span></span><span class="line"><span class="cl">rndc querylog
</span></span></code></pre></div><h2 id="security-best-practices">Security Best Practices <a class="anchor" data-pagefind-ignore href="#security-best-practices" aria-label="Link to this section">#</a></h2>
<h3 id="key-file-permissions">Key File Permissions <a class="anchor" data-pagefind-ignore href="#key-file-permissions" aria-label="Link to this section">#</a></h3>
<p>The key files hold the secrets: readable by root and the BIND group only.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Restrict key file access</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/rndc.key
</span></span><span class="line"><span class="cl">chown root:named /etc/rndc.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/rndc.conf
</span></span><span class="line"><span class="cl">chown root:named /etc/rndc.conf
</span></span></code></pre></div><p>On Debian/Ubuntu the files are <code>/etc/bind/rndc.key</code> and <code>/etc/bind/rndc.conf</code>, and the group is <code>bind</code> (there is no <code>named</code> group).</p>
<h3 id="separate-keys-per-purpose">Separate Keys per Purpose <a class="anchor" data-pagefind-ignore href="#separate-keys-per-purpose" aria-label="Link to this section">#</a></h3>
<p>A leaked transfer key should not let anyone stop your server. Use different keys for different functions:</p>
<pre tabindex="0"><code># Administrative key - full access
key &#34;admin-key&#34; {
    algorithm hmac-sha512;
    secret &#34;admin-secret&#34;;
};

# Transfer key - zone transfers only
key &#34;xfr-key&#34; {
    algorithm hmac-sha256;
    secret &#34;transfer-secret&#34;;
};

# Update key - dynamic updates only
key &#34;update-key&#34; {
    algorithm hmac-sha256;
    secret &#34;update-secret&#34;;
};
</code></pre><h3 id="firewall-rules">Firewall Rules <a class="anchor" data-pagefind-ignore href="#firewall-rules" aria-label="Link to this section">#</a></h3>
<p>Restrict the RNDC port to the admin network, as a second layer behind <code>allow</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Allow RNDC only from admin network</span>
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">953</span> -s 192.168.1.0/24 -j ACCEPT
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">953</span> -j DROP
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or with firewalld</span>
</span></span><span class="line"><span class="cl">firewall-cmd --permanent --add-rich-rule<span class="o">=</span><span class="s1">&#39;rule family=ipv4 source address=192.168.1.0/24 port port=953 protocol=tcp accept&#39;</span>
</span></span></code></pre></div><h3 id="avoid-storing-keys-in-main-config">Avoid Storing Keys in Main Config <a class="anchor" data-pagefind-ignore href="#avoid-storing-keys-in-main-config" aria-label="Link to this section">#</a></h3>
<p>Keep secrets in separate files and include them, so you can share <code>named.conf</code> without leaking keys:</p>
<pre tabindex="0"><code>include &#34;/etc/named/keys/rndc.key&#34;;
include &#34;/etc/named/keys/transfer.key&#34;;
</code></pre><p>This keeps sensitive data separate and simplifies key rotation.</p>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>connection refused</code></td>
					<td><code>named</code> not running, or no <code>controls</code> channel on that address/port</td>
			</tr>
			<tr>
					<td><code>connection to remote host closed</code></td>
					<td>Wrong key, wrong source IP, or <code>named</code> cannot read <code>rndc.key</code></td>
			</tr>
			<tr>
					<td><code>decode base64 secret</code></td>
					<td>Secret in <code>rndc.conf</code> is not valid base64</td>
			</tr>
			<tr>
					<td>Permission errors</td>
					<td>File ownership, SELinux or AppArmor</td>
			</tr>
	</tbody>
</table>
<h3 id="connection-refused">Connection Refused <a class="anchor" data-pagefind-ignore href="#connection-refused" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl"><span class="c1"># rndc: connect failed: 127.0.0.1#953: connection refused</span>
</span></span></code></pre></div><p>Check that <code>named</code> is running and the controls statement is configured:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl status named
</span></span><span class="line"><span class="cl">named-checkconf /etc/named.conf
</span></span><span class="line"><span class="cl">ss -tlnp <span class="p">|</span> grep <span class="m">953</span>
</span></span></code></pre></div><h3 id="authentication-failure">Authentication Failure <a class="anchor" data-pagefind-ignore href="#authentication-failure" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl"><span class="c1"># rndc: connection to remote host closed.</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * This may indicate that the</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * remote server is using an older</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * version of the command protocol,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * this host is not authorized to connect,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * the clocks are not synchronized,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * the key signing algorithm is incorrect</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * or the key is invalid.</span>
</span></span></code></pre></div><p>On the server, <code>named</code> logs <code>invalid command from 127.0.0.1#...: bad auth</code>. A secret that is not valid base64 fails earlier, on the client: <code>rndc: decode base64 secret: bad base64 encoding</code>.</p>
<p>Verify keys match between <code>rndc.conf</code> and the key <code>named</code> uses (<code>named.conf</code>, or <code>rndc.key</code> when there is no <code>controls</code> statement):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Compare secrets</span>
</span></span><span class="line"><span class="cl">grep secret /etc/rndc.conf
</span></span><span class="line"><span class="cl">grep -A2 <span class="s1">&#39;key &#34;rndc-key&#34;&#39;</span> /etc/named.conf
</span></span><span class="line"><span class="cl">grep secret /etc/rndc.key
</span></span></code></pre></div><h3 id="permission-denied">Permission Denied <a class="anchor" data-pagefind-ignore href="#permission-denied" aria-label="Link to this section">#</a></h3>
<p>Check file permissions and SELinux:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ls -la /etc/rndc.key
</span></span><span class="line"><span class="cl">getenforce
</span></span><span class="line"><span class="cl">ausearch -m AVC -ts recent <span class="p">|</span> grep named
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-rndc-tsig" rel="noopener">pderuiter/blog-bind-rndc-tsig</a>. It creates a master, a slave and an admin workstation, sets up the admin and read-only monitoring control channels, the TSIG-signed zone transfer and the workstation&rsquo;s <code>rndc.conf</code>; put your keys in an ansible-vault file, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>RNDC and TSIG keys make DNS administration safe to do remotely. Use HMAC-SHA256 or HMAC-SHA512, separate keys per purpose, a read-only channel for monitoring, and restrict network access to the RNDC port.</p>
<p>The next post in this series will cover zone security, including views, ACLs, and query restrictions to protect your DNS infrastructure from abuse.</p>
]]></content:encoded></item></channel></rss>