Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
credns.conf(5)			 credns	0.2.10			credns.conf(5)

NAME
       credns.conf - Credns configuration file

SYNOPSIS
       credns.conf

DESCRIPTION
       Credns.conf  is	used  to  configure credns(8). The file	format has at-
       tributes	and values. Some attributes have attributes inside  them.  The
       notation	is: attribute: value.

       Comments	 start with # and last to the end of line. Empty lines are ig-
       nored as	is whitespace at the beginning of a line.

       Credns.conf specifies options for the credns server, zone  files,  pri-
       maries and secondaries.

EXAMPLE
       An example of a short credns.conf file is below.

       # Example.com credns.conf file
       # This is a comment.

       server:
	    database: "/var/db/nsd/nsd.db"
	    username:
	    logfile: "/var/log/credns.log"
	    pidfile: "/var/run/nsd/nsd.pid"
	    difffile: "/var/db/nsd/ixfr.db"
	    xfrdfile: "/var/db/nsd/xfrd.state"
	    ip-address:	10.10.0.1

       zone:
	    name: example.com

	    # Accept notifies and xfr from the hidden master
	    allow-notify: 10.0.0.1 NOKEY
	    request-xfr: 10.0.0.1 NOKEY

	    verifier: ldns-verify-zone -V2

	    # Notify and xfr to	the public slave
	    notify: 10.20.0.1 NOKEY
	    provide-xfr: 10.20.0.1 NOKEY

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.

       At  the	top level only server: or zone:	or key:	are allowed. These are
       followed	by their attributes or the start of a new server: or zone:  or
       key:  clause.  The  zone:  attribute  is	 followed by zone options. The
       server: attribute is followed by	global options for the credns  server.
       A key: attribute	is used	to define keys for authentication.

       Files  can be included using the	include: directive. It can appear any-
       where, 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.

   Server Options
       The global options (if not overridden from the credns commandline)  are
       taken from the server: clause. There may	only be	one server: clause.

       ip-address: <ip4	or ip6>[@port]
	      Credns  will bind	to the listed ip-address. Can be give multiple
	      times to bind multiple ip-addresses. Optionally, a  port	number
	      can be given.  If	none are given dnssext listens to the wildcard
	      interface. Same as commandline option -a.

       debug-mode: <yes	or no>
	      Turns on debugging mode for  credns,  does  not  fork  a	daemon
	      process.	Default	is no. Same as commandline option -d.

       ip4-only: <yes or no>
	      If yes, credns only listens to IPv4 connections. Same as comman-
	      dline option -4.

       ip6-only: <yes or no>
	      If yes, credns only listens to IPv6 connections. Same as comman-
	      dline option -6.

       database: <filename>
	      By  default  /var/db/nsd/nsd.db  is  used. The specified file is
	      used to store the	compiled zone information. Same	as commandline
	      option -f.

       identity: <string>
	      Returns  the specified identity when asked for CH	TXT ID.SERVER.
	      Default is the name as returned by gethostname(3). Same as  com-
	      mandline option -i.

       nsid: <string>
	      Add  the	specified  nsid	to the EDNS section of the answer when
	      queried with an NSID EDNS	enabled	packet.	 Same  as  commandline
	      option -I.

       logfile:	<filename>
	      Log messages to the logfile. The default is to log to stderr and
	      syslog (with facility LOG_DAEMON). Same  as  commandline	option
	      -l.

       server-count: <number>
	      Start  this  many	credns servers.	Default	is 1. Same as command-
	      line option -N.

       tcp-count: <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	-n.

       tcp-query-count:	<number>
	      The maximum number of queries served on a	single TCP connection.
	      Default is 0, meaning there is no	maximum.

       tcp-timeout: <number>
	      Overrides	the default TCP	timeout. This also affects zone	trans-
	      fers over	TCP.

       ipv4-edns-size: <number>
	      Preferred	EDNS buffer size for IPv4.

       ipv6-edns-size: <number>
	      Preferred	EDNS buffer size for IPv6.

       pidfile:	<filename>
	      Use the pid file instead of the platform specific	default,  usu-
	      ally /var/run/nsd/nsd.pid.  Same as commandline option -P.

       port: <number>
	      Answer  queries  on  the	specified port.	Default	is 53. Same as
	      commandline option -p.

       statistics: <number>
	      If not present no	statistics are dumped. Statistics are produced
	      every number seconds. Same as commandline	option -s.

       zone-stats-file:	<filename>
	      If per zone statistics is	enabled, file to dump the statistics.

       chroot: <directory>
	      Credns  will  chroot on startup to the specified directory. Same
	      as commandline option -t.

       username: <username>
	      After binding the	socket,	drop user privileges  and  assume  the
	      username.	Can be username, id or id.gid. Same as commandline op-
	      tion -u.

       zonesdir: <directory>
	      Change the working directory to the specified  directory	before
	      accessing	  zone	files.	Same  as  commandline  option  -d  for
	      zonec(8).	Also credns(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.

       difffile: <filename>
	      When credns 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
	      /var/db/nsd/ixfr.db.

       xfrdfile: <filename>
	      The soa timeout and zone transfer	daemon in credns 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 credns. Default is /var/db/nsd/xfrd.state.

       xfrd-reload-timeout: <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.

       verbosity: <level>
	      This value specifies the verbosity level	for  (non-debug)  log-
	      ging.  Default is	0. 1 gives more	information about incoming no-
	      tifies and zone transfers. 2 lists soft warnings	that  are  en-
	      countered.

       hide-version: <yes or no>
	      Prevent  credns  from  replying with the version string on CHAOS
	      class queries.

       verifier-count: <number>
	      Number of	verifiers that may run simultaneously.	0  means  that
	      no  verifiers should be run at all, which	will prevent all zones
	      -	with a verifier: attribute in their zone: clause - from	 being
	      updated by IXFR or AXFR.	The default is 1.

       verifier-feed-zone: <yes	or no>
	      Feed  a  by  IXFR	 or  AXFR  updated  zone to the	standard input
	      (stdin) of a verifier.  The default is  "yes".   This  attribute
	      may be overloaded	per zone.

       verify-ip-address: <ip4 or ip6>[@port]
	      Serve the	zone to	the verifier on	the listed ip-address.	Can be
	      given multiple times to bind multiple ip-addresses.  Optionally,
	      a	 port  number  can  be	given.	 The  default  is  to  have no
	      verify-ip-address: and to	not serve the zone to a	verifier.

       verify-port: <number>
	      Serve the	zone to	the verifier on	this port.  Note that the zone
	      will  not	be served to a verifier	when no	verify-ip-address: at-
	      tribute is given.	 The default is	port 5347.

       verifier-timeout: <number>
	      The maximum number of seconds a verifier should take for assess-
	      ing  one	zone.  If the verifier takes longer, it	will be	termi-
	      nated and	the update to the zone will be discarded.  The default
	      is  0  seconds  which  means the verifier	may take as long as it
	      needs.  This attribute may be overloaded per zone.

   Zone	Options
       For every zone the options need to be specified in  one	zone:  clause.
       The  access  control  list  elements can	be given multiple times	to add
       multiple	servers. These elements	need to	be added explicitly.

       name: <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	"exam-
	      ple.com",	"sub.example.net.". This attribute must	be present  in
	      each zone.

       zonefile: <filename>
	      The  file	 containing the	zone information. This file is used by
	      zonec(8).	This attribute must be present in each zone.

       allow-notify: <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.

	      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	 exam-
	      ple  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  -  sym-
	      bols.

       request-xfr: [AXFR|UDP] <ip-address> <key-name |	NOKEY>
	      Access  control list. The	listed address (the master) is queried
	      for AXFR/IXFR on update. A port number can be added using	a suf-
	      fix  of  @number,	for example 1.2.3.4@5300. The specified	key is
	      used during AXFR/IXFR.

	      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 credns 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.

	      If the UDP option	is given, the secondary	will use UDP to	trans-
	      mit  the IXFR requests. You should deploy	TSIG when allowing UDP
	      transport, to authenticate notifies and zone  transfers.	Other-
	      wise,  credns  is	more vulnerable	for Kaminsky-style attacks. If
	      the UDP option is	left out then IXFR will	be  transmitted	 using
	      TCP.

       allow-axfr-fallback: <yes or no>
	      This option should be accompanied	by request-xfr.	It (dis)allows
	      credns (as secondary) to fallback	to AXFR	if  the	 primary  name
	      server does not support IXFR. Default is yes.

       notify: <ip-address> <key-name |	NOKEY>
	      Access  control  list. The listed	address	(a secondary) is noti-
	      fied of updates to this zone. A port number can be added using a
	      suffix  of  @number, for example 1.2.3.4@5300. The specified key
	      is used to sign the notify.  Only	 on  secondary	configurations
	      will  credns be able to detect zone updates (as it gets notified
	      itself, or refreshes after a time).

       notify-retry: <number>
	      This option should be accompanied	by notify. It sets the	number
	      of retries when sending notifies.

       provide-xfr: <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  dis-
	      carded.

	      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	 exam-
	      ple  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  -  sym-
	      bols.

       outgoing-interface: <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).

	      The  ip-address  is  a  plain IP address (IPv4 or	IPv6).	A port
	      number can be added using	 a  suffix  of	@number,  for  example
	      1.2.3.4@5300.

       verifier: <program with arguments>
	      When  an	update is received for the zone	(by IXFR or AXFR) this
	      program will be run to asses the zone with the update.  When the
	      program  exits  with  a status code of 0,	the zone is considered
	      good and will be served.	Any other status code  will  designate
	      the  zone	bad and	the received update will be discarded.	Credns
	      will then	continue to serve the zone but without the update.

	      The following environment	variables are available	for verifiers:

		     VERIFY_ZONE
			    The	domain name of the zone	to be verified.
		     VERIFY_ZONE_ON_STDIN
			    When the zone can be read from the standard	input,
			    this  variable  will be set	to "yes", otherwise it
			    will be empty.
		     VERIFY_IP_ADDRESSES
			    A  list  of	 <ip-address>@<port>  combinations  on
			    which the zones to be assessed will	be served.
		     VERIFY_IP_ADDRESS
			    The	 first	address	 on  which the zones to	be as-
			    sessed will	be served.  If IPv6  is	 available  an
			    IPv6 address will be prefered over IPv4.
		     VERIFY_PORT
			    the	port number for	VERIFY_IP_ADDRESS
		     VERIFY_IPV6_ADDRESS
			    The	 first	IPv6  address on which the zones to be
			    assessed will be served.
		     VERIFY_IPV6_PORT
			    The	port number for	VERIFY_IPV6_ADDRESS.
		     VERIFY_IPV4_ADDRESS
			    The	first IPv4 address on which the	 zones	to  be
			    assessed will be served.
		     VERIFY_IPV4_PORT
			    The	port number for	VERIFY_IPV4_ADDRESS.

       verifier-feed-zone: <yes, no or inherit>
	      Feed the updated zone on the standard input (stdin) of the veri-
	      fier.  The default is "inherit", which means that	the  value  of
	      the  verifier-feed-zone:	attribute from the server: clause will
	      be used.

       verifier-timeout: <number or inherit>
	      The maximum number of seconds a verifier should take for assess-
	      ing  one	zone.  If the verifier takes longer, it	will be	termi-
	      nated and	the update to the zone will be discarded.  The default
	      is    "inherit",	 which	 means	 that	the   value   of   the
	      verifier-timeout:	attribute from	the  server:  clause  will  be
	      used.

   Key Declarations
       The  key:  clause establishes a key for use in access control lists. It
       has the following attributes.

       name: <string>
	      The key name. Used to refer to this key in  the  access  control
	      list.

       algorithm: <string>
	      Authentication algorithm for this	key.

       secret: <base64 blob>
	      The  base64 encoded shared secret. It is possible	to put the se-
	      cret: declaration	(and base64 blob) into a different  file,  and
	      then  to	include: that file. In this way	the key	secret and the
	      rest of the configuration	file, which may	have  different	 secu-
	      rity policies, can be split apart.

