logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

nsd.conf.5 (36612B)


  1. .TH "nsd.conf" "5" "Apr 6, 2021" "NLnet Labs" "nsd 4.3.6"
  2. .\" Copyright (c) 2001\-2008, NLnet Labs. All rights reserved.
  3. .\" See LICENSE for the license.
  4. .SH "NAME"
  5. .B nsd.conf
  6. \- NSD configuration file
  7. .SH "SYNOPSIS"
  8. .B nsd.conf
  9. .SH "DESCRIPTION"
  10. .B Nsd.conf
  11. is used to configure nsd(8). The file format has attributes and
  12. values. Some attributes have attributes inside them. The notation
  13. is: attribute: value.
  14. .PP
  15. Comments start with # and last to the end of line. Empty lines are
  16. ignored as is whitespace at the beginning of a line. Quotes can be used,
  17. for names with spaces, eg. "file name.zone".
  18. .PP
  19. .B Nsd.conf
  20. specifies options for the nsd server, zone files, primaries and
  21. secondaries.
  22. .SH "EXAMPLE"
  23. An example of a short nsd.conf file is below.
  24. .LP
  25. # Example.com nsd.conf file
  26. .RS 0
  27. # This is a comment.
  28. .RE
  29. .TP
  30. server:
  31. .RS 5
  32. server-count: 1 # use this number of cpu cores
  33. .RE
  34. .RS 5
  35. database: "" # or use "/var/db/nsd/nsd.db"
  36. .RE
  37. .RS 5
  38. zonelistfile: "/var/db/nsd/zone.list"
  39. .RE
  40. .RS 5
  41. username: nsd
  42. .RE
  43. .RS 5
  44. logfile: "/var/log/nsd.log"
  45. .RE
  46. .RS 5
  47. pidfile: "/run/nsd.pid"
  48. .RE
  49. .RS 5
  50. xfrdfile: "/var/db/nsd/xfrd.state"
  51. .RE
  52. .TP
  53. zone:
  54. .RS 5
  55. name: example.com
  56. .RE
  57. .RS 5
  58. zonefile: /etc/nsd/example.com.zone
  59. .RE
  60. .TP
  61. zone:
  62. .RS 5
  63. # this server is master, 192.0.2.1 is the secondary.
  64. .RE
  65. .RS 5
  66. name: masterzone.com
  67. .RE
  68. .RS 5
  69. zonefile: /etc/nsd/masterzone.com.zone
  70. .RE
  71. .RS 5
  72. notify: 192.0.2.1 NOKEY
  73. .RE
  74. .RS 5
  75. provide-xfr: 192.0.2.1 NOKEY
  76. .RE
  77. .TP
  78. zone:
  79. .RS 5
  80. # this server is secondary, 192.0.2.2 is master.
  81. .RE
  82. .RS 5
  83. name: secondzone.com
  84. .RE
  85. .RS 5
  86. zonefile: /etc/nsd/secondzone.com.zone
  87. .RE
  88. .RS 5
  89. allow-notify: 192.0.2.2 NOKEY
  90. .RE
  91. .RS 5
  92. request-xfr: 192.0.2.2 NOKEY
  93. .RE
  94. .LP
  95. Then, use kill \-HUP to reload changes from master zone files.
  96. And use kill \-TERM to stop the server.
  97. .SH "FILE FORMAT"
  98. There must be whitespace between keywords. Attribute keywords end
  99. with a colon ':'. An attribute is followed by its containing
  100. attributes, or a value.
  101. .P
  102. At the top level only
  103. .BR server: ,
  104. .BR key: ,
  105. .BR pattern: ,
  106. .BR zone: ,
  107. and
  108. .B remote-control:
  109. are allowed. These are followed by their attributes or a new top-level keyword. The
  110. .B zone:
  111. attribute is followed by zone options. The
  112. .B server:
  113. attribute is followed by global options for the
  114. .B NSD
  115. server. A
  116. .B key:
  117. attribute is used to define keys for authentication. The
  118. .B pattern:
  119. attribute is followed by the zone options for zones that use the pattern.
  120. .P
  121. Files can be included using the
  122. .B include:
  123. directive. It can appear anywhere, and takes a single filename as an
  124. argument. Processing continues as if the text from the included file
  125. was copied into the config file at that point. If a chroot is used
  126. an absolute filename is needed (with the chroot prepended), so that
  127. the include can be parsed before and after application of the chroot (and
  128. the knowledge of what that chroot is). You can use '*' to include a
  129. wildcard match of files, eg. "foo/nsd.d/*.conf". Also '?', '{}', '[]',
  130. and '~' work, see \fBglob\fR(7). If no files match the pattern, this
  131. is not an error.
  132. .SS "Server Options"
  133. .LP
  134. The global options (if not overridden from the NSD commandline) are
  135. taken from the
  136. .B server:
  137. clause. There may only be one
  138. .B server:
  139. clause.
  140. .TP
  141. .B ip\-address:\fR <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
  142. NSD will bind to the listed ip\-address. Can be given multiple times
  143. to bind multiple ip\-addresses. Optionally, a port number can be given.
  144. If none are given NSD listens to the wildcard interface. Same as commandline option
  145. .BR \-a.
  146. .IP
  147. To limit which NSD server(s) listen on the given interface, specify one or
  148. more servers separated by whitespace after <ip>[@port]. Ranges can be used as
  149. a shorthand to specify multiple consecutive servers. By default every server
  150. will listen.
  151. .IP
  152. If an interface name is used instead of ip4 or ip6, the list of IP addresses
  153. associated with that interface is picked up and used at server start.
  154. .IP
  155. For servers with multiple IP addresses that can be used to send traffic
  156. to the internet, list them one by one, or the source address of replies
  157. could be wrong. This is because if the udp socket associates a source
  158. address of 0.0.0.0 then the kernel picks an ip-address with which to
  159. send to the internet, and it picks the wrong one. Typically needed for
  160. anycast instances. Use ip-transparent to be able to list addresses that
  161. turn on later (typical for certain load-balancing).
  162. .TP
  163. .B interface:\fR <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
  164. Same as ip\-address (for ease of compatibility with unbound.conf).
  165. .TP
  166. .B ip\-transparent:\fR <yes or no>
  167. Allows NSD to bind to non local addresses. This is useful to have NSD
  168. listen to IP addresses that are not (yet) added to the network interface, so
  169. that it can answer immediately when the address is added. Default is no.
  170. .TP
  171. .B ip\-freebind:\fR <yes or no>
  172. Set the IP_FREEBIND option to bind to nonlocal addresses and interfaces
  173. that are down. Similar to ip\-transparent. Default is no.
  174. .TP
  175. .B reuseport:\fR <yes or no>
  176. Use the SO_REUSEPORT socket option, and create file descriptors for every
  177. server in the server\-count. This improves performance of the network
  178. stack. Only really useful if you also configure a server\-count higher
  179. than 1 (such as, equal to the number of cpus). The default is no.
  180. It works on Linux, but does not work on FreeBSD, and likely does not
  181. work on other systems.
  182. .TP
  183. .B send\-buffer\-size:\fR <number>
  184. Set the send buffer size for query-servicing sockets. Set to 0 to use the default settings.
  185. .TP
  186. .B receive\-buffer\-size:\fR <number>
  187. Set the receive buffer size for query-servicing sockets. Set to 0 to use the default settings.
  188. .TP
  189. .B debug\-mode:\fR <yes or no>
  190. Turns on debugging mode for nsd, does not fork a daemon process.
  191. Default is no. Same as commandline option
  192. .BR \-d.
  193. If set to yes it does not fork and stays in the foreground, which can
  194. be helpful for commandline debugging, but is also used by certain
  195. server supervisor processes to ascertain that the server is running.
  196. .TP
  197. .B do\-ip4:\fR <yes or no>
  198. If yes, NSD listens to IPv4 connections. Default yes.
  199. .TP
  200. .B do\-ip6:\fR <yes or no>
  201. If yes, NSD listens to IPv6 connections. Default yes.
  202. .TP
  203. .B database:\fR <filename>
  204. By default
  205. .I /var/db/nsd/nsd.db
  206. is used. The specified file is used to store the compiled
  207. zone information. Same as commandline option
  208. .BR \-f.
  209. If set to "" then no database is used. This uses less memory but
  210. zone updates are not (immediately) spooled to disk.
  211. .TP
  212. .B zonelistfile:\fR <filename>
  213. By default
  214. .I /var/db/nsd/zone.list
  215. is used. The specified file is used to store the dynamically added
  216. list of zones. The list is written to by NSD to add and delete zones.
  217. It is a text file with a zone\-name and pattern\-name on each line.
  218. This file is used for the nsd\-control addzone and delzone commands.
  219. .TP
  220. .B identity:\fR <string>
  221. Returns the specified identity when asked for CH TXT ID.SERVER.
  222. Default is the name as returned by gethostname(3). Same as
  223. commandline option
  224. .BR \-i .
  225. See hide\-identity to set the server to not respond to such queries.
  226. .TP
  227. .B version:\fR <string>
  228. Returns the specified version string when asked for CH TXT version.server,
  229. and version.bind queries. Default is the compiled package version.
  230. See hide\-version to set the server to not respond to such queries.
  231. .TP
  232. .B nsid:\fR <string>
  233. Add the specified nsid to the EDNS section of the answer when queried
  234. with an NSID EDNS enabled packet. As a sequence of hex characters or
  235. with ascii_ prefix and then an ascii string. Same as commandline option
  236. .BR \-I .
  237. .TP
  238. .B logfile:\fR <filename>
  239. Log messages to the logfile. The default is to log to stderr and
  240. syslog (with facility LOG_DAEMON). Same as commandline option
  241. .BR \-l .
  242. .TP
  243. .B log\-only\-syslog:\fR <yes or no>
  244. Log messages only to syslog. Useful with systemd so that print to stderr
  245. does not cause duplicate log strings in journald. Before syslog has
  246. been opened, the server uses stderr. Stderr is also used if syslog is
  247. not available. Default is no.
  248. .TP
  249. .B server\-count:\fR <number>
  250. Start this many NSD servers. Default is 1. Same as commandline
  251. option
  252. .BR \-N .
  253. .TP
  254. .B cpu\-affinity:\fR <number> <number> ...
  255. Overall CPU affinity for NSD server(s). Default is no affinity.
  256. .BR \-n .
  257. .TP
  258. .B server\-N\-cpu\-affinity:\fR <number>
  259. Bind NSD server specified by N to a specific core. Default is to have affinity
  260. set to every core specified in cpu\-affinity. This setting only takes effect
  261. if cpu\-affinity is enabled.
  262. .BR \-n
  263. .TP
  264. .B xfrd\-cpu\-affinity:\fR <number>
  265. Bind xfrd to a specific core. Default is to have affinity set to every core
  266. specified in cpu\-affinity. This setting only takes effect if cpu\-affinity is
  267. enabled.
  268. .BR \-n
  269. .TP
  270. .B tcp\-count:\fR <number>
  271. The maximum number of concurrent, active TCP connections by each server.
  272. Default is 100. Same as commandline option
  273. .BR \-n .
  274. .TP
  275. .B tcp\-reject\-overflow:\fR <yes or no>
  276. If set to yes, TCP connections made beyond the maximum set by tcp-count will
  277. be dropped immediately (accepted and closed). Default is no.
  278. .TP
  279. .B tcp\-query\-count:\fR <number>
  280. The maximum number of queries served on a single TCP connection.
  281. Default is 0, meaning there is no maximum.
  282. .TP
  283. .B tcp\-timeout:\fR <number>
  284. Overrides the default TCP timeout. This also affects zone transfers over TCP.
  285. The default is 120 seconds.
  286. .TP
  287. .B tcp-mss:\fR <number>
  288. Maximum segment size (MSS) of TCP socket on which the server responds
  289. to queries. Value lower than common MSS on Ethernet
  290. (1220 for example) will address path MTU problem.
  291. Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
  292. Default is system default MSS determined by interface MTU and
  293. negotiation between server and client.
  294. .TP
  295. .B outgoing\-tcp\-mss:\fR <number>
  296. Maximum segment size (MSS) of TCP socket for outgoing XFR request
  297. to other namesevers. Value lower than
  298. common MSS on Ethernet (1220 for example) will
  299. address path MTU problem.
  300. Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
  301. Default is system default MSS determined by interface MTU and
  302. negotiation between NSD and other servers.
  303. .TP
  304. .B ipv4\-edns\-size:\fR <number>
  305. Preferred EDNS buffer size for IPv4. Default 1232.
  306. .TP
  307. .B ipv6\-edns\-size:\fR <number>
  308. Preferred EDNS buffer size for IPv6. Default 1232.
  309. .TP
  310. .B pidfile:\fR <filename>
  311. Use the pid file instead of the platform specific default, usually
  312. .IR /run/nsd.pid.
  313. Same as commandline option
  314. .BR \-P .
  315. With "" there is no pidfile, for some startup management setups,
  316. where a pidfile is not useful to have.
  317. .TP
  318. .B port:\fR <number>
  319. Answer queries on the specified port. Default is 53. Same as
  320. commandline option
  321. .BR \-p .
  322. .TP
  323. .B statistics:\fR <number>
  324. If not present no statistics are dumped. Statistics are produced
  325. every number seconds. Same as commandline option
  326. .BR \-s .
  327. .TP
  328. .B chroot:\fR <directory>
  329. NSD will chroot on startup to the specified directory. Note that if
  330. elsewhere in the configuration you specify an absolute pathname to a file
  331. inside the chroot, you have to prepend the \fBchroot\fR path. That way,
  332. you can switch the chroot option on and off without having to modify
  333. anything else in the configuration. Set the value to "" (the empty string)
  334. to disable the chroot. By default "\fI\fR" is used. Same as
  335. commandline option
  336. .BR \-t .
  337. .TP
  338. .B username:\fR <username>
  339. After binding the socket, drop user privileges and assume the
  340. username. Can be username, id or id.gid. Same as commandline option
  341. .BR \-u .
  342. .TP
  343. .B zonesdir:\fR <directory>
  344. Change the working directory to the specified directory before accessing
  345. zone files. Also, NSD will access \fBdatabase\fR, \fBzonelistfile\fR,
  346. \fBlogfile\fR, \fBpidfile\fR, \fBxfrdfile\fR, \fBxfrdir\fR,
  347. \fBserver-key-file\fR, \fBserver-cert-file\fR, \fBcontrol-key-file\fR and
  348. \fBcontrol-cert-file\fR
  349. relative to this directory. Set the value to "" (the empty string)
  350. to disable the change of working directory. By default "\fI/etc/nsd/zone\fR"
  351. is used.
  352. .TP
  353. .B difffile:\fR <filename>
  354. Ignored, for compatibility with NSD3 config files.
  355. .TP
  356. .B xfrdfile:\fR <filename>
  357. The soa timeout and zone transfer daemon in NSD will save its state to
  358. this file. State is read back after a restart. The state file can be
  359. deleted without too much harm, but timestamps of zones will be gone.
  360. If it is configured as "", the state file is not used, all slave zones
  361. are checked for updates upon startup. For more details see the section
  362. on zone expiry behavior of NSD. Default is
  363. .IR /var/db/nsd/xfrd.state .
  364. .TP
  365. .B xfrdir:\fR <directory>
  366. The zone transfers are stored here before they are processed. A directory
  367. is created here that is removed when NSD exits. Default is
  368. .IR /tmp .
  369. .TP
  370. .B xfrd\-reload\-timeout:\fR <number>
  371. If this value is \-1, xfrd will not trigger a reload after a zone
  372. transfer. If positive xfrd will trigger a reload after a zone
  373. transfer, then it will wait for the number of seconds before it will
  374. trigger a new reload. Setting this value throttles the reloads to
  375. once per the number of seconds. The default is 1 second.
  376. .TP
  377. .B verbosity:\fR <level>
  378. This value specifies the verbosity level for (non\-debug) logging.
  379. Default is 0. 1 gives more information about incoming notifies and
  380. zone transfers. 2 lists soft warnings that are encountered. 3 prints
  381. more information.
  382. .IP
  383. Verbosity 0 will print warnings and errors, and other events that are
  384. important to keep NSD running.
  385. .IP
  386. Verbosity 1 prints additionally messages of interest. Successful notifies,
  387. successful incoming zone transfer (the zone is updated), failed incoming
  388. zone transfers or the inability to process zone updates.
  389. .IP
  390. Verbosity 2 prints additionally soft errors, like connection resets over TCP.
  391. And notify refusal, and axfr request refusals.
  392. .TP
  393. .B hide\-version:\fR <yes or no>
  394. Prevent NSD from replying with the version string on CHAOS class
  395. queries. Default is no.
  396. .TP
  397. .B hide\-identity:\fR <yes or no>
  398. Prevent NSD from replying with the identity string on CHAOS class
  399. queries. Default is no.
  400. .TP
  401. .B drop\-updates:\fR <yes or no>
  402. If set to yes, drop received packets with the UPDATE opcode. Default is no.
  403. .TP
  404. .B use\-systemd:\fR <yes or no>
  405. This option is deprecated and ignored. If compiled with libsystemd,
  406. NSD signals readiness to systemd and use of the option is not necessary.
  407. .TP
  408. .B log\-time\-ascii:\fR <yes or no>
  409. Log time in ascii, if "no" then in seconds epoch. Default is yes.
  410. This chooses the format when logging to file. The printout via syslog
  411. has a timestamp formatted by syslog.
  412. .TP
  413. .B round\-robin:\fR <yes or no>
  414. Enable round robin rotation of records in the answer. This changes the
  415. order of records in the answer and this may balance load across them.
  416. The default is no.
  417. .TP
  418. .B minimal\-responses:\fR <yes or no>
  419. Enable minimal responses for smaller answers. This makes packets smaller.
  420. Extra data is only added for referrals, when it is really necessary.
  421. This is different from the \-\-enable-minimal-responses configure time option,
  422. that reduces packets, but exactly to the fragmentation length, the nsd.conf
  423. option reduces packets as small as possible.
  424. The default is no.
  425. .TP
  426. .B confine\-to\-zone:\fR <yes or no>
  427. If set to yes, additional information will not be added to the response if the
  428. apex zone of the additional information does not match the apex zone of the
  429. initial query (E.G. CNAME resolution). Default is no.
  430. .TP
  431. .B refuse\-any:\fR <yes or no>
  432. Refuse queries of type ANY. This is useful to stop query floods trying
  433. to get large responses. Note that rrl ratelimiting also has type ANY as
  434. a ratelimiting type. It sends truncation in response to UDP type ANY queries,
  435. and it allows TCP type ANY queries like normal.
  436. The default is no.
  437. .TP
  438. .B zonefiles\-check:\fR <yes or no>
  439. Make NSD check the mtime of zone files on start and sighup. If you
  440. disable it it starts faster (less disk activity in case of a lot of zones).
  441. The default is yes. The nsd\-control reload command reloads zone files
  442. regardless of this option.
  443. .TP
  444. .B zonefiles\-write:\fR <seconds>
  445. Write changed secondary zones to their zonefile every N seconds. If the
  446. zone (pattern) configuration has "" zonefile, it is not written. Zones that
  447. have received zone transfer updates are written to their zonefile.
  448. Default is 0 (disabled) when there is a database, and 3600 (1 hour) when
  449. database is "". The database also commits zone transfer contents.
  450. You can configure it away from the default by putting the config statement
  451. for zonefiles\-write: after the database: statement in the config file.
  452. .TP
  453. .B tls\-service\-key:\fR <filename>
  454. If enabled, the server provides TLS service on TCP sockets with the TLS
  455. service port number. The port number (853) is configured with tls\-port.
  456. To turn it on, create an interface: option line in config with @port
  457. appended to the IP-address. This creates the extra socket on which the
  458. DNS over TLS service is provided.
  459. .IP
  460. The file is the private key for the TLS session. The public certificate is
  461. in the tls-service-pem file. Default is "", turned off. Requires a
  462. restart (a reload is not enough) if changed, because the private key is
  463. read while root permissions are held and before chroot (if any).
  464. .TP
  465. .B tls\-service\-pem:\fR <filename>
  466. The public key certificate pem file for the tls service. Default is "", turned off.
  467. .TP
  468. .B tls\-service\-ocsp:\fR <filename>
  469. The ocsp pem file for the tls service, for OCSP stapling. Default is "",
  470. turned off. An external process prepares and updates the OCSP stapling data.
  471. Like this,
  472. .RS 9
  473. openssl ocsp -no_nonce \\
  474. -respout /path/to/ocsp.pem \\
  475. -CAfile /path/to/ca_and_any_intermediate.pem \\
  476. -issuer /path/to/direct_issuer.pem \\
  477. -cert /path/to/cert.pem \\
  478. -url "$( openssl x509 -noout -text -in /path/to/cert.pem | grep 'OCSP - URI:' | cut -d: -f2,3 )"
  479. .RE
  480. .TP
  481. .B tls\-port:\fR <number>
  482. The port number on which to provide TCP TLS service, default is 853, only
  483. interfaces configured with that port number as @number get DNS over TLS service.
  484. .SS "Remote Control"
  485. The
  486. .B remote\-control:
  487. clause is used to set options for using the \fInsd\-control\fR(8)
  488. tool to give commands to the running NSD server. It is disabled by
  489. default, and listens for localhost by default. It uses TLS over TCP
  490. where the server and client authenticate to each other with self\-signed
  491. certificates. The self\-signed certificates can be generated with the
  492. \fInsd\-control\-setup\fR tool. The key files are read by NSD before
  493. the chroot and before dropping user permissions, so they can be outside
  494. the chroot and readable by the superuser only.
  495. .TP
  496. .B control\-enable:\fR <yes or no>
  497. Enable remote control, default is no.
  498. .TP
  499. .B control\-interface:\fR <ip4 or ip6 | interface name | absolute path>
  500. NSD will bind to the listed addresses to service control requests
  501. (on TCP). Can be given multiple times to bind multiple ip\-addresses.
  502. Use 0.0.0.0 and ::0 to service the wildcard interface. If none are given
  503. NSD listens to the localhost 127.0.0.1 and ::1 interfaces for control,
  504. if control is enabled with control\-enable.
  505. .IP
  506. If an interface name is used instead of ip4 or ip6, the list of IP addresses
  507. associated with that interface is picked up and used at server start.
  508. .IP
  509. With an absolute path, a unix local named pipe is used for control. The
  510. file is created with user and group that is configured and access bits
  511. are set to allow members of the group access. Further access can be
  512. controlled by setting permissions on the directory containing the control
  513. socket file. The key and cert files are not used when control is via the
  514. named pipe, because access control is via file and directory permission.
  515. .TP
  516. .B control\-port:\fR <number>
  517. The port number for remote control service. 8952 by default.
  518. .TP
  519. .B server\-key\-file:\fR <filename>
  520. Path to the server private key, by default
  521. .IR /etc/nsd/nsd_server.key .
  522. This file is generated by the \fInsd\-control\-setup\fR utility.
  523. This file is used by the nsd server, but not by \fInsd\-control\fR.
  524. .TP
  525. .B server\-cert\-file:\fR <filename>
  526. Path to the server self signed certificate, by default
  527. .IR /etc/nsd/nsd_server.pem .
  528. This file is generated by the \fInsd\-control\-setup\fR utility.
  529. This file is used by the nsd server, and also by \fInsd\-control\fR.
  530. .TP
  531. .B control\-key\-file:\fR <filename>
  532. Path to the control client private key, by default
  533. .IR /etc/nsd/nsd_control.key .
  534. This file is generated by the \fInsd\-control\-setup\fR utility.
  535. This file is used by \fInsd\-control\fR.
  536. .TP
  537. .B control\-cert\-file:\fR <filename>
  538. Path to the control client certificate, by default
  539. .IR /etc/nsd/nsd_control.pem .
  540. This certificate has to be signed with the server certificate.
  541. This file is generated by the \fInsd\-control\-setup\fR utility.
  542. This file is used by \fInsd\-control\fR.
  543. .SS "Pattern Options"
  544. The
  545. .B pattern:
  546. clause is used to denote a set of options to apply to some zones.
  547. The same zone options as for a zone are allowed.
  548. .TP
  549. .B name:\fR <string>
  550. The name of the pattern. This is a (case sensitive) string. The pattern
  551. names that start with "_implicit_" are used internally for zones that
  552. have no pattern (they are defined in nsd.conf directly).
  553. .TP
  554. .B include\-pattern:\fR <pattern\-name>
  555. The options from the given pattern are included at this point in
  556. this pattern. The referenced pattern must be defined above this one.
  557. .TP
  558. .B <zone option>:\fR <value>
  559. The zone options such as
  560. .BR zonefile ,
  561. .BR allow\-query ,
  562. .BR allow\-notify ,
  563. .BR request\-xfr ,
  564. .BR allow\-axfr\-fallback ,
  565. .BR notify ,
  566. .BR notify\-retry ,
  567. .BR provide\-xfr ,
  568. .BR zonestats ,
  569. and
  570. .B outgoing\-interface
  571. can be given. They are applied to the patterns and zones that include
  572. this pattern.
  573. .SS "Zone Options"
  574. .LP
  575. For every zone the options need to be specified in one
  576. .B zone:
  577. clause. The access control list elements can be given multiple
  578. times to add multiple servers. These elements need to be added
  579. explicitly.
  580. .LP
  581. For zones that are configured in the \fInsd.conf\fR config file their
  582. settings are hardcoded (in an implicit pattern for themselves only)
  583. and they cannot be deleted via delzone, but remove them from the config
  584. file and repattern.
  585. .TP
  586. .B name:\fR <string>
  587. The name of the zone. This is the domain name of the apex of the
  588. zone. May end with a '.' (in FQDN notation). For example
  589. "example.com", "sub.example.net.". This attribute must be present in
  590. each zone.
  591. .TP
  592. .B zonefile:\fR <filename>
  593. The file containing the zone information. If this attribute is present
  594. it is used to read and write the zone contents. If the attribute is
  595. absent it prevents writing out of the zone.
  596. .IP
  597. The string is processed so that one string can be used (in a pattern)
  598. for a lot of different zones. If the label or character does not exist the
  599. percent-character is replaced with a period for output (i.e. for the
  600. third character in a two letter domain name).
  601. .IP
  602. .B %s\fR is replaced with the zone name.
  603. .IP
  604. .B %1\fR is replaced with the first character of the zone name.
  605. .IP
  606. .B %2\fR is replaced with the second character of the zone name.
  607. .IP
  608. .B %3\fR is replaced with the third character of the zone name.
  609. .IP
  610. .B %z\fR is replaced with the toplevel domain name of the zone.
  611. .IP
  612. .B %y\fR is replaced with the next label under the toplevel domain.
  613. .IP
  614. .B %x\fR is replaced with the next-next label under the toplevel domain.
  615. .TP
  616. .B allow\-query:\fR <ip\-spec> <key\-name | NOKEY | BLOCKED>
  617. Access control list. When at least one \fBallow\-query\fR option is
  618. specified, then the in the \fBallow\-query\fR options specified addresses
  619. are are allowed to query the server for the zone. Queries from unlisted or
  620. specifically BLOCKED addresses are discarded. If NOKEY is given no TSIG
  621. signature is required. BLOCKED supersedes other entries, other entries are
  622. scanned for a match in the order of the statements. Without
  623. \fBallow\-query\fR options, queries are allowed from any IP address
  624. without TSIG key (which is the default).
  625. .P
  626. .RS
  627. The ip\-spec is either a plain IP address (IPv4 or IPv6), or can be
  628. a subnet of the form 1.2.3.4/24, or masked like
  629. 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4\-1.2.3.25.
  630. Note the ip\-spec ranges do not use spaces around the /, &, @ and \-
  631. symbols.
  632. .RE
  633. .TP
  634. .B allow\-notify:\fR <ip\-spec> <key\-name | NOKEY | BLOCKED>
  635. Access control list. The listed (primary) address is allowed to
  636. send notifies to this (secondary) server. Notifies from unlisted or
  637. specifically BLOCKED addresses are discarded. If NOKEY is given no
  638. TSIG signature is required.
  639. BLOCKED supersedes other entries, other entries are scanned for a match
  640. in the order of the statements.
  641. .P
  642. .RS
  643. The ip\-spec is either a plain IP address (IPv4 or IPv6), or can be
  644. a subnet of the form 1.2.3.4/24, or masked like
  645. 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4\-1.2.3.25.
  646. A port number can be added using a suffix of @number, for example
  647. 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300.
  648. Note the ip\-spec ranges do not use spaces around the /, &, @ and \-
  649. symbols.
  650. .RE
  651. .TP
  652. .B request\-xfr:\fR [AXFR|UDP] <ip\-address> <key\-name | NOKEY>
  653. Access control list. The listed address (the master) is queried for
  654. AXFR/IXFR on update. A port number can be added using a suffix of @number,
  655. for example 1.2.3.4@5300. The specified key is used during AXFR/IXFR.
  656. .P
  657. .RS
  658. If the AXFR option is given, the server will not be contacted with
  659. IXFR queries but only AXFR requests will be made to the server. This
  660. allows an NSD secondary to have a master server that runs NSD. If
  661. the AXFR option is left out then both IXFR and AXFR requests are
  662. made to the master server.
  663. .P
  664. If the UDP option is given, the secondary will use UDP to transmit the IXFR
  665. requests. You should deploy TSIG when allowing UDP transport, to authenticate
  666. notifies and zone transfers. Otherwise, NSD is more vulnerable for
  667. Kaminsky\-style attacks. If the UDP option is left out then IXFR will be
  668. transmitted using TCP.
  669. .RE
  670. .TP
  671. .B allow\-axfr\-fallback:\fR <yes or no>
  672. This option should be accompanied by request\-xfr. It (dis)allows NSD (as secondary)
  673. to fallback to AXFR if the primary name server does not support IXFR. Default is yes.
  674. .TP
  675. .B size\-limit\-xfr:\fR <number>
  676. This option should be accompanied by request\-xfr. It specifies XFR temporary file size limit. It can be used to stop very large zone retrieval, that could otherwise use up a lot of memory and disk space.
  677. If this option is 0, unlimited. Default value is 0.
  678. .TP
  679. .B notify:\fR <ip\-address> <key\-name | NOKEY>
  680. Access control list. The listed address (a secondary) is notified
  681. of updates to this zone. A port number can be added using a suffix of @number,
  682. for example 1.2.3.4@5300. The specified key is used to sign the
  683. notify. Only on secondary configurations will NSD be able to detect
  684. zone updates (as it gets notified itself, or refreshes after a
  685. time).
  686. .TP
  687. .B notify\-retry:\fR <number>
  688. This option should be accompanied by notify. It sets the number of retries
  689. when sending notifies.
  690. .TP
  691. .B provide\-xfr:\fR <ip\-spec> <key\-name | NOKEY | BLOCKED>
  692. Access control list. The listed address (a secondary) is allowed to
  693. request AXFR from this server. Zone data will be provided to the
  694. address. The specified key is used during AXFR. For unlisted or
  695. BLOCKED addresses no data is provided, requests are discarded.
  696. BLOCKED supersedes other entries, other entries are scanned for a match
  697. in the order of the statements.
  698. NSD provides AXFR for its secondaries, but IXFR is not implemented (IXFR
  699. is implemented for request\-xfr, but not for provide\-xfr).
  700. .P
  701. .RS
  702. The ip\-spec is either a plain IP address (IPv4 or IPv6), or can be
  703. a subnet of the form 1.2.3.4/24, or masked like
  704. 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4\-1.2.3.25.
  705. A port number can be added using a suffix of @number, for example
  706. 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the ip\-spec
  707. ranges do not use spaces around the /, &, @ and \- symbols.
  708. .RE
  709. .TP
  710. .B outgoing\-interface:\fR <ip\-address>
  711. Access control list. The listed address is used to request AXFR|IXFR (in case of
  712. a secondary) or used to send notifies (in case of a primary).
  713. .P
  714. .RS
  715. The ip\-address is a plain IP address (IPv4 or IPv6).
  716. A port number can be added using a suffix of @number, for example
  717. 1.2.3.4@5300.
  718. .RE
  719. .TP
  720. .B max\-refresh\-time:\fR <seconds>
  721. Limit refresh time for secondary zones. This is the timer which checks to see
  722. if the zone has to be refetched when it expires. Normally the value from the
  723. SOA record is used, but this option restricts that value.
  724. .TP
  725. .B min\-refresh\-time:\fR <seconds>
  726. Limit refresh time for secondary zones.
  727. .TP
  728. .B max\-retry\-time:\fR <seconds>
  729. Limit retry time for secondary zones. This is the timer which retries after
  730. a failed fetch attempt for the zone. Normally the value from the SOA record is
  731. used, followed by an exponential backoff, but this option restricts that value.
  732. .TP
  733. .B min\-retry\-time:\fR <seconds>
  734. Limit retry time for secondary zones.
  735. .TP
  736. .B min\-expire\-time:\fR <seconds or refresh+retry+1>
  737. Limit expire time for secondary zones. The value can be expressed either by a
  738. number of seconds, or the string "refresh+retry+1". With the latter the expire
  739. time will be lower bound to the refresh plus the retry value from the SOA
  740. record, plus 1. The refresh and retry values will be subject to the bounds
  741. configured with max\-refresh\-time, min\-refresh\-time, max\-retry\-time and
  742. min\-retry\-time if given.
  743. .TP
  744. .B zonestats:\fR <name>
  745. When compiled with \-\-enable\-zone\-stats NSD can collect statistics per zone.
  746. This name gives the group where statistics are added to. The groups are
  747. output from nsd\-control stats and stats_noreset. Default is "".
  748. You can use "%s" to use the name of the zone to track its statistics.
  749. If not compiled in, the option can be given but is ignored.
  750. .TP
  751. .B include\-pattern:\fR <pattern\-name>
  752. The options from the given pattern are included at this point.
  753. The referenced pattern must be defined above this zone.
  754. .TP
  755. .B multi\-master\-check:\fR <yes or no>
  756. Default no. If enabled, checks all masters for the last version. It uses
  757. the higher version of all the configured masters. Useful if you have multiple
  758. masters that have different version numbers served.
  759. .SS "Key Declarations"
  760. The
  761. .B key:
  762. clause establishes a key for use in access control lists. It has
  763. the following attributes.
  764. .TP
  765. .B name:\fR <string>
  766. The key name. Used to refer to this key in the access control list.
  767. The key name has to be correct for tsig to work.
  768. This is because the key name is output on the wire.
  769. .TP
  770. .B algorithm:\fR <string>
  771. Authentication algorithm for this key. Such as hmac\-md5, hmac\-sha1,
  772. hmac\-sha224, hmac\-sha256, hmac\-sha384 and hmac\-sha512. Can also be
  773. abbreviated as 'sha1', 'sha256'. Default is sha256.
  774. Algorithms are only available when they were compiled in (available in the
  775. crypto library).
  776. .TP
  777. .B secret:\fR <base64 blob>
  778. The base64 encoded shared secret. It is possible to put the
  779. .B secret:
  780. declaration (and base64 blob) into a different file, and then to
  781. .B include:
  782. that file. In this way the key secret and the rest of the configuration
  783. file, which may have different security policies, can be split apart.
  784. The content of the secret is the agreed base64 secret content. To make it
  785. up, enter a password (its length must be a multiple of 4 characters, A\-Za\-z0\-9), or use
  786. dev-random output through a base64 encode filter.
  787. .SS DNSTAP Logging Options
  788. DNSTAP support, when compiled in, is enabled in the \fBdnstap:\fR section.
  789. This starts a collector process that writes the log information to the
  790. destination.
  791. .TP
  792. .B dnstap-enable:\fR <yes or no>
  793. If dnstap is enabled. Default no. If yes, it connects to the dnstap server
  794. and if any of the dnstap-log-..-messages options is enabled it sends logs
  795. for those messages to the server.
  796. .TP
  797. .B dnstap-socket-path:\fR <file name>
  798. Sets the unix socket file name for connecting to the server that is
  799. listening on that socket. Default is "".
  800. .TP
  801. .B dnstap-send-identity:\fR <yes or no>
  802. If enabled, the server identity is included in the log messages.
  803. Default is no.
  804. .TP
  805. .B dnstap-send-version:\fR <yes or no>
  806. If enabled, the server version if included in the log messages.
  807. Default is no.
  808. .TP
  809. .B dnstap-identity:\fR <string>
  810. The identity to send with messages, if "" the hostname is used.
  811. Default is "".
  812. .TP
  813. .B dnstap-version:\fR <string>
  814. The version to send with messages, if "" the package version is used.
  815. Default is "".
  816. .TP
  817. .B dnstap-log-auth-query-messages:\fR <yes or no>
  818. Enable to log auth query messages. Default is no.
  819. These are client queries to NSD.
  820. .TP
  821. .B dnstap-log-auth-response-messages:\fR <yes or no>
  822. Enable to log auth response messages. Default is no.
  823. These are responses from NSD to clients.
  824. .SH "NSD CONFIGURATION FOR BIND9 HACKERS"
  825. BIND9 is a name server implementation with its own configuration
  826. file format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.
  827. .SS "Slave zones"
  828. For a slave zone, the master servers are listed. The master servers are
  829. queried for zone data, and are listened to for update notifications.
  830. In NSD these two properties need to be configured separately, by listing
  831. the master address in allow\-notify and request\-xfr statements.
  832. .P
  833. In BIND9 you only need to provide allow\-notify elements for
  834. any extra sources of notifications (i.e. the operators), NSD needs to have
  835. allow\-notify for both masters and operators. BIND9 allows
  836. additional transfer sources, in NSD you list those as request\-xfr.
  837. .P
  838. Here is an example of a slave zone in BIND9 syntax.
  839. .P
  840. # Config file for example.org
  841. options {
  842. .RS 5
  843. dnssec\-enable yes;
  844. .RE
  845. .RS 0
  846. };
  847. .RE
  848. .LP
  849. key tsig.example.org. {
  850. .RS 5
  851. algorithm hmac\-md5;
  852. .RE
  853. .RS 5
  854. secret "aaaaaabbbbbbccccccdddddd";
  855. .RE
  856. };
  857. .LP
  858. server 162.0.4.49 {
  859. .RS 5
  860. keys { tsig.example.org. ; };
  861. .RE
  862. };
  863. .LP
  864. zone "example.org" {
  865. .RS 5
  866. type slave;
  867. .RE
  868. .RS 5
  869. file "secondary/example.org.signed";
  870. .RE
  871. .RS 5
  872. masters { 162.0.4.49; };
  873. .RE
  874. };
  875. .P
  876. For NSD, DNSSEC is enabled automatically for zones that are signed. The
  877. dnssec\-enable statement in the options clause is not needed. In NSD
  878. keys are associated with an IP address in the access control list
  879. statement, therefore the server{} statement is not needed. Below is
  880. the same example in an NSD config file.
  881. .LP
  882. # Config file for example.org
  883. .RS 0
  884. key:
  885. .RE
  886. .RS 5
  887. name: tsig.example.org.
  888. .RE
  889. .RS 5
  890. algorithm: hmac\-md5
  891. .RE
  892. .RS 5
  893. secret: "aaaaaabbbbbbccccccdddddd"
  894. .RE
  895. .LP
  896. zone:
  897. .RS 5
  898. name: "example.org"
  899. .RE
  900. .RS 5
  901. zonefile: "secondary/example.org.signed"
  902. .RE
  903. .RS 5
  904. # the master is allowed to notify and will provide zone data.
  905. .RE
  906. .RS 5
  907. allow\-notify: 162.0.4.49 NOKEY
  908. .RE
  909. .RS 5
  910. request\-xfr: 162.0.4.49 tsig.example.org.
  911. .RE
  912. .P
  913. Notice that the master is listed twice, once to allow it to send notifies
  914. to this slave server and once to tell the slave server where to look for
  915. updates zone data. More allow\-notify and request\-xfr lines can be
  916. added to specify more masters.
  917. .P
  918. It is possible to specify extra allow\-notify lines for addresses
  919. that are also allowed to send notifications to this slave server.
  920. .SS "Master zones"
  921. For a master zone in BIND9, the slave servers are listed. These slave
  922. servers are sent notifications of updated and are allowed to request
  923. transfer of the zone data. In NSD these two properties need to be
  924. configured separately.
  925. .P
  926. Here is an example of a master zone in BIND9 syntax.
  927. .LP
  928. zone "example.nl" {
  929. .RS 5
  930. type master;
  931. .RE
  932. .RS 5
  933. file "example.nl";
  934. .RE
  935. };
  936. .LP
  937. In NSD syntax this becomes:
  938. .LP
  939. zone:
  940. .RS 5
  941. name: "example.nl"
  942. .RE
  943. .RS 5
  944. zonefile: "example.nl"
  945. .RE
  946. .RS 5
  947. # allow anybody to request xfr.
  948. .RE
  949. .RS 5
  950. provide\-xfr: 0.0.0.0/0 NOKEY
  951. .RE
  952. .RS 5
  953. provide\-xfr: ::0/0 NOKEY
  954. .RE
  955. .P
  956. .RS 5
  957. # to list a slave server you would in general give
  958. .RE
  959. .RS 5
  960. # provide\-xfr: 1.2.3.4 tsig\-key.name.
  961. .RE
  962. .RS 5
  963. # notify: 1.2.3.4 NOKEY
  964. .RE
  965. .SS "Other"
  966. NSD is an authoritative only DNS server. This means that it is
  967. meant as a primary or secondary server for zones, providing DNS
  968. data to DNS resolvers and caches. BIND9 can function as an
  969. authoritative DNS server, the configuration options for that are
  970. compared with those for NSD in this section. However, BIND9 can
  971. also function as a resolver or cache. The configuration options that
  972. BIND9 has for the resolver or caching thus have no equivalents for NSD.
  973. .SH "FILES"
  974. .TP
  975. /var/db/nsd/nsd.db
  976. default
  977. .B NSD
  978. database
  979. .TP
  980. /etc/nsd/nsd.conf
  981. default
  982. .B NSD
  983. configuration file
  984. .SH "SEE ALSO"
  985. \fInsd\fR(8), \fInsd\-checkconf\fR(8), \fInsd\-control\fR(8)
  986. .SH "AUTHORS"
  987. .B NSD
  988. was written by NLnet Labs and RIPE NCC joint team. Please see
  989. CREDITS file in the distribution for further details.
  990. .SH "BUGS"
  991. .B nsd.conf
  992. is parsed by a primitive parser, error messages may not be to the
  993. point.