manual page for knsupdate

refs #2380

Change-Id: I940a3193f39568ed3868bbe730d131edacb56620

man/knsupdate.8in

@@ -2,38 +2,132 @@
 .SH NAME
 .TP 10
 .B knsupdate
-\- Dynamic DNS update utility (libknot equivalent of ISC
-  nsupdate)
+\- Dynamic DNS update utility (libknot equivalent of ISC nsupdate)
 .SH SYNOPSIS
 .B knsupdate
 [\fIoptions\fR] [\fIfilename\fR]
+
 .SH DESCRIPTION
 
+The utility sends Dynamic DNS update message to DNS server. Update content is
+read from a file (if the parameter \fIfilename\fR is given) or from standard
+input. The format of the update is described in \fBINPUT FORMAT\fR section.
+
 .SH OPTIONS
 .TP 4
 .BI -d
-Enable debug messages if any.
+Enable debugging messages.
 .TP
 .BI -v
-Use TCP protocol.
+Use TCP protocol instead of the default UDP.
 .TP
 .BI -p \ port
-Set the default port.
+Set the port to use when connecting to server and the port was not explicitly
+specified in the update. The default is 53.
 .TP
 .BI -t \ timeout
-The query timeout (default 300 seconds).
+The timeout of the update request in seconds. The default is 12. If set to
+zero, the timeout is infinite.
 .TP
 .BI -r \ retries
-The number of UDP retries (default 3).
+The number of retries for UDP requests. The default is 3. Partial timeout for
+each try is computed from total timeout (option \fB-t\fR).
+.TP
+.BI -k \ keyfile
+Use TSIG or SIG\-0 key stored in file to authenticate the request. The tool
+supports keys generated by ISC \fBdnssec\-keygen\fR. The key comprises of
+public (.key extension) and private part (.private extension). Either of these
+file names or a name without the extension can be specified as \fIkeyfile\fR
+parameter.
+
 .TP
 .BI -y \ \fR[\fIhmac:\fR]\fIname:key\fR]
-Use TSIG.
-.SH FILES
-.BI /etc/resolv.conf
-.SH AUTHOR
-Marek Vavruša (\fBhttp://knot-dns.cz\fR)
+Use TSIG key to to authenticate the request. The \fIhmac\fR part specifies the
+algorithm (the default is hmac\-md5), \fIname\fR specifies the key name, and
+\fIkey\fR specifies the shared secret encoded in Base64.
+
+.TP
+Options \fB-k\fR and \fB-y\fR cannot be used mutually.
+
+.SH INPUT FORMAT
+
+The input format is textual and is made up of commands. Every command is placed
+on a separate line of the input. Lines starting with a semicolon are comments
+and are not processed.
+
+List of commands format and their description:
+
+.TP
+\fBserver\fR \fIname\fR [\fIport\fR]
+
+Specifies a receiving server of the dynamic update message. Parameter \fIname\fR
+can be either a host name or an IP address. If the \fIport\fR is not specified,
+default port is used. The default port value can be controlled using program
+option \fB-p\fR.
+
+.TP
+\fBzone\fR \fIname\fR
+
+Specifies that all updates are done within a zone named \fIname\fR. If not used,
+the default zone is the root zone.
+
+.TP
+\fBclass\fR \fIname\fR
+
+Sets \fIname\fR as a default class for all updates. If not used, the default
+class is IN.
+
+.TP
+\fBttl\fR \fIvalue\fR
+
+Sets \fIvalue\fR as a default TTL (time to live) in seconds. If not used, the
+default value is zero.
+
 .TP
-Please send any bugs or comments to \fBknot-dns@labs.nic.cz\fR
+\fBkey\fB \fIname\fR \fIkey\fR
+
+Specifies TSIG key to authenticate the request. This command has the same
+semantics as the program option \fB\-y\fR, except that the MAC algorithm
+cannot be set.
+
+.TP
+[\fBupdate\fR] \fBadd\fR \fIname\fR \fIttl\fR [\fIclass\fR] \fItype\fR \fIdata\fR
+
+Adds a request to add a new resource record into the zone. Please note that the
+\fIname\fR must be fully qualified domain name (zone name is not appended to it).
+
+.TP
+[\fBupdate\fR] \fBdel\fR[\fBete\fR] \fIname\fR \fIttl\fR [\fIclass\fR] \fItype\fR \fIdata\fR
+
+Adds a request to remove an existing resource record from the zone. There is
+the same requirement for the \fIname\fR parameter as in the \fBupdate add\fR
+command.
+
+.TP
+\fBshow\fR
+
+Displays current content of the update message.
+
+.TP
+\fBsend\fR
+
+Sends the current update message and cleans the list of updates.
+
+.TP
+\fBanswer\fR
+
+Displays the last answer from the server.
+
+.TP
+\fBdebug\fR
+
+Enable debugging. This command has the same meaning as program option \fB\-d\fR.
+
+.SH BUGS
+
+Please note that there are slight differences from ISC nsupdate and some
+features are not supported. Any bugs, comments, or feature requests can be sent
+to \fBknot-dns@labs.nic.cz\fR.
 .SH SEE ALSO
 .BI khost\fR(8),
 .BI kdig\fR(8).