Skip to content

How to use the RFC2136 Plugin

This plugin works against any DNS provider that supports dynamic updates using the protocol specified in RFC 2136. Both unauthenticated and TSIG authenticated updates are supported.

Setup

It is beyond the scope of this guide to explain how to configure your DNS server to accept dynamic updates or generate a TSIG key to use for authentication. But if you're using BIND, the Dynamic Update Policies section of the official docs is a good place to start. There are also a variety of tutorials available with a quick web search.

The plugin does not currently support Kerberos (GSS-TSIG) based updates. You must either use unauthenticated updates with an IP whitelist or TSIG authenticated updates using a key type supported by your DNS server and the nsupdate utility. As of this writing, the current stable version of BIND is 9.16.20 and supports key types using the following algorithms:

  • hmac-md5
  • hmac-sha1
  • hmac-sha224
  • hmac-sha256
  • hmac-sha384
  • hmac-sha512

When using a TSIG key, you will typically have 3 values; a key name, a key type from the list above, and a Base64 encoded key value. You will need to supply all three as plugin parameters.

Plugin Dependencies

Due to the inexplicable lack of good native DNS libraries within PowerShell/.NET, this plugin relies on the nsupdate utility which is part of the ISC BIND distribution. Most modern Linux distributions will have this installed by default, but double check to be sure. On Windows, you will need to download and install the utility. Go to the ISC BIND Downloads page and download the current stable version for Windows. You don't actually need to run the installer. It is sufficient to simply unzip the archive and either add that folder to your PATH environment variable or specify the full path to nsupdate.exe in the plugin arguments. (Adding the folder to your PATH also gives you easy access to the dig utility which many DNS admins prefer over nslookup)

Note

Some users have reported needing to install Visual C++ Redistributable libraries in order for the unzip-and-run method to work. Many systems will already have these installed. But if not, among the files unzipped should be a vcredist_x64.exe installer you can use. You can test by running nsupdate -V to check the version.

Using the Plugin

When using unauthenticated updates, the only required parameter is DDNSNameserver which is the IP or hostname of the authoritative DNS server that will accept dynamic updates for the zone your TXT record lives in. You may also provide DDNSPort if your server is not listening on the standard port 53.

When using TSIG authenticated updates, in addition to the previous parameters you must also supply DDNSKeyName, DDNSKeyType, and DDNSKeyValue which is a SecureString object.

Warning

The DDNSKeyValueInsecure parameter is deprecated and will be removed in the next major module version. If you are using it, please migrate to the Secure parameter set.

If the nsupdate utility is not in your PATH environment variable, you must also supply the full path to it using the DDNSExePath parameter.

There is an optional DDNSZone parameter which allows you to specify the zone(s) the records will be added to. But this shouldn't normally be necessary. See issue #307 for more info.

Here are a few examples using different combinations of parameters.

TSIG and explicit nsupdate path

$pArgs = @{
    DDNSNameserver = 'ns.example.com'
    DDNSKeyName = 'mykey'
    DDNSKeyType = 'hmac-sha256'
    DDNSKeyValue = (Read-Host 'TSIG Key Value' -AsSecureString)
    DDNSExePath = 'C:\BIND\nsupdate.exe'
}
New-PACertificate example.com -Plugin RFC2136 -PluginArgs $pArgs

Unauthenticated with nsupdate in PATH and alternate port

$pArgs = @{
    DDNSNameserver = 'ns.example.com'
    DDNSPort = 54
}
New-PACertificate example.com -Plugin RFC2136 -PluginArgs $pArgs