diff options
Diffstat (limited to 'doc/man_knsupdate.rst')
| -rw-r--r-- | doc/man_knsupdate.rst | 188 |
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)`. |