$Id$

The signer engine and its tools are part of the OpenDNSSEC project.
For more information, visit http://www.opendnssec.org

CONTENTS:
    INTRODUCTION
    DEPENDENCIES
    INSTALLATION
    INTERACTION FROM THE COMMAND LINE
    RUNNING THE ENGINE
    RUNNING WITHOUT THE KASP
    DEBUGGING

-------------------------------------------------------------------
INTRODUCTION
-------------------------------------------------------------------

As part of the OpenDNSSEC project, the task of the signer engine is to
schedule signing operation on DNS zones. Taking input from the KASP, it
will automatically sign zones and keep their signatures up-to-date.

Until version 1.3, OpenDNSSEC could only handle file-to-file signing. 
With the Zonefetcher enabled, AXFR-to-file signing was possible. Version
1.4 and up can handle unsigned zones in file, AXFR and IXFR format, as well
as output signed zones as file, AXFR and IXFR. When a zone has changed,
the engine can run a specified command, for instance to signal an actual
DNS server that it should reload its zones (useful for file output).

The signer engine has a scheduler, including a set of workers to do zone
manipulation, and zone in- and output is handled by different types of
adapters. 

The signer is written in c is run as a daemon. When a zone needs to be
sorted or (re)signed, the workers will report for duty and perform the job.
It uses a worker/task-queue design, where the worker threads will suspend
until there is something to do. 

-------------------------------------------------------------------
DEPENDENCIES
-------------------------------------------------------------------

The signer depends on the ldns library:

	 http://www.NLnetLabs.nl/projects/ldns

and can only be used in conjuction with a PKCS#11 library (a software
version of which, softHSM, is supplied with the OpenDNSSEC).

-------------------------------------------------------------------
INSTALLATION
-------------------------------------------------------------------

The signer is installed as part of the OpenDNSSEC install. To build and
install the signer engine separately, the following steps are needed:

From the base directory <opendnssec>/signer

autoreconf --install
./configure
make
make install

The options provided with configure:

--with-ldns=<dir> The base directory (prefix) of your ldns installation,
                  if it isn't in your standard path.
--prefix=<dir>    Installation directory. All files will be installed
                  relative to this path, and default search paths will
                  be relative to the prefix. Defaults to /usr/local

The signer engine will be installed in
<prefix>/sbin

-------------------------------------------------------------------
INTERACTION FROM THE COMMAND LINE
-------------------------------------------------------------------

If the engine is running (see the next section on how to run
one manually), you can interact with it using the tool ods-signer.

If you give no arguments, it will connect to the engine and go to
interactive mode. Only the start command cannot be called in
interactive mode. The command 'help' shows a list of possible
commands:
$ ods-signer
cmd> help
 Commands:
zones           show the currently known zones
sign <zone>     schedule zone for immediate (re-)signing
sign --all      schedule all zones for immediate (re-)signing.
clear <zone>    delete the internal storage of this zone.
                All signatures will be regenerated on the next re-sign.
queue           show the current task queue.
flush           execute all scheduled tasks immediately.
update <zone>   update this zone signer configurations.
update [--all]  update zone list and all signer configurations.
start           start the engine.
reload          reload the engine.
running		test if the engine is running.
stop            stop the engine.
verbosity <nr>  set verbosity.

cmd> quit

You can also use these commands directly from your shell, by giving
them as arguments to ods-signer. If you do this, the client will
execute the command and quit.

-------------------------------------------------------------------
RUNNING THE ENGINE
-------------------------------------------------------------------

You can run the engine by calling <prefix>/sbin/ods-signer start

If everything is ok, you should see the following output:
$ ./ods-signer start
OpenDNSSEC signer engine version 1.4.0
$

The engine has daemonized itself and should be running. You can
check that it does by using ods-signer as specified in the
section INTERACTION FROM THE COMMAND LINE.

-------------------------------------------------------------------
RUNNING WITHOUT THE KASP
-------------------------------------------------------------------

If you want to test the engine on its own, or run it without using
the KASP module, you will need to perform the following steps.

Of course it has to be installed using the steps from section
INSTALLATION.

HSM
---
You will need to set up an HSM module. If you use SoftHSM, you will
need to make sure that a token is initialized, and that the correct
softhsm.conf file is set in the environment variable $SOFTHSM_CONF.

Some keys should be present in the token. If not, you can generate
them with the hsm-toolkit from OpenDNSSEC.


