DragonFly On-Line Manual Pages
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
attributes 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
ignored as is whitespace at the beginning of a line.
Credns.conf specifies options for the credns server, zone files,
primaries 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
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.
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
commandline option -4.
ip6-only: <yes or no>
If yes, credns only listens to IPv6 connections. Same as
commandline 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
commandline 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
commandline 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
transfers 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,
usually /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
option -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)
logging. Default is 0. 1 gives more information about incoming
notifies and zone transfers. 2 lists soft warnings that are
encountered.
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:
attribute is given. The default is port 5347.
verifier-timeout: <number>
The maximum number of seconds a verifier should take for
assessing one zone. If the verifier takes longer, it will be
terminated 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
"example.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
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.
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
suffix 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
transmit the IXFR requests. You should deploy TSIG when allowing
UDP transport, to authenticate notifies and zone transfers.
Otherwise, 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
notified 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
discarded.
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.
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
assessed 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
verifier. 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
assessing one zone. If the verifier takes longer, it will be
terminated 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
secret: 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
security 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
allow-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
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.
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
authoritative 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), crednspatch(8)
, credns-xfer(8)
AUTHORS
Credns was written by NLnet Labs.
NSD was written by NLnet Labs and RIPE NCC joint team. Please see
CREDITS 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 June 22, 2012 credns.conf(5)