Using OpenDNSSEC v1.1.0

This documentation is based on OpenDNSSEC v1.1.0

The goal of OpenDNSSEC is to have a complete DNSSEC zone signing system which maintains stability and security of signed domains. DNSSEC adds many cryptographic concerns to DNS; OpenDNSSEC automates those to allow current DNS administrators to adopt DNSSEC. This document provides DNS administrators with the necessary information to get the system up and running with a basic configuration.


Before you start to use OpenDNSSEC in your production environment you must first decide which hardware you going to run on. When you have a good system to run on, then it is time to install the software that OpenDNSSEC depends on, and finally installing OpenDNSSEC.

Here are some short recommendations if you are planning to use OpenDNSSEC with many zones or a single large zone, and where the time is important.

OpenDNSSEC is multithreaded when it concerns the handling of multiple zone. But it is not currently multithreaded in the handling of a single zone. So a multicore machine will not give any benefits if you plan to only run a single large zone. It is thus, in this case, more important to go with a CPU that is fast rather than a CPU with many cores.

The zones are stored on disc and so are the temporary files that are used in the signing process. The temporary files are saved between the processes in order to e.g. increase the zone signing speed or to re-use old signatures. This means that OpenDNSSEC will use up to seven times the zone size on the HDD.

OpenDNSSEC has been tested on the following platforms:

  • Debian Linux 5.0
  • Mac OS X 10.5
  • OpenBSD 4.4
  • Red Hat Enterprise Linux 5
  • Solaris 10
  • Ubuntu Linux 8.04

OpenDNSSEC depends on a number of open-source packages, all of which must be installed on your system for OpenDNSSEC to build successfully.

The  Installation of depencencies guide shows which packages are required and how to download/install them.

NOTE: You also need an  HSM.

Choose from any vendor that uses the  PKCS#11 interface. Or the software-only implementation of an HSM called SoftHSM created by the OpenDNSSEC project. Follow these instructions on  how to install SoftHSM.

OpenDNSSEC packages are available for the following systems:

FreeBSD and NetBSD  http://pkgsrc.se/wip/opendnssec

The latest version of OpenDNSSEC can be found as a tarball on  http://www.opendnssec.org

The development (unstable) version of OpenDNSSEC is available from the Subversion repository and can be obtained using the following command:

svn co http://svn.opendnssec.org/trunk/OpenDNSSEC OpenDNSSEC

If you downloaded the tarball then first untar it:

 tar -xzf opendnssec-<VERSION>.tar.gz
 cd OpenDNSSEC

or if you are working from the repository:

 cd OpenDNSSEC
 sh autogen.sh

Then it is time to configure the build scripts:

 ./configure

You may also need some other options to configure.

  --disable-auditor       Disable auditor build (default enabled)
  --enable-eppclient      Enable eppclient build (default disabled) (experimental)
  --with-database-backend Select database backend (sqlite3|mysql) (default sqlite)

Use the following command to find out which other options that are available:

 ./configure --help

The configure script defaults to –prefix=/usr/local, –sysconfdir=/etc, and –localstatedir=/var

Once configured, build OpenDNSSEC using:

 make

… and install using …

 sudo make install

If the build fails it might be because of a missing software dependency. Please read the error messages carefully.

Depending on operating system, there may be a few additional steps required after installation.

Linux Users Linux users need to rebuild the dynamic linker caches. To do this, issue the command:

sudo ldconfig [library-path [library-path ...]]

If OpenDNSSEC or any of the pre-requisites were installed in non-standard directories, the list of library paths should be specified as arguments on the command line.


The default configuration installs good default values for anyone who just wants to sign their domains with DNSSEC. There are four configuration files for the basic OpenDNSSEC installation. You have conf.xml which is the overall configuration of the system, kasp.xml which contains the policy of signing, then there is zonelist.xml where you list all the zones that you are going to sign, and finally an optional zonefetch.xml for zone transfers.

Before describing each of the configuration files, we need to explain how timing is described in all of them. All date/time durations in the configuration files are specified as defined by  ISO 8601.

Durations are represented by the format P[n]Y[n]M[n]DT[n]H[n]M[n]S. In these representations, the [n] is replaced by the value for each of the date and time elements that follow the [n]. Leading zeros are not required. The capital letters ‘P’, ‘Y’, ‘M’, ‘W’, ‘D’, ‘T’, ‘H’, ‘M’, and ‘S’ are designators for each of the date and time elements and are not replaced.

  • P is the duration designator (historically called “period”) placed at the start of the duration representation.
  • Y is the year designator that follows the value for the number of years.
  • M is the month designator that follows the value for the number of months.
  • W is the week designator that follows the value for the number of weeks.
  • D is the day designator that follows the value for the number of days.
  • T is the time designator that precedes the time components of the representation.
  • H is the hour designator that follows the value for the number of hours.
  • M is the minute designator that follows the value for the number of minutes.
  • S is the second designator that follows the value for the number of seconds.

For example, “P3Y6M4DT12H30M5S” represents a duration of “three years, six months, four days, twelve hours, thirty minutes, and five seconds”. Date and time elements including their designator may be omitted if their value is zero, and lower order elements may also be omitted for reduced precision. For example, “P23DT23H” and “P4Y” are both acceptable duration representations.

Exception: A year or month vary in duration depending on the current date. For OpenDNSSEC, we assume fixed values

  • One month is assumed to be 31 days.
  • One year is assumed to be 365 days.

The overall configuration of OpenDNSSEC is defined by the contents of the file /etc/opendnssec/conf.xml. In this configuration file you specify logging facilities (only syslog is supported now), system paths, key repositories, privileges, and the database where all key and zone information is stored.

Read more  details about conf.xml

kasp.xml – found by default in /etc/opendnssec – is the file that defines policies used to sign zones. KASP stands for “Key and Signature Policy?, and each policy details

  • security parameters used for signing zones
  • timing parameters used for signing zones

You can have any number of policies and refer to the proper one by name in for example the zonelist.xml configuration file.

Read more  details about kasp.xml

The zonelist.xml file is used when first setting up the system, but also used by the ods-signerd when signing zones. For each zone, it contains a Zone tag with information about

  • the zone’s DNS name
  • the policy from kasp.xml used to sign the zone
  • how to obtain the zone
  • how to publish the zone

Read more  details about zonelist.xml

OpenDNSSEC can sign zonefiles on disk, but can also sign zones received from transfer (AXFR). If you configure a zone fetcher configuration, the Signer Engine will kick off the zone fetcher that will listen to NOTIFY messages from the parent and store AXFR messages on disk.

Information in this file details

  • where to fetch zone data from
  • protection mechanisms to be used

Read more  details about zonefetch.xml

There are also xml files for each of the zones that the user wants to sign, but those are only used for communication between the Enforcer and the Signer Engine. And they are created automatically be the Enforcer. The location of these files can be found in zonelist.xml.

The OpenDNSSEC XML configuration files (conf.xml and kasp.xml) offer the user many options to customise the OpenDNSSEC signing system. Not all possible configuration texts are meaningful however.

A tool (ods-kaspcheck) is provided to check that the configuration files (conf.xml and kasp.xml) are semantically sane and contain no inconsistencies. It is advisable to use this tool to check your configuration before starting to use OpenDNSSEC.


