Rollover Realms: Multiple, Simultaneous, Independent Rollover Environments
This is a brief description of using realms in DNSSEC-Tools rollover management.
DNSSEC-Tools provides rollerd and zonesigner for managing key rollovers in zones. There are times when it would be desirable to have multiple instances of rollerd running simultaneously, but with different collections of zones. This has been possible for quite a while, but only by manually setting environment variables and building file hierarchies for each environment.
The realms facility in DNSSEC-Tools allows an administrator to easily manage multiple rollover environments that are executing simultaneously. The dtrealms command will start each rollover environment within its own "realm", keeping separate the zone files, key files, configuration files, and other required pieces of the environment. The rollerd managing rollover actions in a particular realm will only know about the zones in that realm; it won't have anything to do with the zones in any other realm.
realms are useful in the following situations:
- testing new software
- very large (hundreds or thousands) of zones being managed
- segregating customers or classes of customers
- 1 Realm Definition
- 2 Realm Initialization
- 3 Things To Come
A realm is distinguished by the following things:
- configuration directory - The configuration directory for the realm. This will hold the dnssec-tools.conf configuration file. It may also hold the key archive and other files. It contain a dnssec-tools directory.
- state directory - This directory holds a number of files used during execution of a realm. This includes communications sockets, lock files, and a process-id file. This may be combined with the configuration directory.
- realm directory - The rollrec file, zone files, keyrec files, all the files that define the zones in a realm are stored in this directory.
In the current system, each realm must be created manually. Tools are being developed to assist in this, but for now the steps given below must be followed.
The Makefile in the .../demos/dtrealms-basic directory may be consulted to see how two realms are constructed.
Structure of Hierarchy
You must decide how each realm's files will be organized. This decision will be reflected in where the various directories are created and how the realms file is built. The "Example Realms Directory" section below gives two organizational methods.
The first method groups the realms' configuration directories in one directory, the realms' state directories in one directory, and the realms' realm directories into one directory. Each realm's directory and files are subdirectories named by the realm. With the realms bob-realm and mary-realm, this might give such directories as:
The second method groups each realm's configuration, state, and realms directories beneath a single directory, again named by the realm. With the same example realms, the directories might be:
Both methods will work, and an individual will likely prefer one method over another. It is likely that a set of realms could be defined such that all their files were intermingled, but this is the path to madness and ruin. This method of disorganization is strongly discouraged.
You should create a realms directory1. This is a directory that will hold all the files for all the realms, as well as the files used by the DNSSEC-Tools realms software. This includes the realms file, all the configuration directories, all the state directories, all the realm directories, all the zone files, all the rollrec files, all the key files, everything.
This is not a requirement. However, grouping these files together will likely make the administrator's life easier.
This directory should be reasonably close to the top of the file system so that its pathname is no more than around 50-60 characters long. The actual length will depend on the length of your longest realm name. dtrealms and rollerd use sockets for communicating with their control programs. These sockets are represented by filenames and operating systems restrict this name to be 104-108 characters long, depending on the system. This restriction is required due to an operating system limit that is beyond the control of DNSSEC-Tools.
1 The "realms directory" is not the same thing as a "realm directory".
The configuration directories for each realm must be created. This directory will hold the dnssec-tools.conf configuration file and it contain a dnssec-tools directory. This directory may be combined with the realm's state directory.
This directory holds a number of files used during execution of a realm. This includes communications sockets, lock files, and a process-id file. The realm's key archive may be stored here. This may be combined with the configuration directory. If it is not combined, then this directory must be created.
The rollrec file, zone files, keyrec files, all the files used by the zones in a realm are stored in this directory. The realm directory must be created.
A realms file, which will contain a set of realm entries, must be created. It will define the existing realms. Each realm entry describes where the realm's data are stored, whether the realm is active, and other important information about the realm.
You must build a realms file with entries for each of your realms. It should use the structure decided upon above, and organize the directories accordingly.
The realminit command may be used to create a realms file.
DNSSEC-Tools Configuration File
Each realm will have its own DNSSEC-Tools configuration file. At this writing, there are no realms-specific entries in this file. A distinct copy of a single DNSSEC-Tools configuration file may be made for each realm. The dtinitconf command may be used to create a new DNSSEC-Tools configuration file.
However, this file may be used to define realms-specific behavior. If one realm should use two KSK keys and four ZSK keys per zone and all other realms use a single KSK and a single ZSK, then that must be set in the realms' configuration files. This file is also where the pathnames are set for various programs, such as zonesigner and dnssec-keygen. This will allow a separate zone to be created for testing new versions of DNSSEC-Tools or BIND.
This configuration file is also where the key archive is specified. This is discussed in the next section.
Key Archive Directory
The DNSSEC-Tools programs move a zone's old keys into the key archive directory. This directory is defined in the DNSSEC-Tools configuration file. A key archive directory must be created for each realm.
rollrec files control the rollover process managed by the rollerd program. Each realm must have a rollrec file. This will describe how rollerd handles rollover for each zone in that realm. The rollinit command may be used to create this file. It is recommended that the rollrec file be kept in the realm's realm directory.
Example Realms Directory
The following is the contents of a realms directory that has three realms, bob-realm, mary-realm, and chris-realm. Each realm has two zones.
bob-realm and mary-realm are organized such that their files are grouped according to function. chris-realm is organized so that all its files are beneath a single directory.
/dnssec/realms /dnssec/realms/configs /dnssec/realms/configs/bob-realm /dnssec/realms/configs/bob-realm/dnssec-tools /dnssec/realms/configs/bob-realm/dnssec-tools/dnssec-tools.conf /dnssec/realms/configs/mary-realm /dnssec/realms/configs/mary-realm/dnssec-tools /dnssec/realms/configs/mary-realm/dnssec-tools/dnssec-tools.conf /dnssec/realms/states /dnssec/realms/states/bob-realm /dnssec/realms/states/bob-realm/dnssec-tools /dnssec/realms/states/bob-realm/dnssec-tools/rollmgr.socket /dnssec/realms/states/bob-realm/dnssec-tools/rollrec.lock /dnssec/realms/states/bob-realm/dnssec-tools/key-archive /dnssec/realms/states/mary-realm /dnssec/realms/states/mary-realm/dnssec-tools /dnssec/realms/states/mary-realm/dnssec-tools/rollmgr.socket /dnssec/realms/states/mary-realm/dnssec-tools/rollrec.lock /dnssec/realms/states/mary-realm/dnssec-tools/key-archive /dnssec/realms/bob-realm /dnssec/realms/bob-realm/bob.rollrec /dnssec/realms/bob-realm/bob1.example.com /dnssec/realms/bob-realm/bob1.example.com.krf /dnssec/realms/bob-realm/bob1.example.com.signed /dnssec/realms/bob-realm/bob2.example.com /dnssec/realms/bob-realm/bob2.example.com.krf /dnssec/realms/bob-realm/bob2.example.com.signed /dnssec/realms/mary-realm /dnssec/realms/mary-realm/mary-realm.rrf /dnssec/realms/mary-realm/sub1.mary.example.com /dnssec/realms/mary-realm/sub1.mary.example.com.krf /dnssec/realms/mary-realm/sub1.mary.example.com.signed /dnssec/realms/mary-realm/sub2.mary.example.com /dnssec/realms/mary-realm/sub2.mary.example.com.krf /dnssec/realms/mary-realm/sub2.mary.example.com.signed /dnssec/realms/chris-realm/dnssec-tools /dnssec/realms/chris-realm/dnssec-tools/dnssec-tools.conf /dnssec/realms/chris-realm/dnssec-tools/rollmgr.socket /dnssec/realms/chris-realm/dnssec-tools/rollrec.lock /dnssec/realms/chris-realm/dnssec-tools/key-archive /dnssec/realms/chris-realm/zones/rollrec-chris /dnssec/realms/chris-realm/zones/kim.example.com /dnssec/realms/chris-realm/zones/kim.example.com.krf /dnssec/realms/chris-realm/zones/kim.example.com.signed /dnssec/realms/chris-realm/zones/lee.example.com /dnssec/realms/chris-realm/zones/lee.example.com.krf /dnssec/realms/chris-realm/zones/lee.example.com.signed
Things To Come
Additional tools and capabilities are planned for the DNSSEC-Tools realms support. These include:
- buildrealms - This tool will perform the vast bulk of the work in creating a set of realms for use with dtrealms. This tool is under construction.
- grandvizier - Additional realms-management commands will be added.
- migrate - This tool will move a set of zones from one realm to another.
- realm-editor - This tool will be a GUI editor for realms files.