A few days ago I saw a commit for NSD, I had never heard of it before,
so naturally, I went to read the manpage, however it wasn't there. I
looked at the cvs tree, and saw that there was a manpage, just not
formatted for mandoc like all other manpages I've seen in OpenBSD, so I
read up on mdoc and rewrote the manpage.
As this is my first time converting anything from whatever that was
(somethingroff?) to mdoc, so I have a few questions about what I did:
- Did I handle the ip-addre...@port] argument properly? (I based it off
of nc.1's "[-x proxy_address[:port]]", but Xo and Xc are depreciated so
I avoided using them.)
- Is Em appropriate for signals?
- What should I do to the "zonesdir:" text?
- Is it appropriate to have the license at the top of the manpage like
that since there is a LICENSE file in the tree in the same directory as
the manpage.
- I removed the @version@ stuff found in the original manpage, is there
anything I should replace it with?
- I removed the options section as I cannot find an example of a new
manpage in OpenBSD where there are separate description and options
sections, the options seem to just be slapped on to the end of the
description, was this the right thing to do?
- Is there a way to specify that something is both a path and an
argument (for "chrootdir" in "chrootdir/dev/log" in the -t description).
- Why is -v for version and -V for verbosity instead of the other way
around?
- Was it correct to use "/(hy" instead of "-"? What about in the SEE
ALSO section?
- Is converting this stuff to mdoc format actually helpful and should I
clean the rest of the manpages for NSD or am I wasting my time writing
it and your time looking at it?
Any enlightenment would be greatly appreciated.
Here is my reformatted /src/usr.sbin/nsd/nsd.8 with a few minor
grammatical changes:
.\" Copyright (c) 2001-2006, NLnet Labs. All rights reserved.
.\"
.\" This software is open source.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" Redistributions of source code must retain the above copyright notice,
.\" this list of conditions and the following disclaimer.
.\"
.\" Redistributions in binary form must reproduce the above copyright
notice,
.\" this list of conditions and the following disclaimer in the
documentation
.\" and/or other materials provided with the distribution.
.\"
.\" Neither the name of the NLNET LABS nor the names of its contributors may
.\" be used to endorse or promote products derived from this software
without
.\" specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate$
.Dt NSD 8
.Os
.Sh NAME
.Nm nsd
.Nd Name Server Daemon
.Sh SYNOPSIS
.Nm
.Bk -words
.Op Fl 46dhv
.Op Fl a Ar ip\(hyaddress Ns Oo Ar @port Oc
.Op Fl c Ar configfile
.Op Fl f Ar database
.Op Fl I Ar nsid
.Op Fl i Ar identity
.Op Fl l Ar logfile
.Op Fl N Ar server\(hycount
.Op Fl n Ar noncurrent\(hytcp\(hycount
.Op Fl P Ar pidfile
.Op Fl p Ar port
.Op Fl s Ar seconds
.Op Fl t Ar chrootdir
.Op Fl u Ar username
.Op Fl V Ar level
.Ek
.Sh DESCRIPTION
.Nm
is a complete implementation of an authoritative DNS nameserver.
Upon startup,
.Nm
will read the database specified with the
.Fl f
argument, put itself into the background, and answer queries on port 53
.Po
or a different port as specified by
.Fl p
.Pc .
.Ar database
must be generated beforehand with
.Xr zonec 8 .
By default,
.Nm
will bind to all local interfaces available.
Use
.Fl a
to specify a single particular interface address to be bound.
If this option is given more than once,
.Nm
will bind its UDP and TCP sockets to all the specified ip\(hyaddresses
separately.
If IPv6 is enabled when
.Nm
is compiled, an IPv6 address can also be specified.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 4
Only listen to IPv4 connections.
.It Fl 6
Only listen to IPv6 connections.
.It Fl a Ar ip\(hyaddress Ns Oo Ar @port Oc
Listen to the specified
.Fl ip\(hyaddress .
The
.Fl ip\(hyaddress
must be specified in numeric format
.Pq using the standard IPv4 or IPv6 notation .
Optionally, a port number can be given.
This flag can be specified multiple times to listen to multiple IP
addresses.
If this flag is not specified,
.Nm
listens to the wildcard interface.
.It Fl b Ar configfile
Read specified
.Ar configfile
instead of the default
.Pa /etc/nsd/nsd.conf .
For format description see
.Xr nsd.conf 5 .
.It Fl d
Turn on debugging mode, do not fork, stay in the foreground.
.It Fl f Ar database
Use the specified
.Ar database
instead of the default of
.Pa /var/db/nsd/nsd.db .
If a
.Em zonesdir:
is specified in the config file this path can be relative to that directory.
.It Fl h
Print help information and exit.
.It Fl I Ar nsid
Add the specified
.Ar nsid
to the EDNS section of the answer when queried with an NSID EDNS enabled
packet.
.It Fl i Ar identity
Return the specified
.Ar identity
when asked for
.Em CH TXT ID.SERVER
.Po
This option is used to determine which server is answering the queries
when they
are multicast
.Pc .
The default is the name returned by
.Xr gethostname 3 .
.It Fl l Ar logfile
Log messages to the specified
.Ar logfile .
The default is to log to stderr and syslog.
If a
.Em zonesdir:
is specified in the config file this path can be relative to that directory.
.It Fl N Ar count
Start
.Ar count
.Nm
servers.
The default is 1.
Starting more than a single server is only useful on machines with
multiple CPUs
and/or network adapters.
.It Fl n Ar number
The maximum
.Ar number
of concurrent TCP connections that can be handled by each server.
The default is 10.
.It fl P Ar pidfile
Use the specified
.Ar pidfile
instead of the platform specific default, which is mostly
.Pa /var/run/nsd.pid .
If a
.Em zonesdir:
is specified in the config file, this path can be relative to that
directory.
.It p Ar port
Answer the queries on the specified
.Ar port
.Pq normally 53 .
.It Fl s Ar seconds
Produce statistics dump every
.Ar seconds
seconds.
This is equal to sending
.Em SIGUSR1
to the daemon periodically.
.It Fl t Ar chroot
Specifies a directory to chroot to upon startup.
This option requires you to ensure that the appropriate
.Xr syslogd 8
socket
.Po
e.g.
.Pa chrootdir/dev/log
.Pc
is available, otherwise
.Nm
won't produce any log output.
.It Fl u Ar username
Drop user and group privileges to those of
.Ar username
after binding the socket.
.Ar username
must be one of: username, id, or id.gid. For example: nsd, 80, or 80.80.
.It Fl V Ar level
This value specifies the verbosity level for
.Pq non\(hydebug
logging.
The default is 0.
.It Fl v
Print the version number of
.Nm
to standard error and exit.
.El
.Pp
All the options above can be specified in the configfile
.Po
.Fl c
argument
.Pc ,
except for the
.Fl v
and
.Fl h
options.
If options are specified on the commandline,
the options on the commandline take precedence over the options in the
configfile.
.Pp
Normally
.B NSD
should be started with the
.So
.Xr nsdc 8
start
.Sc
command invoked from a
.Pa /etc/rc.d/nsd.sh
script or similar at the operating system startup.
.Pp
.Nm
reacts to the following signals:
.Bl -tag
.It SIGTERM
Stop answering queries, shutdown, and exit normally.
.It SIGHUP
Reload the database.
.It SIGUSR1
Dump BIND8\(hystyle statistics into the log. Ignored otherwise.
.El
.Sh FILES
.Pa /var/db/nsd/nsd.db
\(em default
.Nm
database
.Pa /var/run/nsd.pid
\(em the process id of the name server.
.Pa /etc/nsd/nsd.conf
\(em default
.Nm
configuration file
.Sh DIAGNOSTICS
.Nm
will log all the problems via the standard
.Xr syslog 8
.I daemon
facility, unless the
.Fl d
option is specified.
.Sh SEE ALSO
.Xr nsdc 8 ,
.Xr nsd.conf 5 ,
.Xr nsd-checkconf 8 ,
.Xr nsd-notify 8 ,
.Xr nsd-patch 8 ,
.Xr nsd-xfer 8 ,
.Xr zonec 8
.Sh AUTHORS
.Nm
was written by NLnet Labs and RIPE NCC joint team.
Please see CREDITS file in the distribution for further details.
.Sh BUGS
.Nm
will answer the queries erroneously if
.Ar database
was not properly compiled with
.Xr zonec 8 .
Therefore problems with misconfigured master zone files or
.Xr zonec 8
bugs may not be visible until the queries are actually answered with
.Nm