The overall configuration of OpenDNSSEC is defined by the contents of the file /etc/opendnssec/conf.xml. In this configuration file you specify logging facilities (only syslog is supported now), system paths, key repositories, privileges, and the database where all key and zone information is stored.

Preamble

<?xml version="1.0" encoding="UTF-8"?>

<!-- $Id: conf.xml.in 1143 2009-06-24 12:10:40Z jakob $ -->

Each XML file starts with a standard element “<?xml…”. As with any XML file, comments are included between the delimiters “<!–” and “–>”.

Configuration

<Configuration>

The enclosing element of the XML file is the element <Configuration> which, with the closing element </Configuration>, brackets the configuration information.

Repositories

	<RepositoryList>

OpenDNSSEC stores its keys in “repositories”. There must be at least one repository, although the system can be configured to run with multiple repositories.

There are a number of reasons for running with multiple repositories, including:

  • Temporarily running with multiple repositories whilst a switch is made from one repository to another, e.g. when replacing hardware.
  • The chosen type of repository has a limit on the number of keys that can be stored, and multiple repositories are needed to handle the chosen number of keys.
  • Different types of repository are needed for different security levels, e.g. a key-signing key may require a higher level of security than a zone-signing key.

In practice, all repositories are “HSM”s (hardware security modules) or an emulation of one.

SoftHSM

The software emulation of an HSM – SoftHSM – must be installed separately but is part of the OpenDNSSEC project, and its definition is shown below. The element names will be explained later.

		<Repository name="SoftHSM">
			<Module>/usr/local/lib/libsofthsm.so</Module>
			<TokenLabel>OpenDNSSEC</TokenLabel>
			<PIN>1234</PIN>
		</Repository>

HSM

As indicated, any number of repositories can be specified in the configuration file:

<!--
		<Repository name="sca6000">
			<Module>/usr/lib/libpkcs11.so</Module>
			<TokenLabel>Sun Metaslot</TokenLabel>
			<PIN>test:1234</PIN>
			<Capacity>1000</Capacity>
			<RequireBackup/>
		</Repository>
-->

(The example above is commented out by the XML comment delimiters.)

<Repository> – the definition of a repository is bracketed by the <Repository> and </Repository> elements. The name attribute must be supplied and must be unique. It is this name that is used in the  kasp.xml file to identify which repository holds the keys.

<Module> identifies the dynamic-link library that controls the repository. Each type of HSM will have its own library.

<TokenLabel> identifies the “token” within the HSM that is being used – essentially a form of sub-repository. The token label is also used where there are two repositories of the same type, in that each repository should contain a different token label sub-repository. OpenDNSSEC will automatically go to the right HSM based on this.

<PIN> is the password to the HSM. OpenDNSSEC have this stored en-claire in the configuration file. Later versions will allow the option of requiring the password to be typed in when OpenDNSSEC is started.

<Capacity> indicates the maximum number of keys the HSM can store. It is an optional element – if there is no (realistic) limit to the number of keys, remove it.

<RequireBackup> is an optional element that specifies that keys from this repository may not be used until they are backed up. If backup has been done, then use ods-ksmutil to notify OpenDNSSEC about this. The backup notification is needed for OpenDNSSEC to be able to complete a key rollover.

	</RepositoryList>

The list of repositories ends with the closing tag.

Common

These are the configuration that is shared among the components of OpenDNSSEC.

	<Common>
		<Logging>
			<Syslog><Facility>local0</Facility></Syslog>
		</Logging>

		<PolicyFile>/etc/opendnssec/kasp.xml</PolicyFile>
		<ZoneListFile>/etc/opendnssec/zonelist.xml</ZoneListFile>

		<!--
			<ZoneFetchFile>/etc/opendnssec/zonefetch.xml</ZoneFetchFile>
		-->
	</Common>

All components of HSM log error, warning and progress information. This is configurable and defined in the <Logging> element. Currently, the only syslog() feature configurable via the OpenDNSSEC configuration file is the facility name under which messages are logged. This can be any of the names listed in the operating system’s syslog header file (usually /usr/include/sys/syslog.h, but the location is system dependent). Although any facility listed there can be used, it is recommended that one of the “local” facilities (usually “local0″ through “local7″) be used.

Then you also have pointers to where the policy and zone list files can be found. There are also an optional element where you specify the path of the zone fetch configuration used for inbound AXFR.

Enforcer
The KASP enforcer component of OpenDNSSEC – which deals with key rollover and key generation – has its own section in the configuration file:

	<Enforcer>
	<!--
		<Privileges>
			<User>opendnssec</User>
			<Group>opendnssec</Group>
		</Privileges>
	-->

		<Datastore><SQLite>/var/opendnssec/kasp.db</SQLite></Datastore>
		<Interval>PT3600S</Interval>
	</Enforcer>

The section is bracketed by the <Enforcer> .. </Enforcer> tags.

The Enforcer can drop its privileges if specified.

The database used by the Enforcer is specified by the <Datastore> tag. OpenDNSSEC supports SQLite and MySQL, the choice being indicated by one of two mutually exclusive tags:

SQLite

If SQLite is the database in use, the <Datastore> tag must contain a single <SQLite> tag which specifies the database file in use (as shown above).

MySql

Note: The support of MySQL is considered experimental

If MySQL is in use, then the <Datastore> contains a single <MySQL> tag, which in turn contains elements that describe the database connection. The following XML elements shows this:

		<Datastore>
			<MySQL>
				<Host port="1213">dnssec-db</Host>
				<Database>KASP</Database>
				<Username>kaspuser</Username>
				<Password>abc123</Password>
			</MySQL>
		</Datastore>

<Host> is the name of the system on which the database resides. It is optional – if omitted, the database is assumed to run on the same system as OpenDNSSEC. The “port” attribute gives the port to which the !MySQL connection is made. It too is optional, and defaults to 3306 if omitted.

<Database> is the name of the database holding the KASP Enforcer data.

<Username> is the username needed to connect to the database.

<Password> is the password associated with the username.

Other Enforcer Parameters

<Interval> is how often the Enforcer runs to check whether keys are coming up for expiry and should be rolled. The more frequently this is run, the closer will the usage of keys reflect the policy set for it. However, if the key lifetimes are in the order of months, an <Interval> of the order of a day to a week is sufficient.

Signer Configuration

The Signer Engine of OpenDNSSEC – the part that constructs signature records to include in to the zone file – also has its own section in the configuration file:

	<Signer>
	<!--
		<Privileges>
			<User>opendnssec</User>
			<Group>opendnssec</Group>
		</Privileges>
	-->
		<WorkingDirectory>/var/opendnssec/tmp</WorkingDirectory>
		<WorkerThreads>8</WorkerThreads>

	<!--
		<NotifyCommand>/usr/local/bin/my_nameserver_reload_command</NotifyCommand>
	-->
	</Signer>

Delimited by the <Signer> .. </Signer> tags, the components are:

  • <Privileges> the Signer Engine can drop its privileges if specified.
  • <WorkingDirectory> defines the location in which the Signer Engine will create temporary files.
  • <WorkerThreads> specify the number of workers. One worker can handle one zone a time. When it is finished with the zone it takes the next one in queue.
  • <NotifyCommand> optional element that will tell the Signer Engine to call this command when the zone has been signed. Will expand the following variables: %zone (the name of the zone that was signed) and %zonefile (the filename of the signed zone).

