Provided by: dnssec-tools_2.0-1_all bug

NAME

       buildrealms - assist in building a DNSSEC-Tools realms environment

SYNOPSIS

         buildrealms [options] <realmsfile> <command> <command-args>

DESCRIPTION

       buildrealms helps in setting up a realms environment for use by dtrealms.  buildrealms
       creates the required file hierarchies for each realm, it moves a realm's files to their
       appropriate place in the hierarchy, and it updates several files for the final
       destination.

       The realm hierarchies are built in a staging area, which will hold the files for all the
       realms.  These are rollrec files, keyrec files, key files, configuration files, log files,
       and anything else needed for by DNSSEC-Tools to manage key rollover.  After buildrealms
       creates these files, the user should check the files to ensure that they are correct.  The
       files and directories in the staging then must be manually moved to the final directory.
       It is from this directory that dtrealms will manage the various realms.  If the final
       directory isn't specified (via an option), then the directory in which buildrealms was
       executed will be the final directory.

       buildrealms uses a realms file to control how it builds the realms environment.  This
       realm entries in this file have a hoard field, which is only used by buildrealms.  For
       each realm, this field's value is a directory which holds the files needed by that
       particular realm.  After building that realm, buildrealms removes the hoard entry from
       that realm record.  After all the realms have been built, a copy of this realms file is
       moved into the staging area.

       There are two operations buildrealms currently provides.  These operations are in support
       of creating and maintaining a DNSSEC-Tools realms environment.  This documentation
       describes the operations individually.

   Realms Environment Creation
       The create command builds the whole realms environment.  The realm file hierarchies are
       built in the staging area.  After buildrealms creates these files, the user should check
       the files to ensure that they are correct.  The files and directories in the staging then
       must be manually moved to the final directory.  If the final directory isn't specified
       (via an option), then the directory in which buildrealms was executed will be the final
       directory.

       buildrealms takes the following actions when given the create command:

       •   A file hierarchy is created for each realm.

       •   A DNSSEC-Tools configuration file is put in each realm's hierarchy.  If the -config
           option is given, then the specified configuration file will be copied to each realm.
           If it isn't given, then each realm's hoard will be searched for a file whose name ends
           with .conf.  The first such file found will be used for that realm only.  If such a
           file is not found, then the system-wide DNSSEC-Tools configuration file will be used
           for that realm.

       •   The realm's rollrec, keyrec, zone, and key files are moved into the hierarchy.  The
           rollrec file is named in the realms file.  The keyrec and signed zone files are listed
           in the rollrec file.  The unsigned zone files and key files are listed in the keyrec
           file.

       •   A key archive is created for each realm's existing, expired keys.  The key archive is
           placed in the realm's state directory in the staging area.  Archived keys, as listed
           in the keyrec files, are moved to this key archive.

       •   Paths in several files are adjusted for the new hierarchy and the realm's final
           destination.  These paths include archived keys in the realm's keyrec files, the key
           archive and rollerd log files in the realm's DNSSEC-Tools configuration file, and key
           directories in the keyrec files.

   Realms Hierarchy Creation
       The trees command builds the basic directory hierarchy for each realm in the staging area.
       However, no other files or directories are copied or moved in to the staging area..

       The following directories are created for each realm:

       •   configuration directory - This holds the dnssec-tools directory.

       •   dnssec-tools directory - This will hold the DNSSEC-Tools configuration file.

       •   state directory - This will hold the realm's state information, including the key
           archive.

       •   realm directory - This will hold  the realm's rollrec file, the keyrec files, the zone
           files (signed and unsigned), and the key files.

PREPARING FOR EXECUTION

       In preparing a realms file and the realm hoards for buildrealms, there are several things
       that should be kept in mind.

       •   Use relative paths for the rollrec file and three directories in the realms file.

       •   All a realm's files should be stored in its hoard.  They do not have to be in a
           particular place in the directory, as long as the rollrec and keyrec files are
           accurate.

       •   At the end of the creation process, the realms file will be copied into the top level
           of the staging area.

       •   After specific files (e.g., rollrecs, keyrecs, etc.) are moved into a realm's part of
           the staging area, the remaining files in the hoard will be moved into the realm's
           realmdir part of the staging area.  The hierarchical organization of the remaining
           hoard files will be preserved.

       •   The contents of a keyrec's archive directory in the realm's hoard, as defined by the
           archivedir field, will be moved to <statedir>/key-archive in the staging area.

       •   The configuration file for a realm will be put in <configdir>/dnssec-tools/<conffile>
           in the staging area.  The actual name of the configuration file (given here as
           <conffile>) will depend on how the configuration file is found.  If the system-wide
           DNSSEC-Tools file is used, then the name will be dnssec-tools.conf.  If the -config
           option is used, then the name used with the option will be used.  If a .conf file is
           found in the realm's hoard, then the full filename will be used.

WARNINGS

       root is not allowed to run buildrealms.  Some of the actions taken by buildrealms can be
       devastating if a misconfigured (or maliciously constructed) realm file is used to control
       construction.

       buildrealms is not clairvoyant.  It does the best it can, but it is a general tool.  The
       resulting realms should be checked to ensure they are set up as desired.  In particular,
       you should check the realm file rollrec files, keyrec files, and configuration file.

       No reverse functionality has been implemented, so once run, the files are modified, moved,
       and copied.  It might not be a bad idea to back up your files prior to running
       buildrealms, just in case...

COMMANDS

       create
           The create command builds the whole realms environment.  buildrealms takes the
           following actions when given this command:

       trees
           The trees command builds the basic directory hierarchy for each realm.  The following
           directories are created for each realm:

