path: root/doc/man/knsupdate.1in

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "KNSUPDATE" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS"
.SH NAME
knsupdate \- Dynamic DNS update utility
.SH SYNOPSIS
.sp
\fBknsupdate\fP [\fIoptions\fP] [\fIfilename\fP]
.SH DESCRIPTION
.sp
This utility sends Dynamic DNS update messages to a DNS server. Update content
is read from a file (if the parameter \fIfilename\fP is given) or from the standard
input.
.sp
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.
.SS Parameters
.INDENT 0.0
.TP
\fIfilename\fP
Path to the file with knsupdate commands.
.UNINDENT
.SS Options
.INDENT 0.0
.TP
\fB\-d\fP
Enable debug messages.
.TP
\fB\-h\fP, \fB\-\-help\fP
Print the program help.
.TP
\fB\-k\fP \fIkeyfile\fP
Use the TSIG key stored in a file \fIkeyfile\fP to authenticate the request. The
file should contain the key in the same format, which is accepted by the
\fB\-y\fP option.
.TP
\fB\-p\fP \fIport\fP
Set the port to use for connections to the server (if not explicitly specified
in the update). The default is 53.
.TP
\fB\-r\fP \fIretries\fP
The number of retries for UDP requests. The default is 3.
.TP
\fB\-t\fP \fItimeout\fP
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.
.TP
\fB\-v\fP
Use a TCP connection.
.TP
\fB\-V\fP, \fB\-\-version\fP
Print the program version.
.TP
\fB\-y\fP [\fIalg\fP:]\fIname\fP:\fIkey\fP
Use the TSIG key with a name \fIname\fP to authenticate the request. The \fIalg\fP
part specifies the algorithm (the default is hmac\-sha256) and \fIkey\fP specifies
the shared secret encoded in Base64.
.UNINDENT
.SS Commands
.INDENT 0.0
.TP
\fBserver\fP \fIname\fP [\fIport\fP]
Specifies a receiving server of the dynamic update message. The \fIname\fP parameter
can be either a host name or an IP address. If the \fIport\fP is not specified,
the default port is used. The default port value can be controlled using
the \fB\-p\fP program option.
.TP
\fBlocal\fP \fIaddress\fP [\fIport\fP]
Specifies outgoing \fIaddress\fP and \fIport\fP\&. If no local is specified, the
address and port are set by the system automatically. The default port number
is 0.
.TP
\fBzone\fP \fIname\fP
Specifies that all updates are done within a zone \fIname\fP\&. The zone name doesn\(aqt
have a default and must be set explicitly.
.TP
\fBorigin\fP \fIname\fP
Specifies fully qualified domain name suffix which is appended to non\-fqd
owners in update commands. The default is the terminal label (\fB\&.\fP).
.TP
\fBclass\fP \fIname\fP
Sets \fIname\fP as the default class for all updates. If not used, the default
class is IN.
.TP
\fBttl\fP \fIvalue\fP
Sets \fIvalue\fP as the default TTL (in seconds). If not used, the default value
is 3600.
.TP
\fBkey\fP [\fIalg\fP:]\fIname\fP \fIkey\fP
Specifies the TSIG \fIkey\fP named \fIname\fP to authenticate the request. An optional
\fIalg\fP algorithm can be specified. This command has the same effect as
the program option \fB\-y\fP\&.
.TP
[\fBprereq\fP] \fBnxdomain\fP \fIname\fP
Adds a prerequisite for a non\-existing record owned by \fIname\fP\&.
.TP
[\fBprereq\fP] \fByxdomain\fP \fIname\fP
Adds a prerequisite for an existing record owned by \fIname\fP\&.
.TP
[\fBprereq\fP] \fBnxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP
Adds a prerequisite for a non\-existing record of the \fItype\fP owned by \fIname\fP\&.
Internet \fIclass\fP is expected.
.TP
[\fBprereq\fP] \fByxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP [\fIdata\fP]
Adds a prerequisite for an existing record of the \fItype\fP owned by \fIname\fP
with optional \fIdata\fP\&. Internet \fIclass\fP is expected.
.TP
[\fBupdate\fP] \fBadd\fP \fIname\fP [\fIttl\fP] [\fIclass\fP] \fItype\fP \fIdata\fP
Adds a request to add a new resource record into the zone.
Please note that if the \fIname\fP is not fully qualified domain name, the
current origin name is appended to it.
.TP
[\fBupdate\fP] \fBdel\fP[\fBete\fP] \fIname\fP [\fIttl\fP] [\fIclass\fP] [\fItype\fP] [\fIdata\fP]
Adds a request to remove all (or matching \fIclass\fP, \fItype\fP or \fIdata\fP)
resource records from the zone. There is the same requirement for the \fIname\fP
parameter as in \fBupdate add\fP command. The \fIttl\fP item is ignored.
.TP
\fBshow\fP
Displays current content of the update message.
.TP
\fBsend\fP
Sends the current update message and cleans the list of updates.
.TP
\fBanswer\fP
Displays the last answer from the server.
.TP
\fBdebug\fP
Enable debugging. This command has the same meaning as the \fB\-d\fP program option.
.TP
\fBexit\fP
End the program.
.UNINDENT
.SH NOTES
.sp
Options \fB\-k\fP and \fB\-y\fP can not be used simultaneously.
.sp
Neither \fItsig\-keygen(8)\fP nor \fIdnssec\-keygen(1)\fP keyfile formats are supported.
Use \fBkeymgr(8)\fP to construct a string for \fB\-y\fP or the file passed to \fB\-k\fP\&.
.sp
Zone name/server guessing is not supported if the zone name/server is not specified.
.sp
An empty line doesn\(aqt send the update.
.SS Interactive mode
.sp
The utility provides interactive mode with basic line editing functionality,
command completion, and command history.
.sp
Interactive mode behavior can be customized in \fI~/.editrc\fP\&. Refer to
\fBeditrc(5)\fP for details.
.sp
Command history is saved in \fI~/.knsupdate_history\fP\&.
.SH EXIT VALUES
.sp
Exit status of 0 means successful operation. Any other exit status indicates
an error.
.SH EXAMPLES
.INDENT 0.0
.IP 1. 3
Send one update of the zone example.com to the server 192.168.1.1. The update
contains two new records:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ 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 \(dqhello\(dq
knsupdate> show
knsupdate> send
knsupdate> answer
knsupdate> exit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBkdig(1)\fP, \fBkhost(1)\fP, \fBkeymgr(8)\fP, \fBeditrc(5)\fP\&.
.SH AUTHOR
CZ.NIC Labs <https://www.knot-dns.cz>
.SH COPYRIGHT
Copyright 2010–2024, CZ.NIC, z.s.p.o.
.\" Generated by docutils manpage writer.
.