Auditor Configuration

The Auditor can check a signed zone against the policy and the unsigned zone. This is to verify that the everything is done correctly.

	<Auditor>
	<!--
		<Privileges>
			<User>opendnssec</User>
			<Group>opendnssec</Group>
		</Privileges>
	-->

		<WorkingDirectory>/var/opendnssec/tmp</WorkingDirectory>
	</Auditor>

Delimited by the <Auditor> .. </Auditor> tags, the components are:

<!Privileges> the Auditor can drop its privileges if specified.

<WorkingDirectory> defines the location in which the Auditor will create temporary files.

</Configuration>

As there are no more elements, the </Configuration> tag closes the file.


kasp.xml – found by default in /etc/opendnssec – is the file that defines policies used to sign zones. (KASP stands for “Key and Signature Policy.) Each policy comprises a series of parameters that define the way the zone is signed. The hierarchical nature of XML allows the grouping of parameters into logical blocks.

The remainder of this article explains the parameters by referring to the example kasp.xml file supplied with the OpenDNSSEC distribution. Segments of the file are shown in shaded blocks – the explanation of the contents of each block follows it.

All date/time durations are specified as defined by  ISO 8601.

Preamble

<?xml version="1.0" encoding="UTF-8"?>

<!-- $Id: kasp.xml.in 1154 2009-06-24 13:02:25Z jakob $ -->

Each XML file starts with a standard element “<?xml…”. As with any XML file, comments are included between the delimiters “<!–” and “–>”.

Policy Description

<KASP>

The enclosing element of the XML file is the element <KASP> which, with the closing element </KASP>, brackets one or more policies.

	<Policy name="default">

Each policy is included in the <Policy>…</Policy> elements. Each policy has a “name” attribute giving the name of the policy. The name is used to link a policy and the zones signed using it; each policy must have a unique name.

The policy named “default” is special, as it is associated with all zones that do not have a policy explicitly associated with them.

		<Description>A default policy that will amaze you and your friends</Description>

A policy can have a description associated with it. Unlike XML comments, the description can be understood by programs and may be used to document the policy, e.g. a future GUI may display a list of policies along with their description and ask you to select one for editing.

Signatures

The next section of the file is the Signatures section, which lists the parameters for the signatures created using the policy.

		<Signatures>
			<Resign>PT2H</Resign>
			<Refresh>P3D</Refresh>
			<Validity>
					<Default>P7D</Default>
					<Denial>P7D</Denial>
			</Validity>
			<Jitter>PT12H</Jitter>
			<InceptionOffset>PT300S</InceptionOffset>
		</Signatures>

Here:

<Resign> is the re-sign interval, which is the interval between runs of the Signer Engine.

<Refresh> is the refresh interval, detailing when a signature should be refreshed. As signatures are typically valid for much longer than the interval between runs of the signer, there is no need to re-generate the signatures each time the signer is run if there is no change to the data being signed. The signature will be refreshed when the time until the signature expiration is closer than the refresh interval.

<Validity> groups two elements of information related to how long the signatures are valid for – <Default> is the validity interval for all RRSIG records except those related to NSEC or NSEC3 records. In this case, the validity period is given by the value in the <Denial> element.

<Jitter> is the value added to or extracted from the expiration time of signatures to ensure that not all signatures expire at the same time. The actual value of the <Jitter> element is the -j + r %2j, where j is the jitter value and r a random duration, uniformly ranging between -j and j, is added to signature validity period to get the signature expiration time.

<InceptionOffset> is a duration subtracted from the time at which a record is signed to give the start time of the record. This is required to allow for clock skew between the signing system and the system on which the signature is checked. Without it, the possibility exists that the checking system could retrieve a signature whose start time is later than the current time.

The relationship between these elements is shown below.

Authenticated Denial of Existence
Authenticated denial of existence – proving that domain names do not exist in the zone – is handled by the <Denial> section, as shown below:

		<Denial>
			<NSEC3>
				<OptOut/>
				<Resalt>P100D</Resalt>
				<Hash>
					<Algorithm>1</Algorithm>
					<Iterations>5</Iterations>
					<Salt length="8"/>
				</Hash>
			</NSEC3>
		</Denial>

<Denial> includes one element, either <NSEC3> (as shown above) or <NSEC>.

NSEC3
<NSEC3> tells the signer to implement NSEC3 scheme for authenticated denial of existence (described in  RFC 5155). The elements are:

<OptOut/> – if present, enable “opt out”. This is an optimisation that means that NSEC3 records are only created for authoritative data or for secure delegations; insecure delegations have no NSEC3 records. For zones where a majority of the entries are delegations that are not signed – typically TLDs during the take-up phase of DNSSEC – this reduces the number of DNSSEC records in the zone.

<Resalt> is the interval between generating new salt values for the hashing algorithm.

<Algorithm>, <Iterations> and <Salt> are parameters to the hash algorithm, described in  RFC 5155.

NSEC
Should, instead, NSEC be used as the authenticated denial of existence scheme, the <Denial> element will contain the single element <NSEC/> – there are no other parameters.

Key Information
Parameters relating to keys can be found in the <Keys> section.

		<Keys>

Common Parameters
The section starts with a number of parameters relating to both zone-signing keys (ZSK) and key-signing keys (KSK):

			<TTL>PT3600S</TTL>
			<RetireSafety>PT3600S</RetireSafety>
                        <PublishSafety>PT3600S</PublishSafety>
			<ShareKeys/>
			<Purge>P14D</Purge>

<TTL> is the time-to-live value for the DNSKEY resource records.

<PublishSafety> and <RetireSafety> are the publish and retire safety margins for the keys. These intervals are safety margins added to calculated timing values to ensure that keys are published and retired without there being a chance of signatures created with the keys being considered invalid.

If multiple zones are associated with a policy, the presence of <ShareKeys/> indicates that a key can be shared between zones. E.g. if you have 10 zones then you will only use one set of keys instead of 10 sets. This will same space in your HSM. If this tag is absent, keys are not shared between zones.

If <Purge> is present, keys marked as dead will be automatically purged from the database after this interval.

Key-Signing Keys

Parameters for key-signing keys are held in the <KSK> section:

			<KSK>
				<Algorithm length="2048">7</Algorithm>
				<Lifetime>P1Y</Lifetime>
				<Repository>softHSM</Repository>
				<Standby>1</Standby>
				<ManualRollover/>
			</KSK>

<Algorithm> determines the algorithm used for the key (the numbers reserved for each algorithm can be found in the appropriate  IANA registry).

<Lifetime> determines how long the key is used for before it is rolled.