OPTIONS

       -actions
           Display the file actions taken by buildrealms.  This includes directory creations,
           file copies, and file moves.  If used in conjunction with the -nobuild option,
           buildrealms will not perform the actions, but will display the actions that would
           otherwise have been taken.

       -clear
           This flag indicates that buildrealms should delete the current staging area and its
           contents prior to building the realms.

       -config conffile
           conffile is the DNSSEC-Tools configuration file to copy for each realm.

       -directory target
           target is the target directory for the realms to be built by buildrealms.  The new
           realms will not be moved to this directory, but the realms' files will reflect the use
           of this directory.  If this option is not specified, the current directory will be
           used.

           If -directory and -stagedir use the same directory, then the realms environment will
           be build in the final directory.

       -nobuild
           This option tells buildrealms to go through the motions of building the new realms,
           but not to actually build anything.  If this is used in conjunctions with the -actions
           option, buildrealms will show the actions that would have been taken.

       -stagedir directory
           This directory in which the new realms hierarchy is built.  The default staging area
           is ./staging-buildrealms if this option is not specified.

           If -directory and -stagedir use the same directory, then the realms environment will
           be build in the final directory.

       -quiet
           buildrealms is prevented from printing any non-error output.  This option and the
           -verbose option are mutually exclusive.

       -verbose
           buildrealms prints a lot of information about what it is doing.  This option and the
           -quiet option are mutually exclusive.

       -Version
           Displays the version number.

       -help
           Displays a help message.

EXAMPLES

       The following examples may help clarify the use of buildrealms.  In each example, the
       following realms file will be used.

           realm "example"
               state           "active"
               configdir       "configs/example"
               statedir        "states/example"
               realmdir        "r-example"
               rollrec         "demo-example.rollrec"
               administrator   "zonefolks@example.com"
               display         "1"
               manager         "rollerd"
               args            "-loglevel phase -logfile log.example"
               hoard           "r-example"

           realm "test"
               state           "active"
               realmdir        "r-test"
               configdir       "configs/test"
               statedir        "states/test"
               rollrec         "demo-test.rollrec"
               manager         "rollerd"
               args            "-loglevel tmi -logfile log.test"
               display         "1"
               hoard           "r-test"

   CREATE EXAMPLE
       Each realm record contains a hoard field that buildrealms will use to find that realm's
       files.  After running buildrealms demo.realm create with the realms file above, the
       following directories will be created:

           staging-buildrealms/
           staging-buildrealms/configs/
           staging-buildrealms/configs/example/
           staging-buildrealms/configs/example/dnssec-tools/
           staging-buildrealms/configs/test/
           staging-buildrealms/configs/test/dnssec-tools/

           staging-buildrealms/r-example/
           staging-buildrealms/r-example/dnssec-tools/
           staging-buildrealms/r-test/
           staging-buildrealms/r-test/dnssec-tools/

           staging-buildrealms/states/
           staging-buildrealms/states/example/
           staging-buildrealms/states/example/key-archive/
           staging-buildrealms/states/test/
           staging-buildrealms/states/test/key-archive/

       The following files will be moved into the staging area.  In the interests of brevity this
       is only a subset of files moved to the staging area; most of the key files have not been
       included:

           staging-buildrealms/demo.realm

           staging-buildrealms/configs/example/dnssec-tools/dnssec-tools.conf
           staging-buildrealms/configs/test/dnssec-tools/dnssec-tools.conf

           staging-buildrealms/r-example/demo-example.rollrec
           staging-buildrealms/r-example/demo.com
           staging-buildrealms/r-example/demo.com.signed
           staging-buildrealms/r-example/dsset-demo.com.
           staging-buildrealms/r-example/dsset-example.com.
           staging-buildrealms/r-example/dsset-test.com.
           staging-buildrealms/r-example/example.com
           staging-buildrealms/r-example/example.com.signed
           staging-buildrealms/r-example/Kdemo.com.+005+16933.key
           staging-buildrealms/r-example/Kdemo.com.+005+16933.private
           staging-buildrealms/r-example/test.com
           staging-buildrealms/r-example/test.com.signed

           staging-buildrealms/r-test/demo-test.rollrec
           staging-buildrealms/r-test/dev.com
           staging-buildrealms/r-test/dev.com.signed
           staging-buildrealms/r-test/dsset-dev.com.
           staging-buildrealms/r-test/dsset-test.com.
           staging-buildrealms/r-test/Ktest.com.+005+34236.key
           staging-buildrealms/r-test/Ktest.com.+005+34236.private
           staging-buildrealms/r-test/test.com
           staging-buildrealms/r-test/test.com.signed

   TREES EXAMPLE
       After running buildrealms demo.realm trees with the realms file above, the following
       directories will be created:

           staging-buildrealms/
           staging-buildrealms/configs/
           staging-buildrealms/configs/example/
           staging-buildrealms/configs/example/dnssec-tools/
           staging-buildrealms/configs/test/
           staging-buildrealms/configs/test/dnssec-tools/

           staging-buildrealms/r-example/
           staging-buildrealms/r-test/

           staging-buildrealms/states/
           staging-buildrealms/states/example/
           staging-buildrealms/states/test/

       No additional files or directories are created by this command.

COPYRIGHT

       Copyright 2012-2013 SPARTA, Inc.  All rights reserved.

AUTHOR

       Wayne Morrison, tewok@tislabs.com

SEE ALSO

       dtrealms(8), realminit(8), realmset(8)

       keyrec(5), realm(5), rollrec(5)