1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. highlight: console 13 14.. _man_nsupdate: 15 16nsupdate - dynamic DNS update utility 17------------------------------------- 18 19Synopsis 20~~~~~~~~ 21 22:program:`nsupdate` [**-d**] [**-D**] [**-i**] [**-L** level] [ [**-g**] | [**-o**] | [**-l**] | [**-y** [hmac:]keyname:secret] | [**-k** keyfile] ] [**-t** timeout] [**-u** udptimeout] [**-r** udpretries] [**-v**] [**-T**] [**-P**] [**-V**] [ [**-4**] | [**-6**] ] [filename] 23 24Description 25~~~~~~~~~~~ 26 27``nsupdate`` is used to submit Dynamic DNS Update requests, as defined in 28:rfc:`2136`, to a name server. This allows resource records to be added or 29removed from a zone without manually editing the zone file. A single 30update request can contain requests to add or remove more than one 31resource record. 32 33Zones that are under dynamic control via ``nsupdate`` or a DHCP server 34should not be edited by hand. Manual edits could conflict with dynamic 35updates and cause data to be lost. 36 37The resource records that are dynamically added or removed with 38``nsupdate`` must be in the same zone. Requests are sent to the 39zone's primary server, which is identified by the MNAME field of the 40zone's SOA record. 41 42Transaction signatures can be used to authenticate the Dynamic DNS 43updates. These use the TSIG resource record type described in :rfc:`2845`, 44the SIG(0) record described in :rfc:`2535` and :rfc:`2931`, or GSS-TSIG as 45described in :rfc:`3645`. 46 47TSIG relies on a shared secret that should only be known to ``nsupdate`` 48and the name server. For instance, suitable ``key`` and ``server`` 49statements are added to ``/etc/named.conf`` so that the name server 50can associate the appropriate secret key and algorithm with the IP 51address of the client application that is using TSIG 52authentication. ``ddns-confgen`` can generate suitable 53configuration fragments. ``nsupdate`` uses the ``-y`` or ``-k`` options 54to provide the TSIG shared secret; these options are mutually exclusive. 55 56SIG(0) uses public key cryptography. To use a SIG(0) key, the public key 57must be stored in a KEY record in a zone served by the name server. 58 59GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode is switched 60on with the ``-g`` flag. A non-standards-compliant variant of GSS-TSIG 61used by Windows 2000 can be switched on with the ``-o`` flag. 62 63Options 64~~~~~~~ 65 66``-4`` 67 This option sets use of IPv4 only. 68 69``-6`` 70 This option sets use of IPv6 only. 71 72``-d`` 73 This option sets debug mode, which provides tracing information about the update 74 requests that are made and the replies received from the name server. 75 76``-D`` 77 This option sets extra debug mode. 78 79``-i`` 80 This option forces interactive mode, even when standard input is not a terminal. 81 82``-k keyfile`` 83 This option indicates the file containing the TSIG authentication key. Keyfiles may be in 84 two formats: a single file containing a ``named.conf``-format ``key`` 85 statement, which may be generated automatically by ``ddns-confgen``; 86 or a pair of files whose names are of the format 87 ``K{name}.+157.+{random}.key`` and 88 ``K{name}.+157.+{random}.private``, which can be generated by 89 ``dnssec-keygen``. The ``-k`` option can also be used to specify a SIG(0) 90 key used to authenticate Dynamic DNS update requests. In this case, 91 the key specified is not an HMAC-MD5 key. 92 93``-l`` 94 This option sets local-host only mode, which sets the server address to localhost 95 (disabling the ``server`` so that the server address cannot be 96 overridden). Connections to the local server use a TSIG key 97 found in ``/var/run/named/session.key``, which is automatically 98 generated by ``named`` if any local ``primary`` zone has set 99 ``update-policy`` to ``local``. The location of this key file can be 100 overridden with the ``-k`` option. 101 102``-L level`` 103 This option sets the logging debug level. If zero, logging is disabled. 104 105``-p port`` 106 This option sets the port to use for connections to a name server. The default is 107 53. 108 109``-P`` 110 This option prints the list of private BIND-specific resource record types whose 111 format is understood by ``nsupdate``. See also the ``-T`` option. 112 113``-r udpretries`` 114 This option sets the number of UDP retries. The default is 3. If zero, only one update 115 request is made. 116 117``-t timeout`` 118 This option sets the maximum time an update request can take before it is aborted. The 119 default is 300 seconds. If zero, the timeout is disabled. 120 121``-T`` 122 This option prints the list of IANA standard resource record types whose format is 123 understood by ``nsupdate``. ``nsupdate`` exits after the lists 124 are printed. The ``-T`` option can be combined with the ``-P`` 125 option. 126 127 Other types can be entered using ``TYPEXXXXX`` where ``XXXXX`` is the 128 decimal value of the type with no leading zeros. The rdata, if 129 present, is parsed using the UNKNOWN rdata format, (<backslash> 130 <hash> <space> <length> <space> <hexstring>). 131 132``-u udptimeout`` 133 This option sets the UDP retry interval. The default is 3 seconds. If zero, the 134 interval is computed from the timeout interval and number of UDP 135 retries. 136 137``-v`` 138 This option specifies that TCP should be used even for small update requests. By default, ``nsupdate`` uses 139 UDP to send update requests to the name server unless they are too 140 large to fit in a UDP request, in which case TCP is used. TCP may 141 be preferable when a batch of update requests is made. 142 143``-V`` 144 This option prints the version number and exits. 145 146``-y [hmac:]keyname:secret`` 147 This option sets the literal TSIG authentication key. ``keyname`` is the name of the key, 148 and ``secret`` is the base64 encoded shared secret. ``hmac`` is the 149 name of the key algorithm; valid choices are ``hmac-md5``, 150 ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, or 151 ``hmac-sha512``. If ``hmac`` is not specified, the default is 152 ``hmac-md5``, or if MD5 was disabled, ``hmac-sha256``. 153 154 NOTE: Use of the ``-y`` option is discouraged because the shared 155 secret is supplied as a command-line argument in clear text. This may 156 be visible in the output from ps1 or in a history file maintained by 157 the user's shell. 158 159Input Format 160~~~~~~~~~~~~ 161 162``nsupdate`` reads input from ``filename`` or standard input. Each 163command is supplied on exactly one line of input. Some commands are for 164administrative purposes; others are either update instructions or 165prerequisite checks on the contents of the zone. These checks set 166conditions that some name or set of resource records (RRset) either 167exists or is absent from the zone. These conditions must be met if the 168entire update request is to succeed. Updates are rejected if the 169tests for the prerequisite conditions fail. 170 171Every update request consists of zero or more prerequisites and zero or 172more updates. This allows a suitably authenticated update request to 173proceed if some specified resource records are either present or missing from 174the zone. A blank input line (or the ``send`` command) causes the 175accumulated commands to be sent as one Dynamic DNS update request to the 176name server. 177 178The command formats and their meanings are as follows: 179 180``server servername port`` 181 This command sends all dynamic update requests to the name server ``servername``. 182 When no server statement is provided, ``nsupdate`` sends updates 183 to the primary server of the correct zone. The MNAME field of that 184 zone's SOA record identify the primary server for that zone. 185 ``port`` is the port number on ``servername`` where the dynamic 186 update requests are sent. If no port number is specified, the default 187 DNS port number of 53 is used. 188 189 .. note:: This command has no effect when GSS-TSIG is in use. 190 191``local address port`` 192 This command sends all dynamic update requests using the local ``address``. When 193 no local statement is provided, ``nsupdate`` sends updates using 194 an address and port chosen by the system. ``port`` can also 195 be used to force requests to come from a specific port. If no port number 196 is specified, the system assigns one. 197 198``zone zonename`` 199 This command specifies that all updates are to be made to the zone ``zonename``. 200 If no ``zone`` statement is provided, ``nsupdate`` attempts to 201 determine the correct zone to update based on the rest of the input. 202 203``class classname`` 204 This command specifies the default class. If no ``class`` is specified, the default 205 class is ``IN``. 206 207``ttl seconds`` 208 This command specifies the default time-to-live, in seconds, for records to be added. The value 209 ``none`` clears the default TTL. 210 211``key hmac:keyname secret`` 212 This command specifies that all updates are to be TSIG-signed using the 213 ``keyname``-``secret`` pair. If ``hmac`` is specified, it sets 214 the signing algorithm in use. The default is ``hmac-md5``; if MD5 215 was disabled, the default is ``hmac-sha256``. The ``key`` command overrides any key 216 specified on the command line via ``-y`` or ``-k``. 217 218``gsstsig`` 219 This command uses GSS-TSIG to sign the updates. This is equivalent to specifying 220 ``-g`` on the command line. 221 222``oldgsstsig`` 223 This command uses the Windows 2000 version of GSS-TSIG to sign the updates. This is 224 equivalent to specifying ``-o`` on the command line. 225 226``realm [realm_name]`` 227 When using GSS-TSIG, this command specifies the use of ``realm_name`` rather than the default realm 228 in ``krb5.conf``. If no realm is specified, the saved realm is 229 cleared. 230 231``check-names [yes_or_no]`` 232 This command turns on or off check-names processing on records to be added. 233 Check-names has no effect on prerequisites or records to be deleted. 234 By default check-names processing is on. If check-names processing 235 fails, the record is not added to the UPDATE message. 236 237``prereq nxdomain domain-name`` 238 This command requires that no resource record of any type exist with the name 239 ``domain-name``. 240 241``prereq yxdomain domain-name`` 242 This command requires that ``domain-name`` exist (as at least one resource 243 record, of any type). 244 245``prereq nxrrset domain-name class type`` 246 This command requires that no resource record exist of the specified ``type``, 247 ``class``, and ``domain-name``. If ``class`` is omitted, IN (Internet) 248 is assumed. 249 250``prereq yxrrset domain-name class type`` 251 This command requires that a resource record of the specified ``type``, 252 ``class`` and ``domain-name`` exist. If ``class`` is omitted, IN 253 (internet) is assumed. 254 255``prereq yxrrset domain-name class type data`` 256 With this command, the ``data`` from each set of prerequisites of this form sharing a 257 common ``type``, ``class``, and ``domain-name`` are combined to form 258 a set of RRs. This set of RRs must exactly match the set of RRs 259 existing in the zone at the given ``type``, ``class``, and 260 ``domain-name``. The ``data`` are written in the standard text 261 representation of the resource record's RDATA. 262 263``update delete domain-name ttl class type data`` 264 This command deletes any resource records named ``domain-name``. If ``type`` and 265 ``data`` are provided, only matching resource records are removed. 266 The Internet class is assumed if ``class`` is not supplied. The 267 ``ttl`` is ignored, and is only allowed for compatibility. 268 269``update add domain-name ttl class type data`` 270 This command adds a new resource record with the specified ``ttl``, ``class``, and 271 ``data``. 272 273``show`` 274 This command displays the current message, containing all of the prerequisites and 275 updates specified since the last send. 276 277``send`` 278 This command sends the current message. This is equivalent to entering a blank 279 line. 280 281``answer`` 282 This command displays the answer. 283 284``debug`` 285 This command turns on debugging. 286 287``version`` 288 This command prints the version number. 289 290``help`` 291 This command prints a list of commands. 292 293Lines beginning with a semicolon (;) are comments and are ignored. 294 295Examples 296~~~~~~~~ 297 298The examples below show how ``nsupdate`` can be used to insert and 299delete resource records from the ``example.com`` zone. Notice that the 300input in each example contains a trailing blank line, so that a group of 301commands is sent as one dynamic update request to the primary name 302server for ``example.com``. 303 304:: 305 306 # nsupdate 307 > update delete oldhost.example.com A 308 > update add newhost.example.com 86400 A 172.16.1.1 309 > send 310 311Any A records for ``oldhost.example.com`` are deleted, and an A record 312for ``newhost.example.com`` with IP address 172.16.1.1 is added. The 313newly added record has a TTL of 1 day (86400 seconds). 314 315:: 316 317 # nsupdate 318 > prereq nxdomain nickname.example.com 319 > update add nickname.example.com 86400 CNAME somehost.example.com 320 > send 321 322The prerequisite condition tells the name server to verify that there are 323no resource records of any type for ``nickname.example.com``. If there 324are, the update request fails. If this name does not exist, a CNAME for 325it is added. This ensures that when the CNAME is added, it cannot 326conflict with the long-standing rule in :rfc:`1034` that a name must not 327exist as any other record type if it exists as a CNAME. (The rule has 328been updated for DNSSEC in :rfc:`2535` to allow CNAMEs to have RRSIG, 329DNSKEY, and NSEC records.) 330 331Files 332~~~~~ 333 334``/etc/resolv.conf`` 335 Used to identify the default name server 336 337``/var/run/named/session.key`` 338 Sets the default TSIG key for use in local-only mode 339 340``K{name}.+157.+{random}.key`` 341 Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``. 342 343``K{name}.+157.+{random}.private`` 344 Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``. 345 346See Also 347~~~~~~~~ 348 349:rfc:`2136`, :rfc:`3007`, :rfc:`2104`, :rfc:`2845`, :rfc:`1034`, :rfc:`2535`, :rfc:`2931`, 350:manpage:`named(8)`, :manpage:`ddns-confgen(8)`, :manpage:`dnssec-keygen(8)`. 351 352Bugs 353~~~~ 354 355The TSIG key is redundantly stored in two separate files. This is a 356consequence of ``nsupdate`` using the DST library for its cryptographic 357operations, and may change in future releases. 358