Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 391 insertions, 0 deletions

diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst
new file mode 100644
index 0000000..81bb481
--- /dev/null
+++ b/bin/nsupdate/nsupdate.rst
@@ -0,0 +1,391 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0.  If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. iscman:: nsupdate
+.. program:: nsupdate
+.. _man_nsupdate:
+
+nsupdate - dynamic DNS update utility
+-------------------------------------
+
+Synopsis
+~~~~~~~~
+
+: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]
+
+Description
+~~~~~~~~~~~
+
+:program:`nsupdate` is used to submit Dynamic DNS Update requests, as defined in
+:rfc:`2136`, to a name server. This allows resource records to be added or
+removed from a zone without manually editing the zone file. A single
+update request can contain requests to add or remove more than one
+resource record.
+
+Zones that are under dynamic control via :program:`nsupdate` or a DHCP server
+should not be edited by hand. Manual edits could conflict with dynamic
+updates and cause data to be lost.
+
+The resource records that are dynamically added or removed with
+:program:`nsupdate` must be in the same zone. Requests are sent to the
+zone's primary server, which is identified by the MNAME field of the
+zone's SOA record.
+
+Transaction signatures can be used to authenticate the Dynamic DNS
+updates. These use the TSIG resource record type described in :rfc:`2845`,
+the SIG(0) record described in :rfc:`2535` and :rfc:`2931`, or GSS-TSIG as
+described in :rfc:`3645`.
+
+TSIG relies on a shared secret that should only be known to :program:`nsupdate`
+and the name server. For instance, suitable ``key`` and ``server``
+statements are added to |named_conf| so that the name server
+can associate the appropriate secret key and algorithm with the IP
+address of the client application that is using TSIG
+authentication. :iscman:`ddns-confgen` can generate suitable
+configuration fragments. :program:`nsupdate` uses the :option:`-y` or :option:`-k` options
+to provide the TSIG shared secret; these options are mutually exclusive.
+
+SIG(0) uses public key cryptography. To use a SIG(0) key, the public key
+must be stored in a KEY record in a zone served by the name server.
+
+GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode is switched
+on with the :option:`-g` flag. A non-standards-compliant variant of GSS-TSIG
+used by Windows 2000 can be switched on with the :option:`-o` flag.
+
+Options
+~~~~~~~
+
+.. option:: -4
+
+   This option sets use of IPv4 only.
+
+.. option:: -6
+
+   This option sets use of IPv6 only.
+
+.. option:: -C
+
+   Overrides the default `resolv.conf` file. This is only intended for testing.
+
+.. option:: -d
+
+   This option sets debug mode, which provides tracing information about the update
+   requests that are made and the replies received from the name server.
+
+.. option:: -D
+
+   This option sets extra debug mode.
+
+.. option:: -g
+
+   This option enables standard GSS-TSIG mode.
+
+.. option:: -i
+
+   This option forces interactive mode, even when standard input is not a terminal.
+
+.. option:: -k keyfile
+
+   This option indicates the file containing the TSIG authentication key. Keyfiles may be in
+   two formats: a single file containing a :iscman:`named.conf`-format ``key``
+   statement, which may be generated automatically by :iscman:`ddns-confgen`;
+   or a pair of files whose names are of the format
+   ``K{name}.+157.+{random}.key`` and
+   ``K{name}.+157.+{random}.private``, which can be generated by
+   :iscman:`dnssec-keygen`. The :option:`-k` option can also be used to specify a SIG(0)
+   key used to authenticate Dynamic DNS update requests. In this case,
+   the key specified is not an HMAC-MD5 key.
+
+.. option:: -l
+
+   This option sets local-host only mode, which sets the server address to localhost
+   (disabling the ``server`` so that the server address cannot be
+   overridden). Connections to the local server use a TSIG key
+   found in |session_key|, which is automatically
+   generated by :iscman:`named` if any local ``primary`` zone has set
+   ``update-policy`` to ``local``. The location of this key file can be
+   overridden with the :option:`-k` option.
+
+.. option:: -L level
+
+   This option sets the logging debug level. If zero, logging is disabled.
+
+.. option:: -o
+
+   This option enables a non-standards-compliant variant of GSS-TSIG
+   used by Windows 2000.
+
+.. option:: -p port
+
+   This option sets the port to use for connections to a name server. The default is
+   53.
+
+.. option:: -P
+
+   This option prints the list of private BIND-specific resource record types whose
+   format is understood by :program:`nsupdate`. See also the :option:`-T` option.
+
+.. option:: -r udpretries
+
+   This option sets the number of UDP retries. The default is 3. If zero, only one update
+   request is made.
+
+.. option:: -t timeout
+
+   This option sets the maximum time an update request can take before it is aborted. The
+   default is 300 seconds. If zero, the timeout is disabled for TCP mode. For UDP mode,
+   the option :option:`-u` takes precedence over this option, unless the option :option:`-u`
+   is set to zero, in which case the interval is computed from the :option:`-t` timeout interval
+   and the number of UDP retries. For UDP mode, the timeout can not be disabled, and will
+   be rounded up to 1 second in case if both :option:`-t` and :option:`-u` are set to zero.
+
+.. option:: -T
+
+   This option prints the list of IANA standard resource record types whose format is
+   understood by :program:`nsupdate`. :program:`nsupdate` exits after the lists
+   are printed. The :option:`-T` option can be combined with the :option:`-P`
+   option.
+
+   Other types can be entered using ``TYPEXXXXX`` where ``XXXXX`` is the
+   decimal value of the type with no leading zeros. The rdata, if
+   present, is parsed using the UNKNOWN rdata format, (<backslash>
+   <hash> <space> <length> <space> <hexstring>).
+
+.. option:: -u udptimeout
+
+   This option sets the UDP retry interval. The default is 3 seconds. If zero, the
+   interval is computed from the timeout interval and number of UDP
+   retries.
+
+.. option:: -v
+
+   This option specifies that TCP should be used even for small update requests. By default, :program:`nsupdate` uses
+   UDP to send update requests to the name server unless they are too
+   large to fit in a UDP request, in which case TCP is used. TCP may
+   be preferable when a batch of update requests is made.
+
+.. option:: -V
+
+   This option prints the version number and exits.
+
+.. option:: -y [hmac:]keyname:secret
+
+   This option sets the literal TSIG authentication key. ``keyname`` is the name of the key,
+   and ``secret`` is the base64 encoded shared secret. ``hmac`` is the
+   name of the key algorithm; valid choices are ``hmac-md5``,
+   ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, or
+   ``hmac-sha512``. If ``hmac`` is not specified, the default is
+   ``hmac-md5``, or if MD5 was disabled, ``hmac-sha256``.
+
+   NOTE: Use of the :option:`-y` option is discouraged because the shared
+   secret is supplied as a command-line argument in clear text. This may
+   be visible in the output from ps1 or in a history file maintained by
+   the user's shell.
+
+Input Format
+~~~~~~~~~~~~
+
+:program:`nsupdate` reads input from ``filename`` or standard input. Each
+command is supplied on exactly one line of input. Some commands are for
+administrative purposes; others are either update instructions or
+prerequisite checks on the contents of the zone. These checks set
+conditions that some name or set of resource records (RRset) either
+exists or is absent from the zone. These conditions must be met if the
+entire update request is to succeed. Updates are rejected if the
+tests for the prerequisite conditions fail.
+
+Every update request consists of zero or more prerequisites and zero or
+more updates. This allows a suitably authenticated update request to
+proceed if some specified resource records are either present or missing from
+the zone. A blank input line (or the ``send`` command) causes the
+accumulated commands to be sent as one Dynamic DNS update request to the
+name server.
+
+The command formats and their meanings are as follows:
+
+``server servername port``
+   This command sends all dynamic update requests to the name server ``servername``.
+   When no server statement is provided, :program:`nsupdate` sends updates
+   to the primary server of the correct zone. The MNAME field of that
+   zone's SOA record identify the primary server for that zone.
+   ``port`` is the port number on ``servername`` where the dynamic
+   update requests are sent. If no port number is specified, the default
+   DNS port number of 53 is used.
+
+   .. note:: This command has no effect when GSS-TSIG is in use.
+
+``local address port``
+   This command sends all dynamic update requests using the local ``address``. When
+   no local statement is provided, :program:`nsupdate` sends updates using
+   an address and port chosen by the system. ``port`` can also
+   be used to force requests to come from a specific port. If no port number
+   is specified, the system assigns one.
+
+``zone zonename``
+   This command specifies that all updates are to be made to the zone ``zonename``.
+   If no ``zone`` statement is provided, :program:`nsupdate` attempts to
+   determine the correct zone to update based on the rest of the input.
+
+``class classname``
+   This command specifies the default class. If no ``class`` is specified, the default
+   class is ``IN``.
+
+``ttl seconds``
+   This command specifies the default time-to-live, in seconds, for records to be added. The value
+   ``none`` clears the default TTL.
+
+``key hmac:keyname secret``
+   This command specifies that all updates are to be TSIG-signed using the
+   ``keyname``-``secret`` pair. If ``hmac`` is specified, it sets
+   the signing algorithm in use. The default is ``hmac-md5``; if MD5
+   was disabled, the default is ``hmac-sha256``. The ``key`` command overrides any key
+   specified on the command line via :option:`-y` or :option:`-k`.
+
+``gsstsig``
+   This command uses GSS-TSIG to sign the updates. This is equivalent to specifying
+   :option:`-g` on the command line.
+
+``oldgsstsig``
+   This command uses the Windows 2000 version of GSS-TSIG to sign the updates. This is
+   equivalent to specifying :option:`-o` on the command line.
+
+``realm [realm_name]``
+   When using GSS-TSIG, this command specifies the use of ``realm_name`` rather than the default realm
+   in ``krb5.conf``. If no realm is specified, the saved realm is
+   cleared.
+
+``check-names [boolean]``
+   This command turns on or off check-names processing on records to be added.
+   Check-names has no effect on prerequisites or records to be deleted.
+   By default check-names processing is on. If check-names processing
+   fails, the record is not added to the UPDATE message.
+
+``prereq nxdomain domain-name``
+   This command requires that no resource record of any type exist with the name
+   ``domain-name``.
+
+``prereq yxdomain domain-name``
+   This command requires that ``domain-name`` exist (as at least one resource
+   record, of any type).
+
+``prereq nxrrset domain-name class type``
+   This command requires that no resource record exist of the specified ``type``,
+   ``class``, and ``domain-name``. If ``class`` is omitted, IN (Internet)
+   is assumed.
+
+``prereq yxrrset domain-name class type``
+   This command requires that a resource record of the specified ``type``,
+   ``class`` and ``domain-name`` exist. If ``class`` is omitted, IN
+   (internet) is assumed.
+
+``prereq yxrrset domain-name class type data``
+   With this command, the ``data`` from each set of prerequisites of this form sharing a
+   common ``type``, ``class``, and ``domain-name`` are combined to form
+   a set of RRs. This set of RRs must exactly match the set of RRs
+   existing in the zone at the given ``type``, ``class``, and
+   ``domain-name``. The ``data`` are written in the standard text
+   representation of the resource record's RDATA.
+
+``update delete domain-name ttl class type data``
+   This command deletes any resource records named ``domain-name``. If ``type`` and
+   ``data`` are provided, only matching resource records are removed.
+   The Internet class is assumed if ``class`` is not supplied. The
+   ``ttl`` is ignored, and is only allowed for compatibility.
+
+``update add domain-name ttl class type data``
+   This command adds a new resource record with the specified ``ttl``, ``class``, and
+   ``data``.
+
+``show``
+   This command displays the current message, containing all of the prerequisites and
+   updates specified since the last send.
+
+``send``
+   This command sends the current message. This is equivalent to entering a blank
+   line.
+
+``answer``
+   This command displays the answer.
+
+``debug``
+   This command turns on debugging.
+
+``version``
+   This command prints the version number.
+
+``help``
+   This command prints a list of commands.
+
+Lines beginning with a semicolon (;) are comments and are ignored.
+
+Examples
+~~~~~~~~
+
+The examples below show how :program:`nsupdate` can be used to insert and
+delete resource records from the ``example.com`` zone. Notice that the
+input in each example contains a trailing blank line, so that a group of
+commands is sent as one dynamic update request to the primary name
+server for ``example.com``.
+
+::
+
+   # nsupdate
+   > update delete oldhost.example.com A
+   > update add newhost.example.com 86400 A 172.16.1.1
+   > send
+
+Any A records for ``oldhost.example.com`` are deleted, and an A record
+for ``newhost.example.com`` with IP address 172.16.1.1 is added. The
+newly added record has a TTL of 1 day (86400 seconds).
+
+::
+
+   # nsupdate
+   > prereq nxdomain nickname.example.com
+   > update add nickname.example.com 86400 CNAME somehost.example.com
+   > send
+
+The prerequisite condition tells the name server to verify that there are
+no resource records of any type for ``nickname.example.com``. If there
+are, the update request fails. If this name does not exist, a CNAME for
+it is added. This ensures that when the CNAME is added, it cannot
+conflict with the long-standing rule in :rfc:`1034` that a name must not
+exist as any other record type if it exists as a CNAME. (The rule has
+been updated for DNSSEC in :rfc:`2535` to allow CNAMEs to have RRSIG,
+DNSKEY, and NSEC records.)
+
+Files
+~~~~~
+
+``/etc/resolv.conf``
+   Used to identify the default name server
+
+|session_key|
+   Sets the default TSIG key for use in local-only mode
+
+``K{name}.+157.+{random}.key``
+   Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`.
+
+``K{name}.+157.+{random}.private``
+   Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`.
+
+See Also
+~~~~~~~~
+
+:rfc:`2136`, :rfc:`3007`, :rfc:`2104`, :rfc:`2845`, :rfc:`1034`, :rfc:`2535`, :rfc:`2931`,
+:iscman:`named(8) <named>`, :iscman:`dnssec-keygen(8) <dnssec-keygen>`, :iscman:`tsig-keygen(8) <tsig-keygen>`.
+
+Bugs
+~~~~
+
+The TSIG key is redundantly stored in two separate files. This is a
+consequence of :program:`nsupdate` using the DST library for its cryptographic
+operations, and may change in future releases.