$Id: README 3586 2010-07-22 12:44:44Z matthijs $ 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. In this version, it can do file-to-file signing or AXFR-to-file signing. 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. The current signer engine consists of two parts; The actual scheduler, including a set of workers to do zone manipulation, and a zone fetcher that takse care of AXFR. The scheduler 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. The zone fetcher is started by the scheduler if a zone fetch configuration is configured. The zone fetcher will do AXFR requests for all zones upon startup and upon receiving a valid NOTIFY message. ------------------------------------------------------------------- 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 ------------------------------------------------------------------- To build and install the signer engine, the following steps are needed: From the base directory /signer autoreconf --install ./configure make make install This will build the C-based tools, and set up the tools and engine to use the options provided with configure: --with-ldns= The base directory (prefix) of your ldns installation, if it isn't in your standard path. --prefix= 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 /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 schedule zone for immediate (re-)signing sign --all schedule all zones for immediate (re-)signing. clear 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 update this zone signer configurations. update [--all] update zone list and all signer configurations. start start the engine. reload reload the engine. stop stop the engine. verbosity 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 /sbin/ods-signer start If everything is ok, you should see the following output: $ ./ods-signer start OpenDNSSEC signer engine version 1.2.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 /etc/opendnssec/conf.xml file to your settings; the element should contain the name of the token you have initialized in your HSM, the complete path of the module library (e.g. /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 below . 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 /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. zonefetch.xml ------------ You can tell the engine where and how to get the zones from the master servers with /etc/zonefetch.xml An example zone list file can be found at http://www.opendnssec.se/browser/trunk/conf/opendnssec/zonefetch.xml The elements and their exact meanings are described here: http://www.opendnssec.se/browser/trunk/conf/opendnssec/zonefetch.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 configuration ------------------ 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 zone file --------- Finally, you 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. 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)] AUDIT[time=2(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. AUDIT[time] is the time it took for the ods-auditor to run. TOTAL[time] is the total time it took for the signer engine to sign the latest version of the zone. ------------------------------------------------------------------- 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.