From c78a376138c479d01cd117cde31a5690881b2635 Mon Sep 17 00:00:00 2001 From: Daniel Salzman <daniel.salzman@nic.cz> Date: Mon, 1 Jul 2013 15:45:15 +0200 Subject: [PATCH] man: unify man pages for utils --- man/kdig.1.in | 107 ++++++++++++++++++++++----------------------- man/khost.1.in | 37 ++++++++-------- man/knsupdate.1.in | 88 +++++++++++-------------------------- 3 files changed, 98 insertions(+), 134 deletions(-) diff --git a/man/kdig.1.in b/man/kdig.1.in index f20eb9211b..75e273e3f3 100644 --- a/man/kdig.1.in +++ b/man/kdig.1.in @@ -1,39 +1,39 @@ .TH "kdig" "1" "April 2013" "CZ.NIC Labs" "Knot DNS, version @VERSION@" .SH NAME +.TP 5 .B kdig \- Advanced DNS lookup utility (libknot equivalent of ISC dig) .SH SYNOPSIS .B kdig [\fIcommon\-settings\fR] [\fIquery\fR [\fIsettings\fR]]... .TP 5 -.B kdig -\fB\-h\fR +.B kdig \-h .SH DESCRIPTION This utility sends one or more DNS \fIqueries\fR to a nameserver. Each query can have individual \fIsettings\fR, or it can be specified globally via \fIcommon\-settings\fR, which must precede \fIquery\fR specification. .TP 4 -\fIquery +.I query \fIname\fR | \fB\-q\fR \fIname\fR | \fB\-x\fR \fIaddress\fR .TP -\fIcommon\-settings, settings +.I common\-settings, settings [\fIclass\fR] [\fItype\fR] [\fB@\fIserver\fR]... [\fIoptions\fR] .TP -\fIname\fR +.I name Is a domain name that is to be looked up. .TP -\fIserver\fR +.I server Is a name or an address of the nameserver to send a query to. The address can be specified using [address]:port notation. If no server is specified the servers from \fB/etc/resolv.conf\fR are used. .TP -If no arguments are provided, \fBkdig\fR sends \fINS\fR query for root zone. +If no arguments are provided, \fBkdig\fR sends \fINS\fR query for the root zone. .SH OPTIONS .TP 4 -.BI \-4 +.B \-4 Use IPv4 protocol only. .TP -.BI \-6 +.B \-6 Use IPv6 protocol only. .TP .BI \-b \ address @@ -41,14 +41,13 @@ Set the source IP address of the query to \fIaddress\fR. The address can be specified using [address]:port notation. .TP .BI \-c \ class -Set query class (e.g. \fICH\fR, \fICLASS4\fR). -An explicit variant of \fIclass\fR specification. -The default class is \fIIN\fR. +Set query class (e.g. \fICH\fR, \fICLASS4\fR). An explicit variant of +\fIclass\fR specification. The default class is \fIIN\fR. .TP -.BI \-d +.B \-d Enable debug messages if any. .TP -\fB\-h\fR, \fB\-\-help\fR +.BR \-h ,\ \-\-help Print short help. .TP .BI \-k \ keyfile @@ -69,105 +68,105 @@ Set query name. An explicit variant of \fIname\fR specification. Set query type (e.g. \fINS\fR, \fIIXFR=12345\fR, \fITYPE65535\fR). An explicit variant of \fItype\fR specification. The default type is \fIA\fR. .TP -\fB\-v\fR, \fB\-\-version\fR +.BR \-v ,\ \-\-version Print program version. .TP .BI \-x \ address Send \fIPTR\fR query for IPv4 or IPv6 \fIaddress\fR. .TP -.BI \-y \ \fR[\fIalgo:\fR]\fIkeyname:key\fR +.B \-y \fR[\fIalgo:\fR]\fIkeyname:key\fR Use TSIG key with a name \fIkeyname\fR to authenticate the request. The \fIalgo\fR part specifies the algorithm (the default is hmac\-md5) and \fIkey\fR specifies the shared secret encoded in Base64. .TP -\fB+\fR[\fBno\fR]\fBmultiline\fR +.BR + [ no ] multiline Wrap long records to more lines. .TP -\fB+\fR[\fBno\fR]\fBshort\fR +.BR + [ no ] short Show record data only. .TP -\fB+\fR[\fBno\fR]\fBaaflag\fR +.BR + [ no ] aaflag Set AA flag. .TP -\fB+\fR[\fBno\fR]\fBtcflag\fR +.BR + [ no ] tcflag Set TC flag. .TP -\fB+\fR[\fBno\fR]\fBrdflag\fR +.BR + [ no ] rdflag Set RD flag. .TP -\fB+\fR[\fBno\fR]\fBrecurse\fR -Same as +\fR[\fBno\fR]\fBrdflag\fR +.BR + [ no ] recurse +.RB "Same as " + [ no ] rdflag .TP -\fB+\fR[\fBno\fR]\fBrec\fR -Same as +\fR[\fBno\fR]\fBrdflag\fR +.BR + [ no ] rec +.RB "Same as " + [ no ] rdflag .TP -\fB+\fR[\fBno\fR]\fBraflag\fR +.BR + [ no ] raflag Set RA flag. .TP -\fB+\fR[\fBno\fR]\fBzflag\fR +.BR + [ no ] zflag Set zero flag bit. .TP -\fB+\fR[\fBno\fR]\fBadflag\fR +.BR + [ no ] adflag Set AD flag. .TP -\fB+\fR[\fBno\fR]\fBcdflag\fR +.BR + [ no ] cdflag Set CD flag. .TP -\fB+\fR[\fBno\fR]\fBdnssec\fR +.BR + [ no ] dnssec Set DO flag. .TP -\fB+\fR[\fBno\fR]\fBall\fR +.BR + [ no ] all Show all packet sections. .TP -\fB+\fR[\fBno\fR]\fBqr\fR +.BR + [ no ] qr Show query packet. .TP -\fB+\fR[\fBno\fR]\fBheader\fR +.BR + [ no ] header Show packet header. .TP -\fB+\fR[\fBno\fR]\fBedns\fR +.BR + [ no ] edns Show EDNS pseudosectio. .TP -\fB+\fR[\fBno\fR]\fBquestion\fR +.BR + [ no ] question Show question section. .TP -\fB+\fR[\fBno\fR]\fBanswer\fR +.BR + [ no ] answer Show answer section. .TP -\fB+\fR[\fBno\fR]\fBauthority\fR +.BR + [ no ] authority Show authority section. .TP -\fB+\fR[\fBno\fR]\fBadditional\fR +.BR + [ no ] additional Show additional section. .TP -\fB+\fR[\fBno\fR]\fBstats\fR +.BR + [ no ] stats Show trailing packet statistics. .TP -\fB+\fR[\fBno\fR]\fBcl\fR +.BR + [ no ] cl Show DNS class. .TP -\fB+\fR[\fBno\fR]\fBttl\fR +.BR + [ no ] ttl Show TTL value. .TP -\fB+time=\fIT\fR +.BI +time= T Set wait for reply interval in seconds (default is 5 seconds). .TP -\fB+retries=\fIN\fR +.BI +retries= N Set number of retries (default is 2). This doesn't apply to AXFR or IXFR. .TP -\fB+bufsize=\fIB\fR +.BI +bufsize= B Set EDNS buffer size in bytes (default is 512 bytes). .TP -\fB+\fR[\fBno\fR]\fBtcp\fR +.BR + [ no ] tcp Use TCP protocol. .TP -\fB+\fR[\fBno\fR]\fBfail\fR +.BR + [ no ] fail Stop if SERVFAIL. .TP -\fB+\fR[\fBno\fR]\fBignore\fR +.BR + [ no ] ignore Don't use TCP automatically if truncated reply is received. .TP -\fB+\fR[\fBno\fR]\fBnsid\fR +.BR + [ no ] nsid Request nameserver identifier (NSID). .SH NOTE Options \fB\-k\fR and \fB\-y\fR cannot be used mutually. @@ -179,17 +178,17 @@ Options \fB\-k\fR and \fB\-y\fR cannot be used mutually. .B Example 2. Perform AXFR for zone example.com from the server 192.0.2.1: .TP # kdig example.com \-t AXFR @192.0.2.1 -.TP 12 +.TP .B Example 3. Send one A query for example.com from 192.0.2.1 and one reverse \ lookup for address 2001:DB8::1 from 192.0.2.2. Both using TCP protocol: .TP # kdig +tcp example.com \-t A @192.0.2.1 \-x 2001:DB8::1 @192.0.2.2 .SH FILES -.BI /etc/resolv.conf +.I /etc/resolv.conf .SH AUTHOR -Daniel Salzman (\fBhttp://knot\-dns.cz\fR) +Daniel Salzman (\fBwww.knot\-dns.cz\fR) .TP -Please send any bugs or comments to \fBknot\-dns@labs.nic.cz\fR +Please send any bug reports or comments to \fBknot\-dns@labs.nic.cz\fR .SH SEE ALSO -.BI khost\fR(1), -.BI knsupdate\fR(1). +.BR khost (1), +.BR knsupdate (1). diff --git a/man/khost.1.in b/man/khost.1.in index a231fbae48..ca4a5756a5 100644 --- a/man/khost.1.in +++ b/man/khost.1.in @@ -1,5 +1,6 @@ .TH "khost" "1" "April 2013" "CZ.NIC Labs" "Knot DNS, version @VERSION@" .SH NAME +.TP 6 .B khost \- Simple DNS lookup utility (libknot equivalent of ISC host) .SH SYNOPSIS @@ -9,11 +10,11 @@ This utility sends a DNS query for the \fIname\fR to the \fIserver\fR and prints a reply in more user\-readable form. For more advanced DNS queries use \fBkdig\fR instead. .TP 4 -\fI name\fR +.I name Is a domain name that is to be looked up. If the \fIname\fR is IPv4 or IPv6 address the \fIPTR\fR query type is used. .TP -\fI server\fR +.I server Is a name or an address of the nameserver to send a query to. The address can be specified using [address]:port notation. If no server is specified the servers from \fB/etc/resolv.conf\fR are used. @@ -21,37 +22,37 @@ the servers from \fB/etc/resolv.conf\fR are used. If no arguments are provided, \fBkhost\fR prints short help. .SH OPTIONS .TP 4 -.BI \-4 +.B \-4 Use IPv4 protocol only. .TP -.BI \-6 +.B \-6 Use IPv6 protocol only. .TP -.BI \-a +.B \-a Send ANY query with verbose mode. .TP -.BI \-d +.B \-d Enable debug messages if any. .TP -\fB\-h\fR, \fB\-\-help\fR +.BR \-h ,\ \-\-help Print help. .TP -.BI \-r +.B \-r Disable recursion. .TP -.BI \-s +.B \-s Stop quering next nameserver if SERVFAIL response is received. .TP -.BI \-T +.B \-T Use TCP protocol. .TP -.BI \-v +.B \-v Enable verbose output. .TP -\fB\-V\fR, \fB\-\-version\fR +.BR \-V ,\ \-\-version Print program version. .TP -.BI \-w +.B \-w Wait forever for the reply. .TP .BI \-c \ class @@ -79,11 +80,11 @@ The time to wait for a reply in seconds. The default is \fI2\fR seconds. .TP # khost \-t AXFR \-v example.com .SH FILES -.BI /etc/resolv.conf +.I /etc/resolv.conf .SH AUTHOR -Daniel Salzman (\fBhttp://knot\-dns.cz\fR) +Daniel Salzman (\fBwww.knot\-dns.cz\fR) .TP -Please send any bugs or comments to \fBknot\-dns@labs.nic.cz\fR +Please send any bug reports or comments to \fBknot\-dns@labs.nic.cz\fR .SH SEE ALSO -.BI kdig\fR(1), -.BI knsupdate\fR(1). +.BR kdig (1), +.BR knsupdate (1). diff --git a/man/knsupdate.1.in b/man/knsupdate.1.in index 884280eaf8..3f30c53f55 100644 --- a/man/knsupdate.1.in +++ b/man/knsupdate.1.in @@ -6,32 +6,28 @@ .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 +.B \-d Enable debugging messages. .TP -.BI \-v +.B \-v Use TCP protocol instead of the default UDP. .TP .BI \-p \ port -Set the port to use when connecting to server and the port was not explicitly -specified in the update. The default is 53. +Set the port to use for connections to a server (if not explicitly +specified in the update). The default is \fI53\fR. .TP .BI \-t \ timeout -The timeout of the update request in seconds. The default is 12. If set to +The total timeout (all UDP update tries) of the update request in seconds. The default is \fI12\fR. If set to zero, the timeout is infinite. .TP .BI \-r \ retries -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). +The number of retries for UDP requests. The default is \fI3\fR. .TP .BI \-k \ keyfile Use TSIG or SIG\-0 key stored in file to authenticate the request. The tool @@ -39,109 +35,77 @@ 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 Use TSIG key 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 -\fB\-\-help\fR +.BR \-h ,\ \-\-help Print help. - .TP -\fB\-\-version\fR +.BR \-V ,\ \-\-version Print program version. - -.TP +.SH NOTE 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. - +.TP List of commands format and their description: - .TP -\fBserver\fR \fIname\fR [\fIport\fR] - +.BI server \ name \ [\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 - +.BI zone \ name Specifies that all updates are done within a zone named \fIname\fR. If not used, the default zone is the root zone. - .TP -\fBorigin\fR \fIname\fR - +.BI origin \ name Specifies fully qualified domain name suffix which is appended to non\-fqd owners in update commands. The default origin is the root zone. - .TP -\fBclass\fR \fIname\fR - +.BI class \ name Sets \fIname\fR as a default class for all updates. If not used, the default class is IN. - .TP -\fBttl\fR \fIvalue\fR - +.BI ttl \ value Sets \fIvalue\fR as a default TTL (time to live) in seconds. If not used, the default value is zero. - .TP -\fBkey\fB \fIname\fR \fIkey\fR - +.BI key \ name \ \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 if the \fIname\fR is not fully qualified domain name, current \fIorigin\fR name is 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 all (or matching \fIclass\fR, \fItype\fR, \fIdata\fR) resource records from the zone. There is the same requirement for the \fIname\fR parameter as in the \fBupdate add\fR command. The \fIttl\fR item is ignored. - .TP -\fBshow\fR - +.B show Displays current content of the update message. - .TP -\fBsend\fR - +.B send Sends the current update message and cleans the list of updates. - .TP -\fBanswer\fR - +.B answer Displays the last answer from the server. - .TP -\fBdebug\fR - +.B debug 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 AUTHOR +Marek VavruÅ¡a, Daniel Salzman, Jan VÄelák (\fBwww.knot\-dns.cz\fR) +.TP +Please send any bug reports or comments to \fBknot\-dns@labs.nic.cz\fR .SH SEE ALSO -.BI khost\fR(1), -.BI kdig\fR(1). +.BR kdig (1), +.BR khost (1). -- GitLab