diff options
Diffstat (limited to 'usr.sbin/nsd/nsd.conf.5')
| -rw-r--r-- | usr.sbin/nsd/nsd.conf.5 | 514 |
1 files changed, 514 insertions, 0 deletions
diff --git a/usr.sbin/nsd/nsd.conf.5 b/usr.sbin/nsd/nsd.conf.5 new file mode 100644 index 00000000000..7b6a871102c --- /dev/null +++ b/usr.sbin/nsd/nsd.conf.5 @@ -0,0 +1,514 @@ +.TH "nsd.conf" "5" "Jan 6, 2010" "NLnet Labs" "nsd 3.2.4" +.\" Copyright (c) 2001\-2008, NLnet Labs. All rights reserved. +.\" See LICENSE for the license. +.SH "NAME" +.LP +.B nsd.conf +\- NSD configuration file +.SH "SYNOPSIS" +.LP +.B nsd.conf +.SH "DESCRIPTION" +.B Nsd.conf +is used to configure nsd(8). The file format has attributes and +values. Some attributes have attributes inside them. The notation +is: attribute: value. +.PP +Comments start with # and last to the end of line. Empty lines are +ignored as is whitespace at the beginning of a line. +.PP +.B Nsd.conf +specifies options for the nsd server, zone files, primaries and +secondaries. +.SH "EXAMPLE" +.LP +An example of a short nsd.conf file is below. +.LP +# Example.com nsd.conf file +.RS 0 +# This is a comment. +.RE +.TP +server: +.RS 5 +database: "/var/db/nsd/nsd.db" +.RE +.RS 5 +username: nsd +.RE +.RS 5 +logfile: "/var/log/nsd.log" +.RE +.RS 5 +pidfile: "/var/run/nsd.pid" +.RE +.RS 5 +difffile: "/var/db/nsd/ixfr.db" +.RE +.RS 5 +xfrdfile: "/var/db/nsd/xfrd.state" +.RE +.TP +zone: +.RS 5 +name: example.com +.RE +.RS 5 +# note that quotes are optional on the value +.RE +.RS 5 +zonefile: /etc/nsd/example.com.zone +.RE +.SH "FILE FORMAT" +There must be whitespace between keywords. Attribute keywords end +with a colon ':'. An attribute is followed by its containing +attributes, or a value. +.P +At the top level only +.B server: +or +.B zone: +or +.B key: +are allowed. These are followed by their attributes or the start of +a new +.B server: +or +.B zone: +or +.B key: +clause. The +.B zone: +attribute is followed by zone options. The +.B server: +attribute is followed by global options for the +.B NSD +server. A +.B key: +attribute is used to define keys for authentication. +.P +Files can be included using the +.B include: +directive. It can appear anywhere, and takes a single filename as +an argument. Processing continues as if the text from the included +file was copied into the config file at that point. +.S "Server Options" +.LP +The global options (if not overridden from the NSD commandline) are +taken from the +.B server: +clause. There may only be one +.B server: +clause. +.TP +.B ip\-address:\fR <ip4 or ip6> +NSD will bind to the listed ip\-address. Can be give multiple times +to bind multiple ip\-addresses. If none are given NSD listens to all +IP addresses. Same as commandline option +.BR \-a. +.TP +.B debug\-mode:\fR <yes or no> +Turns on debugging mode for nsd, does not fork a daemon process. +Default is no. Same as commandline option +.BR \-d. +.TP +.B ip4\-only:\fR <yes or no> +If yes, NSD only listens to IPv4 connections. Same as commandline +option +.BR \-4. +.TP +.B ip6\-only:\fR <yes or no> +If yes, NSD only listens to IPv6 connections. Same as commandline +option +.BR \-6. +.TP +.B database:\fR <filename> +By default +.I /var/db/nsd/nsd.db +is used. The specified file is used to store the compiled +zone information. Same as commandline option +.BR \-f. +.TP +.B identity:\fR <string> +Returns the specified identity when asked for CH TXT ID.SERVER. +Default is the name as returned by gethostname(3). Same as +commandline option +.BR \-i . +.TP +.B logfile:\fR <filename> +Log messages to the logfile. The default is to log to stderr and +syslog. Same as commandline option +.BR \-l . +.TP +.B server\-count:\fR <number> +.It \fBserver\-count:\fR <number> +Start this many NSD servers. Default is 1. Same as commandline +option +.BR \-N . +.TP +.B tcp\-count:\fR <number> +The maximum number of concurrent, active TCP connections by each server. +Default is 10. This option should have a value below 1000. +Same as commandline option +.BR \-n . +.TP +.B tcp\-query\-count:\fR <number> +The maximum number of queries served on a single TCP connection. +Default is 0, meaning there is no maximum. +.TP +.B tcp\-timeout:\fR <number> +Overrides the default TCP timeout. This also affects zone transfers over TCP. +.TP +.B ipv4\-edns\-size:\fR <number> +Preferred EDNS buffer size for IPv4. +.TP +.B ipv6\-edns\-size:\fR <number> +Preferred EDNS buffer size for IPv6. +.TP +.B pidfile:\fR <filename> +Use the pid file instead of the platform specific default, usually +.IR /var/run/nsd.pid. +Same as commandline option +.BR \-P . +.TP +.B port:\fR <number> +Answer queries on the specified port. Default is 53. Same as +commandline option +.BR \-p . +.TP +.B statistics:\fR <number> +If not present no statistics are dumped. Statistics are produced +every number seconds. Same as commandline option +.BR \-s . +.TP +.B chroot:\fR <directory> +NSD will chroot on startup to the specified directory. Same as +commandline option +.BR \-t . +.TP +.B username:\fR <username> +After binding the socket, drop user privileges and assume the +username. Can be username, id or id.gid. Same as commandline option +.BR \-u . +.TP +.B zonesdir:\fR <directory> +Change the working directory to the specified directory before +accessing zone files. Same as commandline option +.B \-d +for zonec(8). Also nsd(8) will access files (pid file, database +file, log file) relative to this directory. Set the value to "" +(the empty string) to disable the change of working directory. +.TP +.B difffile:\fR <filename> +When NSD receives IXFR updates it will store them in this file. +This file contains the differences between the database file and the +latest zone version. Default is +.IR /var/db/nsd/ixfr.db . +.TP +.B xfrdfile:\fR <filename> +The soa timeout and zone transfer daemon in NSD will save its state +to this file. State is read back after a restart. The state file can +be deleted without too much harm, but timestamps of zones will be +gone. For more details see the section on zone expiry behavior of +NSD. Default is +.IR /var/db/nsd/xfrd.state . +.TP +.B xrfd\-reload\-timeout:\fR <number> +If this value is \-1, xfrd will not trigger a reload after a zone +transfer. If positive xfrd will trigger a reload after a zone +transfer, then it will wait for the number of seconds before it will +trigger a new reload. Setting this value throttles the reloads to +once per the number of seconds. The default is 10 seconds. +.TP +.B verbosity:\fR <level> +This value specifies the verbosity level for (non\-debug) logging. +Default is 0. 1 gives more information about incoming notifies and +zone transfers. 2 lists soft warnings that are encountered. +.TP +.B hide\-version:\fR <yes or no> +Prevent NSD from replying with the version string on CHAOS class +queries. +.SS "Zone Options" +.LP +For every zone the options need to be specified in one +.B zone: +clause. The access control list elements can be given multiple +times to add multiple servers. +.TP +.B name:\fR <string> +The name of the zone. This is the domain name of the apex of the +zone. May end with a '.' (in FQDN notation). For example +"example.com", "sub.example.net.". This attribute must be present in +each zone. +.TP +.B zonefile:\fR <filename> +The file containing the zone information. This file is used by +zonec(8). This attribute must be present in each zone. +.TP +.B allow\-notify:\fR <ip\-spec> <key\-name | NOKEY | BLOCKED> +Access control list. The listed (primary) address is allowed to +send notifies to this (secondary) server. Notifies from unlisted or +specifically BLOCKED addresses are discarded. If NOKEY is given no +TSIG signature is required. +.P +.RS +The ip\-spec is either a plain IP address (IPv4 or IPv6), or can be +a subnet of the form 1.2.3.4/24, or masked like +1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4\-1.2.3.25. +A port number can be added using a suffix of @number, for example +1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. +Note the ip\-spec ranges do not use spaces around the /, &, @ and \- +symbols. +.RE +.TP +.B request\-xfr:\fR [AXFR|UDP] <ip\-address> <key\-name | NOKEY> +Access control list. The listed address (the master) is queried for +AXFR/IXFR on update. The specified key is used during AXFR/IXFR. +.P +.RS +If the AXFR option is given, the server will not be contacted with +IXFR queries but only AXFR requests will be made to the server. This +allows an NSD secondary to have a master server that runs NSD. If +the AXFR option is left out then both IXFR and AXFR requests are +made to the master server. +.P +If the UDP option is given, the secondary will use UDP to transmit the IXFR +requests. You should deploy TSIG when allowing UDP transport, to authenticate +notifies and zone transfers. Otherwise, NSD is more vulnerable for +Kaminsky-style attacks. If the UDP option is left out then IXFR will be +transmitted using TCP. +.RE +.TP +.B allow\-axfr\-fallback:\fR <yes or no> +This option should be accompanied by request-xfr. It (dis)allows NSD (as secondary) +to fallback to AXFR if the primary name server does not support IXFR. +.TP +.B notify:\fR <ip\-address> <key\-name | NOKEY> +Access control list. The listed address (a secondary) is notified +of updates to this zone. The specified key is used to sign the +notify. Only on secondary configurations will NSD be able to detect +zone updates (as it gets notified itself, or refreshes after a +time). +.TP +.B notify\-retry:\fR <number> +This option should be accompanied by notify. It sets the number of retries +when sending notifies. +.TP +.B provide\-xfr:\fR <ip\-spec> <key\-name | NOKEY | BLOCKED> +Access control list. The listed address (a secondary) is allowed to +request AXFR from this server. Zone data will be provided to the +address. The specified key is used during AXFR. For unlisted or +BLOCKED addresses no data is provided, requests are discarded. +.P +.RS +The ip\-spec is either a plain IP address (IPv4 or IPv6), or can be +a subnet of the form 1.2.3.4/24, or masked like +1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4\-1.2.3.25. +A port number can be added using a suffix of @number, for example +1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the ip\-spec +ranges do not use spaces around the /, &, @ and \- symbols. +.RE +.TP +.B outgoing\-interface:\fR <ip\-address> +Access control list. The listed address is used to request AXFR|IXFR (in case of +a secondary) or used to send notifies (in case of a primary). +.P +.RS +The ip\-address is either a plain IP address (IPv4 or IPv6), or can be +a subnet of the form 1.2.3.4/24, or masked like +1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4\-1.2.3.25. +.RE +.SS "Key Declarations" +The +.B key: +clause establishes a key for use in access control lists. It has +the following attributes. +.TP +.B name:\fR <string> +The key name. Used to refer to this key in the access control list. +.TP +.B algorithm:\fR <string> +Authentication algorithm for this key. +.TP +.B secret:\fR <base64 blob> +The base64 encoded shared secret. It is possible to put the +.B secret: +declaration (and base64 blob) into a different file, and then to +.B include: +that file. In this way the key secret and the rest of the configuration +file, which may have different security policies, can be split apart. +.SH "NSD CONFIGURATION FOR BIND9 HACKERS" +BIND9 is a name server implementation with its own configuration +file format, named.conf(5). BIND9 types zones as 'Master' or +'Slave'. +.SS "Slave zones" +For a slave zone, the master servers are listed. The master servers are +queried for zone data, and are listened to for update notifications. +In NSD these two properties need to be configured seperately, by listing +the master address in allow\-notify and request\-xfr statements. +.P +In BIND9 you only need to provide allow\-notify elements for +any extra sources of notifications (i.e. the operators), NSD needs to have +allow\-notify for both masters and operators. BIND9 allows +additional transfer sources, in NSD you list those as request\-xfr. +.P +Here is an example of a slave zone in BIND9 syntax. +.P +# Config file for example.org +options { +.RS 5 +dnssec\-enable yes; +.RE +.RS 0 +}; +.RE +.LP +key tsig.example.org. { +.RS 5 +algorithm hmac\-md5; +.RE +.RS 5 +secret "aaaaaabbbbbbccccccdddddd"; +.RE +}; +.LP +server 162.0.4.49 { +.RS 5 +keys { tsig.example.org. ; }; +.RE +}; +.LP +zone "example.org" { +.RS 5 +type slave; +.RE +.RS 5 +file "secondary/example.org.signed"; +.RE +.RS 5 +masters { 162.0.4.49; }; +.RE +}; +.P +For NSD, DNSSEC is enabled automatically for zones that are signed. The +dnssec\-enable statement in the options clause is not needed. In NSD +keys are associated with an IP address in the access control list +statement, therefore the server{} statement is not needed. Below is +the same example in an NSD config file. +.LP +# Config file for example.org +.RS 0 +key: +.RE +.RS 5 +name: tsig.example.org. +.RE +.RS 5 +algorithm: hmac\-md5 +.RE +.RS 5 +secret: "aaaaaabbbbbbccccccdddddd" +.RE +.LP +zone: +.RS 5 +name: "example.org" +.RE +.RS 5 +zonefile: "secondary/example.org.signed" +.RE +.RS 5 +# the master is allowed to notify and will provide zone data. +.RE +.RS 5 +allow\-notify: 162.0.4.49 NOKEY +.RE +.RS 5 +request\-xfr: 162.0.4.49 tsig.example.org. +.RE +.P +Notice that the master is listed twice, once to allow it to send notifies +to this slave server and once to tell the slave server where to look for +updates zone data. More allow\-notify and request\-xfr lines can be +added to specify more masters. +.P +It is possible to specify extra allow\-notify lines for addresses +that are also allowed to send notifications to this slave server. +.SS "Master zones" +For a master zone in BIND9, the slave servers are listed. These slave +servers are sent notifications of updated and are allowed to request +transfer of the zone data. In NSD these two properties need to be +configured seperately. +.P +Here is an example of a master zone in BIND9 syntax. +.LP +zone "example.nl" { +.RS 5 +type master; +.RE +.RS 5 +file "example.nl"; +.RE +}; +.LP +In NSD syntax this becomes: +.LP +zone: +.RS 5 +name: "example.nl" +.RE +.RS 5 +zonefile: "example.nl" +.RE +.RS 5 +# allow anybody to request xfr. +.RE +.RS 5 +provide\-xfr: 0.0.0.0/0 NOKEY +.RE +.RS 5 +provide\-xfr: ::0/0 NOKEY +.RE +.P +.RS 5 +# to list a slave server you would in general give +.RE +.RS 5 +# provide\-xfr: 1.2.3.4 tsig\-key.name. +.RE +.RS 5 +# notify: 1.2.3.4 NOKEY +.RE +.SS "Other" +NSD is an authoritative only DNS server. This means that it is +meant as a primary or secondary server for zones, providing DNS +data to DNS resolvers and caches. BIND9 can function as an +authoritative DNS server, the configuration options for that are +compared with those for NSD in this section. However, BIND9 can +also function as a resolver or cache. The configuration options that +BIND9 has for the resolver or caching thus have no equivalents for NSD. +.SH "FILES" +.TP +/var/db/nsd/nsd.db +default +.B NSD +database +.TP +/etc/nsd/nsd.conf +default +.B NSD +configuration file +.SH "SEE ALSO" +.LP +nsd(8), nsdc(8), nsd\-checkconf(8), nsd-notify(8), +nsd-patch(8), nsd-xfer(8), zonec(8) +.SH "AUTHORS" +.LP +.B NSD +was written by NLnet Labs and RIPE NCC joint team. Please see +CREDITS file in the distribution for further details. +.SH "BUGS" +.LP +.B nsd.conf +is parsed by a primitive parser, error messages may not be to the +point. |