CREDNS 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'.

   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 credns these two properties need to  be  configured  separately,  by
       listing the master address in allow-notify and request-xfr statements.

       In  BIND9  you only need	to provide allow-notify	elements for any extra
       sources of notifications	(i.e. the operators), credns needs to have al-
       low-notify  for	both  masters  and  operators. BIND9 allows additional
       transfer	sources, in credns you list those as request-xfr.

       Here is an example of a slave zone in BIND9 syntax.

       # Config	file for example.org options {
	    dnssec-enable yes;
       };

       key tsig.example.org. {
	    algorithm hmac-md5;
	    secret "aaaaaabbbbbbccccccdddddd";
       };

       server 162.0.4.49 {
	    keys { tsig.example.org. ; };
       };

       zone "example.org" {
	    type slave;
	    file "secondary/example.org.signed";
	    masters { 162.0.4.49; };
       };

       For credns, DNSSEC is enabled automatically for zones that are  signed.
       The  dnssec-enable  statement  in  the options clause is	not needed. In
       credns 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 credns	config file.

       # Config	file for example.org
       key:
	    name: tsig.example.org.
	    algorithm: hmac-md5
	    secret: "aaaaaabbbbbbccccccdddddd"

       zone:
	    name: "example.org"
	    zonefile: "secondary/example.org.signed"
	    # the master is allowed to notify and will provide zone data.
	    allow-notify: 162.0.4.49 NOKEY
	    request-xfr: 162.0.4.49 tsig.example.org.

       Notice that the master is listed	twice, once to allow it	to send	 noti-
       fies  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.

       It  is  possible	to specify extra allow-notify lines for	addresses that
       are also	allowed	to send	notifications to this slave server.

   Providing transfer
       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 credns these two properties  need	to  be
       configured separately.

       Here is an example of a master zone in BIND9 syntax.

       zone "example.nl" {
	    type master;
	    file "example.nl";
       };

       In credns syntax	this becomes:

       zone:
	    name: "example.nl"
	    zonefile: "example.nl"
	    # allow anybody to request xfr.
	    provide-xfr: 0.0.0.0/0 NOKEY
	    provide-xfr: ::0/0 NOKEY

	    # to list a	slave server you would in general give
	    # provide-xfr: 1.2.3.4 tsig-key.name.
	    # notify: 1.2.3.4 NOKEY

   Other
       Credns  is  an  authoritative  transfer only DNS. This means that it is
       meant to	request	and provide transfer and notifies to other  authorita-
       tive  nameservers.   BIND9 can function as an authoritative DNS server,
       the configuration options for that are compared with those  for	credns
       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 credns.

FILES
       /var/db/nsd/nsd.db
	      default credns database

       /usr/local/etc/credns/credns.conf
	      default credns configuration file

SEE ALSO
       credns(8),  crednsc(8),	credns-checkconf(8), credns-notify(8), credns-
       patch(8), credns-xfer(8)

AUTHORS
       Credns was written by NLnet Labs.

       NSD was written by NLnet	Labs and RIPE NCC joint	team. Please see CRED-
       ITS file	in the distribution for	further	details.

BUGS
       credns.conf  is parsed by a primitive parser, error messages may	not be
       to the point.

NLnet Labs			 jun 22, 2012			credns.conf(5)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | FILE FORMAT | CREDNS CONFIGURATION FOR BIND9 HACKERS | FILES | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=credns.conf&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help