<Repository> determines the location of the keys. Keys are stored in “repositories” (currently, only hardware security modules (HSMs) or devices conforming to the PKCS#11 interface), which are defined in the  conf.xml. In the example above, the key is stored in softHSM – the example configuration file distributed with OpenDNSSEC defines this as being the software emulation of an HSM distributed as part of OpenDNSSEC.

<Standby> determines the number of standby keys held in the zone. These keys allow the currently active key to be immediately retired should it be compromised, so enhancing the security of the system. (Without an standby key, additional time is required to allow information about the new key to reach validator caches – see  http://tools.ietf.org/html/draft-morris-dnsop-dnssec-key-timing for timing details.)

<ManualRollover/> is an optional tag. This tag indicate that the key rollover will only be initiated on the command by the operator. There is still a second step for the KSK, where the key needs to be published to the parent before the rollover is completed. Read more in the chapter “Running OpenDNSSEC”. The ZSK rollover will although be fully automatic if this tag is not present.

Zone-Signing Keys

Parameters for zone-signing keys are held in the <ZSK> section, and have the same meaning as for the KSK:

			<ZSK>
				<Algorithm length="1024">7</Algorithm>
				<Lifetime>P14D</Lifetime>
				<Repository>softHSM</Repository>
				<Standby>1</Standby>
			</ZSK>

The ZSK information completes the contents of the <Keys> section.

		</Keys>

Zone Information

General information concerning the zones can be found in the <Zone> section:

		<Zone>
			<PropagationDelay>PT9999S</PropagationDelay>
			<SOA>
				<TTL>PT3600S</TTL>
				<Minimum>PT3600S</Minimum>
				<Serial>unixtime</Serial>
			</SOA>
		</Zone>

<PropagationDelay> is the amount of time needed for information changes at the master server for the zone to work its way through to all the secondary nameservers.

The <SOA> element gives values of parameters for the SOA record in the signed zone. N.B. These values will override values set for the SOA record in the input zone file. The values are:

<TTL> – TTL of the SOA record.

<Minimum> – value for the SOA’s “minimum” parameter.

<Serial> – the format of the serial number in the signed zone. This is one of:

  • counter – use an increasing counter (but use the serial from the unsigned zone if possible)
  • datecounter – use increasing counter in YYYYMMDDxx format (xx is incremented within each day)
  • unixtime – the serial number is set to the “Unix time” (seconds since 00:00 on 1 January 1970 (UTC)) at which the signer is run.
  • keep – keep the serial from the unsigned zone (do not resign unless it has been incremented)

Parent Zone Information

If a DNSSEC zone is in a chain of trust, digest information about the KSKs used in the zone will be stored in DS records in the parent zone. To properly roll keys, timing information about the parent zone must be configured in the <Parent> section:

		<Parent>
			<PropagationDelay>PT9999S</PropagationDelay>
			<DS>
				<TTL>PT3600S</TTL>
			</DS>
			<SOA>
				<TTL>PT3600S</TTL>
				<Minimum>PT3600S</Minimum>
			</SOA>
		</Parent>

<PropagationDelay> is the interval between the time a new KSK is published in the zone and the time that the DS record appears in the parent zone.

The <DS> tag holds information about the DS record in the parent. It contains a single element, <TTL>, which should be set to the TTL of the DS record in the parent zone.

<SOA> gives information about parameters of the parent’s SOA record, used by KASP in its calculations. As before, <TTL> is the TTL of the SOA record and <Minimum> is the value of the “minimum” parameter.

Auditing

The zone will be audited before it is written to the signed directory, if the following tag is included. If you are signing a large number of zones and have a high work load on your server, the memory resources might get exhausted because each instance of the auditor has its own Ruby VM.

		<Audit />

If you are signing a very large zone (more than half a million records, for example), then you may wish to use the Partial Auditor. This checks a sample of the zone (rather than every RRSet cryptographic signature), and performs many of the same checks as the full auditor (including key lifetime tracking). To enable this, replace the above Audit tag with :

		<Audit>
			<Partial />
		</Audit>

This is the last section of the policy specification, so the next element is the policy closing tag:

	</Policy>

If there are any additional policies, they could be entered here, starting with <Policy> and ending with </Policy>. However, in this case there are no additional policies, so the file is ended by closing the <KASP> tag:

</KASP>

The list of zones that OpenDNSSEC will sign is held in the zone list file, /etc/opendnssec/zonelist.xml. As well as listing the zones, it also specifies the policy used to sign the zones.

The remainder of this section explains the parameters of the zone list by referring to the example zonelist.xml file supplied with the OpenDNSSEC distribution. Segments of the file are shown in shaded blocks – the explanation of the contents of each block follows it.

Preamble

<?xml version="1.0" encoding="UTF-8"?>

<!-- $Id: zonelist.xml.in 1147 2009-06-24 12:18:17Z jakob $ -->

Each XML file starts with a standard element “<?xml…”. As with any XML file, comments are included between the delimiters “<!–” and “–>”.

Zone List

<ZoneList>

The enclosing element of the XML file is the element <ZoneList> which, with the closing element </ZoneList>, brackets the list of zones.

Zones
Each zone is defined by a <Zone> element:

	<Zone name="example.com">

The mandatory attribute “name” identifies the zone. Each zone within the zone list must have a unique name.

Policy

		<Policy>default</Policy>

The first element of the <Zone> tag is <Policy>, which identifies the policy used to sign the file. Policies are defined in the  kasp.xml file, and the name in this element must be that of one of the defined policies.

Configuration
Information from the Enforcer to the Signer Engine is passed via a special signer configuration file, the name of which is given by the <SignerConfiguration> section of the zone definition:

		<SignerConfiguration>/var/opendnssec/signconf/example.com.xml</SignerConfiguration>

(Note that this file is a temporary file that passed between OpenDNSSEC components and is not intended to be edited by users.)

Adapters

The next part of the zone element specifies from where OpenDNSSEC gets the zone data and to where the signed data is put.

		<Adapters>
			<Input>
				<File>/var/opendnssec/unsigned/example.com</File>
			</Input>
			<Output>
				<File>/var/opendnssec/signed/example.com</File>
			</Output>
		</Adapters>

The <Adapters> element comprises an <Input> and <Output> element which (fairly obviously) identify the input source and output sink of the data.

Within each element is a tag defining the type of data source/sink and its parameters. At the moment, only the <File> element is defined, which takes as its only data the name of the input unsigned or output signed zone file.

In the future, it is planned to offer the ability to accept and output data in the form of AXFRs and IXFRs.

	</Zone>

The </Zone> tag closes the definition of the zone. As indicated above, one or more zones can be defined in this file.

</ZoneList>

The </ZoneList> element closes the file.

For a small number of zones, the zone list file can be easily edited by hand. Where the number of zones is large – for example, ISPs serving thousands of customers – the intention is that the file be generated by the zone manager’s systems using e.g. the ods-ksmutil zone add command.

As can be seen in the example above, a number of elements that specify file names (<SignerConfiguration>, <Adapter>/<Input> and <Adapter>/<Output>) include the zone name in the name of the file. Where there are multiple zones, this is strongly recommended as a way of avoiding confusion.


OpenDNSSEC can sign zonefiles on disk, but can also sign zones received from transfer (AXFR). If you configure a zone fetcher configuration -  XML RelaxNG compact, the Signer Engine will kick off the zone fetcher that will listen to NOTIFY messages from the parent and store AXFR messages on disk. The messages will be stored as the input file adapter plus an additional “.axfr” extension. If the transfer was succesful, the zone fetcher kicks the Signer Engine so that the incoming zone will be signed.

The zone fetcher configuration filename must be in  conf.xml. Use the ZoneFetchFile element for that.

NotifyListen:
This defines which interface and port the must bind to listen NOTIFY messages on. You can specify an IPv4/IPv6 address plus port number.

Default:
This has the default values for master servers and tsig credentials.

TSIG:
This configures your TSIG credentials. Name, Algorithm and Secret are required.

RequestTransfer:
This configures your master servers to contact. You can specify multiple IPv4/IPv6 addresses. Unfortunately, only the first encountered port number will be used.

The zone fetcher can run a single time, but the Signer Engine will start it as a daemon. As a daemon, it will accept NOTIFY messages for which it has master servers configured (with RequestTransfer). NOTIFY also does not make use of the TSIG credentials.

You can specify the listening interface and port with NotifyListen. By default, the zone fetcher will listen on any interface, port 53.

To listen on a specific address, use:

    <NotifyListen>
        <IPv4>192.0.2.100</IPv4><Port>53</Port>
    </NotifyListen>

Upon a valid NOTIFY, the zone fetcher sends to one of the master servers. If configured, it adds the TSIG RR. A succesful AXFR response will be stored on disk.

The Signer Engine will know if it have to check for an AXFR on disk before signing a new unsigned zone. Thus, the Signer Engine needs to be kicked with ‘update <zone>’ if a AXFR was received. Luckily, the zone fetcher will do that for you.


OpenDNSSEC can handle various formatting of the zone file, including different directives and Resource Records (RRs).

The zone file can be formatted in many ways including multi-lined RR, comments, etc.

$ORIGIN example.com. What origin to use.
$TTL 1h3m The default TTL to use. Treated as seconds, if no suffix is used: s, m, h, d, w, S, M, H, D, W
$INCLUDE <path> Include a file from a given path

OpenDNSSEC support all of the RR specified by  IANA, with some exceptions.

Not supported: ATMA, APL, EID, NIMLOC, HIP, SINK, NINFO, RKEY, TA
Obsoleted: MD, MF, WKS, GPOS, SIG, KEY, NXT, A6, and NSAP-PTR
Not allowed in master file: NULL, OPT, TKEY, TSIG, IXFR, AXFR, MAILB, MAILA, *

But OpenDNSSEC do handle unknown RR types in accordance with  RFC3597. E.g:

example.com.   IN          TYPE1               \# 4 0A000001

All directories are prepared by the build script and are set to be owned by root, so all commands in the default configuration must also be run by root. To change this, alter the configuration or privileges on the files and directories.

Before you run the system for the first time you must import your policy and zone list into the database using the following command:

 ods-ksmutil setup

After running this the first time, you will be ready to run OpenDNSSEC with an empty set of zones. On the other hand, if this command is run on an existing database, then will all meta-information about the zones be lost. The keys would then still exist in HSMs, so you should not forget to clean them up.

OpenDNSSEC consist of two daemons, ods-signerd and ods-enforcerd. To start and stop them use the following commands:

 ods-control start

A proper-looking response to this commands is:

Starting signer engine...
connecting to /var/run/opendnssec/engine.sock
OpenDNSSEC signer engine version 1.0.0rc3
Zone list updated: 0 removed, 16 added, 0 updated
running as pid 16611
Starting enforcer...
OpenDNSSEC ods-enforcerd started (version 1.0.0rc1), pid 16613

At any time, you can stop OpenDNSSEC’s daemons orderly with:

 ods-control stop

After this, your logs should contain messages like:

ods-signerd: Received command: 'stop'
ods-enforcerd: all done! hsm_close result: 0

Zones can be added and removed at will. If the optional parameters are not given, then it will default to the policy default and the /var/opendnssec/ subdirectories.

 ods-ksmutil zone add --zone example.com [--policy <policy> --signerconf <signerconf.xml> --input <input> --output <output>]
 ods-ksmutil zone delete --zone example.com

This command will report positively with a message like:

zonelist filename set to /etc/opendnssec/zonelist.xml.
SQLite database set to: /var/opendnssec/kasp.db
Imported zone: example.com

Alternatively, you could manually edit the zonelist.xml and then give the command:

 ods-ksmutil update zonelist

After zones are added, they will show up in your logs as follows:

ods-enforcerd: Zone example.com found.
ods-enforcerd: Policy for example.com set to default.
ods-enforcerd: Config will be output to /var/opendnssec/signconf/example.com.xml.

If you opened the latter file, you would find the settings that were applied to the zone at the time this file was added.

You can configure the system to only make keys active once they have been backed up. This is done by editing the  conf.xml file. The user must do backups and then notify OpenDNSSEC about this, so that the key rollover process can continue. The keys must be backed up regulary, because OpenDNSSEC is generating new keys prior to a rollover.

For all of the repositories:

 ods-ksmutil backup done

or a single repository:

 ods-ksmutil backup done --repository <repository>

Caution: You want to ensure that all the keys are backed up, and that no new ones have been created just after you started the backup procedure. Therefore, a complete backup procedure would be

 ods-control ksm stop
 # backup the HSM
 ods-ksmutil backup done
 ods-control ksm start

Note: Backups are demanded by way of a repository option in conf.xml:

<RequireBackup/>

If you decide you want to change this facility, you should edit conf.xml accordingly, and run:

ods-ksmutil update conf

It will report something along the lines of:

RequireBackup set.

You need to publish your key to the parent or to interested parties when you are signing the zone for the first time. The follwing command will extract the trust anchors:

 ods-ksmutil key export --zone example.com
 ods-ksmutil key export --zone example.com --ds

What you get in return is the DNSKEY or DS in BIND-format.

To complete KSK rollovers, you need to publish your KSKs before the system makes them active. You must thus add the extra keystate option to the command.

 ods-ksmutil key export --zone --keystate ready example.com
 ods-ksmutil key export --zone --keystate ready example.com --ds

More info on the KSK rollover can be found below.

The rollovers are done automatically according to the policy of the zone. But a manual keyrollover may be desired in cases of emergency, such as having lost a private key. This can be done using the ods-ksmutil command like this:

 ods-ksmutil key rollover --zone example.com --keytype KSK

This will roll the KSK key in a timely manner following the policy used for the zone example.com. If you want to roll the Zone Signing Key use –keytype ZSK instead.

You can also roll all the keys for zones which have a certain policy. This can be useful if you want to move all keys from one key store to another.

 ods-ksmutil key rollover --policy default --keytype KSK

Unlike ZSKs, a KSK rollover requires a second step involving manual intervention. This intervention is a multi-stage process. First, the DNSKEY record for the new key is added to the zone. Then, after a suitable interval, the new DS record is submitted to the parent; at this point the old DS record can be removed from the parent.

The stages are:

1. Extract the DNSKEY record for both the active and ready keys and publish them in the parent zone. (The new records replace any existing records for the zone being signed.) When it is time for this to happen a message with log-level “info” will be sent to syslog looking something like:

Mar 16 11:39:05 sion ods-enforcerd: DS Record set has changed, the current set looks like:
Mar 16 11:39:05 sion ods-enforcerd: example.com. 3600 IN DNSKEY 257 3 7 AwEAAd4QRJHvB9t/yLJgtc24im3LGZibKJxMCPq4FOJ0gJ9/ZSaVUcAmE5QBAJU4ldFDghatZjh0XzHDpSbD5gA6zpNH+X5e84AA/peU+9FFZjmH9klXhZ86XqufqE/DsR438LLu9+u9zkHi0jKV5kItCLX3PmXJO9UmxNcCqSUgfhPtSkVPw+AYgYiL75vkt4RxTWwfPhqz1MUH9Dq601juoE2Kx0iypMndkJfp/Jkvfl/0nRqFLWnarYoYG5hNWNYhRJzpwtjd1pn2BjyNa+iLZFtZqdyh079y/GsFOoPVFvO1HQylN46QbekrfPL5ukiP+u4jKuWVnQfo/WNVIH9K8= ;{id = 18753 (ksk), size = 2048b}
Mar 16 11:39:05 sion ods-enforcerd: example.com. 3600 IN DNSKEY 257 3 7 AwEAAbcTSmphJUMKvegvDgqGspRM8IHlKZqoU5pkPaTtRLkioxGyZ5iIh4bNnvqmx1zWIttuJ6erGUMOatMm3SXxiTr9OLaRPr86KVpo6mzejTqFicGxSp3KsrbUvyIs/V84Ry7XZBKVKVjgppjmqeS8mRtXM4UynwTEJk0hKQfCcmkH0Q/fhZibwBVG+OcBfvTdsQbp8LZN4oVqn/vzhnuxFkE8biTr19jmKTdtgkhp524ML59v7prg7F/+Lb2OJLc8Gg6pastUeqXc/Iv2CdVyOvMWRW39VCzyLbKpmyqB8Hc4Kn1pT5Idqc3/N3qBvXVe3HyyiZbjHGxOT6RZNNT8= ;{id = 51994 (ksk), size = 2048b}
Mar 16 11:39:05 sion ods-enforcerd: Once the new DS records are seen in DNS please issue the ds-seen command for zone example.com with the following cka_ids, 87f1385b114f9f9b299e6b551d728bfb, 04260cd6eac67280cd2dea94c6e38cb7

2. When the records indicated have been seen in DNS then this can be communicated to OpenDNSSEC with the ds-seen command as indicated:

 ods-ksmutil key ds-seen --zone example.com --cka_id 87f1385b114f9f9b299e6b551d728bfb
 ods-ksmutil key ds-seen --zone example.com --cka_id 04260cd6eac67280cd2dea94c6e38cb7

3. If the DS records were not swapped, i.e. the old DS was left in the parent when the new one was added, then the –no-retire flag can be added to the ds-seen command. Then, at some later time, the old key can be retired with the command:

 ods-ksmutil key ksk-retire --zone example.com ---cka_id 87f1385b114f9f9b299e6b551d728bfb
or
 ods-ksmutil key ksk-retire --zone example.com

The former command will retire the specific key (provided the key is active, and the action will not leave the zone without any active keys). The latter command will retire the oldest active key on the zone, again provided it will not leave the zone without any active keys.

Some users want to have more control over their key rollovers and roll keys on exact dates, for example the first day of each month. To do this you need to specify that you want manual key rollovers in the kasp.xml configuration. Add the <ManualRollover/> tag to the type and key you want to roll manually.

When this is done you can add the rollover commands to a cron job, with a command like this:

 ods-ksmutil key rollover --zone example.com --keytype ZSK

(The need to manually time intervals is a limitation of version 1.0 of the software. Future versions of OpenDNSSEC will prompt with reminders at the appropriate times as well as offering alternative KSK rollover methods.)

When you make changes to a policy or add a new policy in kasp.xml you must update the changes to the database.

 ods-ksmutil update kasp

When you update the content of an unsigned zone you can schedule it for immediate resigning using the ods-signer command like this:

 ods-signer sign example.com

Currently all logging is handled by syslog. Other logging methods may come later.

There is a lot of output from the daemons of which a lot of things right now are for debugging. We might reduce the amount of logging for later versions of OpenDNSSEC.


Is a wrapper around the commands below.

 usage: ods-control ksm|hsm|signer|start|stop

The first three options pipe commands to ods-ksmutil, ods-hsmutil, and ods-signer.
The last two options start and stop the two daemons of OpenDNSSEC, ods-enforcerd and ods-signerd.

You need a way to interact to the KASP Enforcer, for example to add and remove zones that are handled by OpenDNSSEC. The ods-ksmutil utility provides a number of commands to make this easier, all commands are invoked on the unix command line.

You must run the setup option before you ever run any sub-system in OpenDNSSEC. This reads the configuration kasp.xml and imports these settings into the KASP Enforcer database. The setup command deletes the current content of the database! (Including information on keys; such that existing keys will become unusable and new keys will need to be generated.)

If you make any changes to kasp.xml these changes must be imported into the database. Use the update command to do this without losing any other data.

To add a zone to be handled by OpenDNSSEC, use the zone add command. This command needs a parameter to specify the zone, and optional parameters for which policy to use and which paths to use for input and output. An example of use:

 ods-ksmutil zone add -z example.com -p default -i /var/example.com -o /var/example.com.signed

The command zone delete is simpler and needs no further parameters but the name of the zone.

A complete list of commands can be found by running:

 ods-ksmutil -h

or they are shown here  http://trac.opendnssec.org/wiki/Signer/Using/Commands/ksmutil

The ods-signer provides a Command Line Interface to the ods-signerd. There are a number of commands you give to ods-signer. If you start the CLI without any command line parameters you enter a shell where you can issue commands:

 ods-signer
 connecting to /var/run/opendnssec/engine.sock
 cmd> help
  Commands:
 zones           show the currently known zones
 sign <zone>     schedule zone for immediate (re-)signing
 clear <zone>    delete the internal storage of the given
                 zone name. All signatures will be
                 regenerated on the next re-sign.
 queue           show the current task queue
 flush           execute all scheduled tasks immediately
 update <zone>   check for changed zone conf xml file, if
                 <zone> is not given all zones are checked
 stop            stop the engine
 verbosity <nr>  set verbosity (notimpl)

The same commands can be passed as command line arguments in your unix shell.

In short, the sign commands tell the signer to immediately queue up a zone for re-signing. This is useful if you have made changes to your zonefile and you immediately want it signed for further distribution to your nameservers. clear tells the signer to renew all signatures on the given zone. The queue command lists all the upcoming tasks currently in the queue.

The ods-hsmutil utility is designed to interact directly with your HSM and can be used to manually list, create or delete keys. It can also be used to perform a set of basics HSM tests. Be careful before create or deleting keys using ods-hsmutil, as the changes are not synced with the KASP Enforcer.

The Auditor (ods-auditor) can do an audit of the zones in the system to see if the signer complies to what the policy mandates. It is run automatically (unless disabled) after each resigning of a zone and will stop the signed zone from being distributed if it finds any issues. Any errors found by the ods-auditor will be logged to the configured syslog utility. This should be checked for debug if you have issues.

You can also run the Auditor yourself, to get feedback on the current status, to loop through all zones run:

  ods-auditor

or, to audit just one zone, run:

  ods-auditor -z <zone>

It is possible to override the audit type specified in the kasp.xml Policy for the zone. To run a full audit, use the –full flag, and use –partial to force a partial audit of the zone. i If you are using the partial auditor to audit your very large zone, you may wish to run an occasional off-line full audit. To do this, take a copy of your signed and unsigned zone files, and run :

  ods-auditor -z <zone> --full --signed <path/to/signed/file> --unsigned <path/to/unsigned/file>

The tool ods-hsmspeed does performance testing on your HSM. This is also useful to find out at what speed you can get from SoftHSM on your CPU.

The hsmbully tool may be used to test your HSM for compliance with PKCS#11. This tool is not part of OpenDNSSEC, but can be found in the SVN repository:

 svn co http://trac.opendnssec.org/browser/trunk/hsmbully hsmbully

You can also run the two OpenDNSSEC daemons ods-signerd and ods-enforcerd from the command line, they are installed into the sbin directory.

This is the component that performs all of the signing. It first reads zonelist.xml and then goes through all zones to sign them if needed. Start the daemon by running:

 ods-signerd

This daemon does not need any command line arguments to run.

The Enforcer daemon creates keys if needed (and configured to); it also maintains the states of the keys according to the appropriate policy. As the states of keys change, it communicates these changes to the signer via the configuration files that the signer uses when signing the zones. To run, call:

 ods-enforcerd

This tool is provided to check that the configuration files (conf.xml and kasp.xml) are semantically sane and contain no inconsistencies. It is advisable to use this tool to check your configuration before starting to use OpenDNSSEC.

ods-kaspcheck -h
Usage: ods-kaspcheck [options]
Specific options:
    -c, --conf [PATH_TO_CONF_FILE]   Path to OpenDNSSEC configuration file
                                       (defaults to the default conf.xml file)
    -k, --kasp [PATH_TO_KASP_FILE]   Path to KASP policy file
                                       (defaults to the path given in the configuration file)
Common options:
    -h, -?, --help                   Show this message

It is possible to migrate a DNSSEC signed zone over to OpenDNSSEC. How to migrate your DNSSEC signed zone over to OpenDNSSEC really depends on how your current solution looks like.

The zone data is no problem. Just place a copy of the unsigned zone in the directory for unsigned zones. But the trick is to maintain the private and public keys.

There are three possible solutions:

  • Export the keys
  • Prepublish DNSKEY record
  • Start fresh

One solution is to move the key pairs and make them accessible by OpenDNSSEC. The goal is to have the key pairs available to the system using PKCS#11.

The key pairs can e.g. be stored:

  • on disc (e.g. BIND .private-key format)
  • on a smartcard with no PKCS#11 interface
  • in an HSM

On disc

When the key pairs are stored on disc, it means that you have access to files containing the key pairs. The key pairs can be imported into your new HSM using the PKCS#11 API or any tool available from your HSM vendor.

The BIND .private-key file can be convert into the PKCS#8 file format using the tool available with SoftHSM. If you have another file format, then OpenSSL probably can help you to convert it into the PKCS#8 file format.

 softhsm-keyconv --topkcs8 --in Kexample.com.+005+42952.private --out key.pem
  • –topkcs8, To indicate that you want to convert from BIND .private-key format to PKCS#8.
  • –in <path>, The path to the BIND .private-key file.
  • –out <path>, A path to the temporary PKCS#8 file.

The PKCS#8 file can then be imported into the SoftHSM token (if you are using SoftHSM as your HSM).

 softhsm --import key.pem --slot 1 --pin 123456 --label A2 --id A2
  • –import <path>, The path to the PKCS#8 file that you want to import. This should point to the temporary file that you created in the previous step.
  • –slot <number>, The key should be imported to a token. Indicate which slot it is connected to.
  • –pin <PIN>, Provide the PIN so that we can login to the token.
  • –label <text>, Choose an arbitrary text string. Not used by OpenDNSSEC.
  • –id <hex>, Choose an ID of the new key pair. The ID is in hexadecimal with a variable length. It must not collide with an existing key pair.

On a smartcard with no PKCS#11 interface

Just connect a smartcard reader to your system and insert your smartcard. Then use opensc and pcscd to give it a PKCS#11 interface. Remember to protect the location where you have your smartcard reader, since the smartcard needs to be online.

On an HSM

You can either move the HSM to the new server and install it there. Or some vendors may have some functionality to export/transfer the key pairs.

The final step

Once you have the key pairs available on the system via PKCS#11, then you must add them to OpenDNSSEC. Give this command before you start OpenDNSSEC. Also make sure that the zone is properly configured with OpenDNSSEC.

 ods-ksmutil key import --cka_id <CKA_ID> --repository <repository> --zone <zone> --bits <size> --algorithm <algorithm> --keystate <state> --keytype <type> --time <time>
  • –cka_id <CKA_ID>, Each key object in the HSM has an ID, the CKA_ID attribute. The private and public key object must have the same ID inorder for OpenDNSESC to find them. The CKA_ID of the key pair to import is indicated, in hexadecimal, by using this option. E.g. A2
  • –repository <repository>, The name of the repository, from conf.xml. E.g. softHSM1
  • –zone <zone>, The name of the zone. E.g. example.com
  • –bits <size>, The key length, E.g. 1024
  • –algorithm <algorithm>, The algorithm. E.g. 5 or 7
  • –keystate <state>, The key state. E.g. active or ready
  • –keytype <type>, The key type. KSK or ZSK
  • –time <time>, The time stamp when the key entered the given state. So that OpenDNSSEC know when to change the state. E.g. 200910301000
  • –retire <retire>, Optional. If you set the state to active, then you may set the time when the key should be retired. E.g. 201001010000. Otherwise will OpenDNSSEC use the key lifetime from the KASP.

The difference between active and ready is:

  • active: Will make the key active, thus used for signing. If there already is an active key, then you will have two of them. If this is not desired, then make sure to give this command right after setup and before you start the system.
  • ready: The key will only be published in the zone. It will become active in a future rollover, if the key parameters match the policy.

TODO: Need text for this part.

A third solution is to start fresh. Remove any DS records from the parent zone. Stop signing your zone when the DS records are removed from the DNS caches. It is safe to remove the public keys from your zone when the signatures are not present in any DNS caches. Then transfer the zone over to OpenDNSSEC. And let OpenDNSSEC start signing it again. Your zone will not be secured by DNSSEC during this transfer.


There are a number of common issues that are straightforward to diagnose and fix… If OpenDNSSEC is not behaving as expected then the first place to look is in the logs. Where these will be depends on your system and your configuration.

The following are log messages which you may see, and what to do about them (if anything).

ods-enforcerd: ERROR: Trying to make non-backed up ZSK active when RequireBackup flag is set
This is not an error as such. It means that in conf.xml you have indicated that keys should not be used unless they are backed up. However, the enforcer has determined that if it continues then a non backed up key will be made active.
The solution Take a backup of your keys (how this is done will depend on your key storage).
Once this has been done then run ods-ksmutil backup done to mark all keys as having been backed up.

ods-enforcerd: WARNING: Making non-backed up KSK active, PLEASE make sure that you know the potential problems of using keys which are not recoverable
This is the same as above, but without RequireBackup being set in conf.xml

ods-enforcerd: WARNING: key rollover not completed as there are no keys in the ready state: ods-enforcerd will try again when it runs next
This is seen when a rollover is happening but there is no replacement key ready (because one has not been published for long enough). It indicates that the rollover will be delayed until the replacement key is ready, the time that this will happen depends on the policy.

ods-enforcerd: Could not call signer engine
If the enforcer makes a change to a zones signer configuration (say it adds a new key) it calls the signer to get it to resign that zone. This message indicates that the signer is not running, although it has been seen on a system where everything is working fine. (See KNOWN_ISSUES.)

ods-enforcerd: Not enough keys to satisfy zsk policy for zone
or ods-enforcerd: Not enough keys to satisfy ksk policy for zone

One of these messages will be seen if the enforcer does not have enough unallocated keys to provide for the zone specified. If the ManualKeyGeneration tag is set in conf.xml then you will need to create new keys usingods-ksmutil key generate, otherwise new keys will be created when the enforcer runs next. (Don’t forget to backup any new keys.)

ods-enforcerd: Rollover of KSK expected at <DATE TIME> for <ZONE>
This is not an error, but a notification of an upcoming (scheduled) rollover. This will appear in your logs at a time prior to the rollover as configured in conf.xml (the Enforcer/RolloverNotification tag).

ods-enforcerd: WARNING: KSK Retirement reached; please submit the new DS for <ZONE> and use ods-ksmutil key ksk-roll to roll the key.
Rolling a KSK requires the DS record of the replacement key to be published in the parent of the zone. This message indicates that your KSK has reached the end of its life (as specified by your policy), and that it is time to submit the DS record to the parent.

ods-enforcerd: Error: database in config file <path_to_conf.xml> does not match libksm
This indicates that either you have libksm built for sqlite, but have specified a MySQL database in conf.xml, or vice versa.
The solution is to either rebuild libksm or to change conf.xml

ods-enforcerd: Error reading config
This usually means that conf.xml is either absent, not readable by the user, or badly formed. There should be a line above this one which gives a more specific error message.

ods-enforcerd: Error getting db lock
When using sqlite any process using the database tries to get an exclusive write lock on a file in the same directory as the kasp.db. If this directory is not writeable by the user then this message will be seen, again a more specific error message should have been issued.

ods-enforcerd: Repository <NAME> is full, cannot create more <KSKs|ZSKs> for policy <POLICY>
In conf.xml a capacity can be specified for a repository. When this is reached then no more keys will be generated in that repository.
The solution is to either run ods-ksmutil key purge to remove dead keys, or to raise this capacity and run ods-ksmutil update conf to push this change into the database. If the repository is really at capacity, and purge does not free up any space, then a new repository will be needed.

ods-enforcerd: Repository <NAME> is nearly full, will create X <KSKs|ZSKs> for policy <POLICY> (reduced from Y)
Y keys were needed to satisfy the policy, but the repository only has room for X more. This warning might precede the error detailed above, and the solution is the same.

ods-enforcerd: NOTE: keys generated in repository <NAME> will not become active until they have been backed up
This is not an error, but a reminder that a backup needs to be done (as new keys have just been generated).

ods-enforcerd: Signconf not written for <ZONE>
Some error has happened and the enforcer will not overwrite the existing signconf file, so the old one will be left in place. There should be a more specific message indicating the root cause just prior to this line. (E.g.attempting to use a non backed up key.)

ods-enforcerd: There are no <KSKs|ZSKs> in the generate state; please use “ods-ksmutil key generate” to make some
ManualKeyGeneration has been set (in conf.xml) and the system has run out of keys.
The solution is to run the ods-ksmutil key generate command, back up the keys, and the system will recover when it runs next.

ods-signerd: Error: unable to open domain socket <socket-file-name>.

ods-signerd: Error: i/o error opening domain socket <socket-file-name>

ods-signerd: Unable to drop privileges to user <user>

ods-signerd: Unable to drop privileges to group <group>

ods-signerd: Unable to chown socket file <socket-file-name>

These messages will be in the logs if the signer engine daemon did not start up. All of them are provided with a specific message indicating the cause.

ods-signerd: Connection closed by peer
The ods-signer tool unexpectedly closed. Try the command again. If the error persists, please contact the OpenDNSSEC project group.

ods-signerd: error parsing zonelist xml file: <zonelist-file>
The zonelist.xml file contains errors. Either you edited it manually, or the Enforcer made an error. If you think the latter occurred, please contact us.

ods-signerd: Error updating zone configuration for <zone-name>
The signer configuration file contains errors. Either you edited it manually, or the Enforcer made an error. If you think the latter occurred, please contact us.

ods-signerd: Error handling signal <signal>
The signer engine was not able to stop or reload. Please try again.

ods-signerd: Error while signing: <reason>
Signing failed. Other messages prior to these should explain why.

ods-signerd: Error: unknown task <task>
This should not happen.

ods-signerd: Error running create_dnskey
The communication to the create_dnskey tool could not be opened. Should not happen.

ods-signerd: Error: could not find key <key-id>
This key is not in the repository.

ods-signerd: Error: Unable to find key <key-id>
We could not access the repository.

ods-signerd: Error: Unable to find key <key-id>
We could not access the repository.

ods-signerd: Error reading input zone
We were not able to read the input zone. Check if the zone file is at the correct location and if the permissions are correct.

ods-signerd: Error sorting zone
We were not able to sort the input zone. Check if the zone file does not contain any syntax errors.

ods-signerd: Sorting failed
The sorter tool failed. The log messages prior to these should indicate the cause and help fixing the issue.

ods-signerd: Preprocessing failed
The preprocessor tool failed. The log messages prior to these should indicate the cause and help fixing the issue.

ods-signerd: Error preprocessing zone
We were not able to sort the input zone. Check if the zone file does not contain any syntax errors.

ods-signerd: Error opening zone file
The internal file could not be read. The file might be corrupted. Try to run ods-signer clear <zone> to clear all internal files.

ods-signerd: Error reading serial file <reason>
The internal .serial file could not be read. The file might be corrupted. Try to run ods-signer clear <zone> to clear all internal files.

ods-signerd: No resource records in output
Somewhere down the process an error occurred. Check the internal files and see if they have content. If not, you can determine which tool failed. The logs should lead you to the cause. If that doesn’t help you, please contact us.

ods-signerd: Error running notification command
Notifying the name server failed. Is the command correct. Are the permissions correct?

ods-signerd: Cannot keep input serial <serial1>, output serial <serial2> is too large. Aborting operation

or

ods-signerd: Error: serial setting is set to ‘keep’, but input serial has not increased. Aborting sign operation for <zone>
You have configured to keep the serial from the input zone file, but it is not larger than the current output serial. You need to increase the input serial in order to get the new input zone file signed.

ods-signerd: Input file missing
The unsigned zone file is missing.

ods-signerd: could not stop zone fetcher: pid file does not exist: <zonefetcher-pid-file-name>
Did the zonefetcher already closed down? If it is still running, you might want to stop it manually with KILL -TERM.

ods-signerd: could not stop zone fetcher: no such process: <process-id>
The zone fetcher is either not running anymore, or the zonefethcer-pid-file-name is out of sync. Stop the zone fetcher manually, if necessary.

ods-signerd: socket close failed: <reason>
The daemon will shut down, but the socket file will continue to exist. No harm done, it will be overwritten upon the next start up.

ods-signerd: Engine already stopped?
It could be that the daemon is currently already shutting down.

Finally, note that it might take a while if you want to shut down the signer engine daemon. There might be a worker busy that will first finish his job. Especially if a worker is currently busy replacing signatures in a huge zone, this might take several minutes.


If you encounter anything strange in either the documentation, the code or in the commands you are using, feel free to post a message to the opendnssec-user mailing list. You can subscribe to it here:

http://lists.opendnssec.org/mailman/listinfo/opendnssec-user

If you have a bug report, please enter it into our trac-system:

http://trac.opendnssec.org/newticket

Be sure to include all the error messages you get, the versions of the other libraries you are using and what actions you did to trigger the error message.