summaryrefslogtreecommitdiffstats
path: root/doc/man_knsupdate.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man_knsupdate.rst')
-rw-r--r--doc/man_knsupdate.rst188
1 files changed, 188 insertions, 0 deletions
diff --git a/doc/man_knsupdate.rst b/doc/man_knsupdate.rst
new file mode 100644
index 0000000..40a419b
--- /dev/null
+++ b/doc/man_knsupdate.rst
@@ -0,0 +1,188 @@
+.. highlight:: none
+
+``knsupdate`` – Dynamic DNS update utility
+==========================================
+
+Synopsis
+--------
+
+:program:`knsupdate` [*options*] [*filename*]
+
+Description
+-----------
+
+This utility sends Dynamic DNS update messages to a DNS server. Update content
+is read from a file (if the parameter *filename* is given) or from the standard
+input.
+
+The format of updates is textual and is made up of commands. Every command is
+placed on the separate line of the input. Lines starting with a semicolon are
+comments and are not processed.
+
+Parameters
+..........
+
+*filename*
+ Path to the file with knsupdate commands.
+
+Options
+.......
+
+**-d**
+ Enable debug messages.
+
+**-h**, **--help**
+ Print the program help.
+
+**-k** *keyfile*
+ Use the TSIG key stored in a file *keyfile* to authenticate the request. The
+ file should contain the key in the same format, which is accepted by the
+ **-y** option.
+
+**-p** *port*
+ Set the port to use for connections to the server (if not explicitly specified
+ in the update). The default is 53.
+
+**-r** *retries*
+ The number of retries for UDP requests. The default is 3.
+
+**-t** *timeout*
+ The total timeout (for all UDP update tries) of the update request in seconds.
+ The default is 12. If set to zero, the timeout is infinite.
+
+**-v**
+ Use a TCP connection.
+
+**-V**, **--version**
+ Print the program version.
+
+**-y** [*alg*:]\ *name*:*key*
+ Use the TSIG key with a name *name* to authenticate the request. The *alg*
+ part specifies the algorithm (the default is hmac-sha256) and *key* specifies
+ the shared secret encoded in Base64.
+
+Commands
+........
+
+**server** *name* [*port*]
+ Specifies a receiving server of the dynamic update message. The *name* parameter
+ can be either a host name or an IP address. If the *port* is not specified,
+ the default port is used. The default port value can be controlled using
+ the **-p** program option.
+
+**local** *address* [*port*]
+ Specifies outgoing *address* and *port*. If no local is specified, the
+ address and port are set by the system automatically. The default port number
+ is 0.
+
+**zone** *name*
+ Specifies that all updates are done within a zone *name*. The zone name doesn't
+ have a default and must be set explicitly.
+
+**origin** *name*
+ Specifies fully qualified domain name suffix which is appended to non-fqd
+ owners in update commands. The default is the terminal label (**.**).
+
+**class** *name*
+ Sets *name* as the default class for all updates. If not used, the default
+ class is IN.
+
+**ttl** *value*
+ Sets *value* as the default TTL (in seconds). If not used, the default value
+ is 3600.
+
+**key** [*alg*:]\ *name* *key*
+ Specifies the TSIG *key* named *name* to authenticate the request. An optional
+ *alg* algorithm can be specified. This command has the same effect as
+ the program option **-y**.
+
+[**prereq**] **nxdomain** *name*
+ Adds a prerequisite for a non-existing record owned by *name*.
+
+[**prereq**] **yxdomain** *name*
+ Adds a prerequisite for an existing record owned by *name*.
+
+[**prereq**] **nxrrset** *name* [*class*] *type*
+ Adds a prerequisite for a non-existing record of the *type* owned by *name*.
+ Internet *class* is expected.
+
+[**prereq**] **yxrrset** *name* [*class*] *type* [*data*]
+ Adds a prerequisite for an existing record of the *type* owned by *name*
+ with optional *data*. Internet *class* is expected.
+
+[**update**] **add** *name* [*ttl*] [*class*] *type* *data*
+ Adds a request to add a new resource record into the zone.
+ Please note that if the *name* is not fully qualified domain name, the
+ current origin name is appended to it.
+
+[**update**] **del**\[**ete**] *name* [*ttl*] [*class*] [*type*] [*data*]
+ Adds a request to remove all (or matching *class*, *type* or *data*)
+ resource records from the zone. There is the same requirement for the *name*
+ parameter as in **update add** command. The *ttl* item is ignored.
+
+**show**
+ Displays current content of the update message.
+
+**send**
+ Sends the current update message and cleans the list of updates.
+
+**answer**
+ Displays the last answer from the server.
+
+**debug**
+ Enable debugging. This command has the same meaning as the **-d** program option.
+
+**exit**
+ End the program.
+
+Notes
+-----
+
+Options **-k** and **-y** can not be used simultaneously.
+
+Neither `tsig-keygen(8)` nor `dnssec-keygen(1)` keyfile formats are supported.
+Use :manpage:`keymgr(8)` to construct a string for **-y** or the file passed to **-k**.
+
+Zone name/server guessing is not supported if the zone name/server is not specified.
+
+An empty line doesn't send the update.
+
+Interactive mode
+................
+
+The utility provides interactive mode with basic line editing functionality,
+command completion, and command history.
+
+Interactive mode behavior can be customized in `~/.editrc`. Refer to
+:manpage:`editrc(5)` for details.
+
+Command history is saved in `~/.knsupdate_history`.
+
+Exit values
+-----------
+
+Exit status of 0 means successful operation. Any other exit status indicates
+an error.
+
+Examples
+--------
+
+1. Send one update of the zone example.com to the server 192.168.1.1. The update
+ contains two new records::
+
+ $ knsupdate
+ knsupdate> server 192.168.1.1
+ knsupdate> zone example.com.
+ knsupdate> origin example.com.
+ knsupdate> ttl 3600
+ knsupdate> add test1.example.com. 7200 A 192.168.2.2
+ knsupdate> add test2 TXT "hello"
+ knsupdate> show
+ knsupdate> send
+ knsupdate> answer
+ knsupdate> exit
+
+See Also
+--------
+
+:manpage:`kdig(1)`, :manpage:`khost(1)`, :manpage:`keymgr(8)`, :manpage:`editrc(5)`.