conf.xml
--------

You will need to either create or update the
<prefix>/etc/opendnssec/conf.xml file to your
settings; the <Repository> element should contain the name of the
token you have initialized in your HSM, the complete path of the
module library (e.g. <prefix>/lib/libsofthsm.so). Optionally you
can use a PIN value here too. If you do not specify it, the engine
will prompt for it.

If you run a nameserver, you will need to create a little script
that tells that server to reload its zones, and point to that
script with the element <NotifyCommand> below <Signer>.

The rest of the values can be left to their defaults.

The elements and their exact meanings are described here:
http://www.opendnssec.se/browser/trunk/conf/opendnssec/conf.rnc


zonelist.xml
------------

You can tell the engine what zones to sign with
<prefix>/etc/zonelist.xml
An example zone list file can be found at
http://www.opendnssec.se/browser/trunk/conf/opendnssec/zonelist.xml

The elements and their exact meanings are described here:
http://www.opendnssec.se/browser/trunk/conf/opendnssec/zonelist.rnc

This file will specify the specific zone configuration, and its
in- and output-files.


addns.xml
------------

If you use AXFR or IXFR as zone input/output, you can tell the engine
where and how to get the zones from the master servers with
<prefix>/etc/addns.xml
This can be configured on a per-zone basis in the zonelist.xml file.

An example zone list file can be found at
http://www.opendnssec.se/browser/trunk/conf/opendnssec/addns.xml

The elements and their exact meanings are described here:
http://www.opendnssec.se/browser/trunk/conf/opendnssec/addns.rnc

This file will specify the interface to listen NOTIFY messages on,
the master servers that are allowed to send NOTIFY messages and to
contact for zone transfers and optionally, the TSIG credentials.


zone file
---------

If you use files as input, you obviously will need to give the engine an
actual zone file to work on. You will have already specified the location of
this file in the zonelist.xml file above.


zone configuration
------------------

Finally, at the location pointed to in your zonelist.xml, you should create
a signer configuration xml file. An example can be found at:
http://www.opendnssec.se/browser/trunk/conf/opendnssec/signconf.xml

The elements and their exact meanings are described here:
http://www.opendnssec.se/browser/trunk/conf/opendnssec/signconf.rnc


Diagnostics
-----------

The signer prints statistics about the signed zones into the logs.

[STATS] opendnssec.org RR[count=32 time=1(sec)]
                       NSEC[count=32 time=1(sec)]
                       RRSIG[new=1 reused=31 time=1(sec) avg=1(sig/sec)]
                       TOTAL[time=5(sec)]

RR[count] is the number of records read in the unsigned zone. It is zero if
the zone was not re-read. This happens for example when only re-signing.
RR[time] is the time it took to read the unsigned zone.

NSEC[count] is the number of NSEC or NSEC3 records added to the zone. This
can be zero too, when only re-signing.
NSEC[time] is the time it took to create all the Denial of Existence records.

RRSIG[new] is the number of signatures newly created.
RRSIG[reused] is the number of signatures that were created on a previous run,
but are fresh enough that they may be remained in the zone.
RRSIG[time] is the time it took to gather all the new and reused signatures.
RRSIG[avg] is the average number of created signatures per second.

TOTAL[time] is the total time it took for the signer engine to sign the 
latest version of the zone.


-------------------------------------------------------------------
DNS FILE ADAPTERS
-------------------------------------------------------------------
As mentioned above, you can use DNS adapters instead of File adapters.
Put something like this in your zonelist.xml:

<Zone name="example.com">
	...
	<Adapters>
		<Input>
			<Adapter type="DNS">example.com.dns.xml</Adapter>
		</Input>
		<Output>
			<Adapter type="DNS">example.com.dns.xml</Adapter>
		</Output>
	</Adapters>
</Zone>

The example.com.dns.xml holds all master and slave configurations for
transfers.


-------------------------------------------------------------------
DEBUGGING
-------------------------------------------------------------------
Warning: DO NOT TRY THIS EXCEPT FOR DEBUGGING PURPOSES

If the signer is build with the '--enable-timeshift' option, one can
override the system clock using the ENFORCER_TIMESHIFT environment variable.
ENFORCER_TIMESHIFT should be set to the timestamp (in YYYYMMDDHHMMSS format).
When running with timeshift, the program will run once only and exit.