.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "BUILDREALMS 1" .TH BUILDREALMS 1 2023-07-29 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME buildrealms \- assist in building a DNSSEC\-Tools realms environment .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& buildrealms [options] .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBbuildrealms\fR helps in setting up a realms environment for use by \fBdtrealms\fR. \&\fBbuildrealms\fR 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. .PP The realm hierarchies are built in a staging area, which will hold the files for all the realms. These are \fIrollrec\fR files, \fIkeyrec\fR files, key files, configuration files, log files, and anything else needed for by DNSSEC-Tools to manage key rollover. After \fBbuildrealms\fR 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 \fBdtrealms\fR will manage the various realms. If the final directory isn't specified (via an option), then the directory in which \fBbuildrealms\fR was executed will be the final directory. .PP \&\fBbuildrealms\fR uses a \fIrealms\fR file to control how it builds the realms environment. This \fBrealm\fR entries in this file have a \fIhoard\fR field, which is only used by \fBbuildrealms\fR. For each realm, this field's value is a directory which holds the files needed by that particular realm. After building that realm, \fBbuildrealms\fR removes the \fIhoard\fR entry from that \fBrealm\fR record. After all the realms have been built, a copy of this \&\fIrealms\fR file is moved into the staging area. .PP There are two operations \fBbuildrealms\fR currently provides. These operations are in support of creating and maintaining a DNSSEC-Tools realms environment. This documentation describes the operations individually. .SS "Realms Environment Creation" .IX Subsection "Realms Environment Creation" The \fIcreate\fR command builds the whole realms environment. The realm file hierarchies are built in the staging area. After \fBbuildrealms\fR 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 \fBbuildrealms\fR was executed will be the final directory. .PP \&\fBbuildrealms\fR takes the following actions when given the \fIcreate\fR command: .IP \(bu 4 A file hierarchy is created for each realm. .IP \(bu 4 A DNSSEC-Tools configuration file is put in each realm's hierarchy. If the \fI\-config\fR 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 \fB.conf\fR. 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. .IP \(bu 4 The realm's \fIrollrec\fR, \fIkeyrec\fR, zone, and key files are moved into the hierarchy. The \fIrollrec\fR file is named in the \fIrealms\fR file. The \&\fIkeyrec\fR and signed zone files are listed in the \fIrollrec\fR file. The unsigned zone files and key files are listed in the \fIkeyrec\fR file. .IP \(bu 4 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 \fIkeyrec\fR files, are moved to this key archive. .IP \(bu 4 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 \&\fIkeyrec\fR files, the key archive and \fBrollerd\fR log files in the realm's DNSSEC-Tools configuration file, and key directories in the \fIkeyrec\fR files. .SS "Realms Hierarchy Creation" .IX Subsection "Realms Hierarchy Creation" The \fItrees\fR 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.. .PP The following directories are created for each realm: .IP \(bu 4 configuration directory \- This holds the \fBdnssec-tools\fR directory. .IP \(bu 4 dnssec-tools directory \- This will hold the DNSSEC-Tools configuration file. .IP \(bu 4 state directory \- This will hold the realm's state information, including the key archive. .IP \(bu 4 realm directory \- This will hold the realm's \fIrollrec\fR file, the \&\fIkeyrec\fR files, the zone files (signed and unsigned), and the key files. .SH "PREPARING FOR EXECUTION" .IX Header "PREPARING FOR EXECUTION" In preparing a \fIrealms\fR file and the realm hoards for \fBbuildrealms\fR, there are several things that should be kept in mind. .IP \(bu 4 Use relative paths for the \fIrollrec\fR file and three directories in the \fIrealms\fR file. .IP \(bu 4 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 \fIrollrec\fR and \&\fIkeyrec\fR files are accurate. .IP \(bu 4 At the end of the creation process, the \fIrealms\fR file will be copied into the top level of the staging area. .IP \(bu 4 After specific files (e.g., \fIrollrec\fRs, \fIkeyrec\fRs, 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 \fIrealmdir\fR part of the staging area. The hierarchical organization of the remaining hoard files will be preserved. .IP \(bu 4 The contents of a \fIkeyrec\fR's archive directory in the realm's hoard, as defined by the \fIarchivedir\fR field, will be moved to \&\fB/key\-archive\fR in the staging area. .IP \(bu 4 The configuration file for a realm will be put in \&\fB/dnssec\-tools/\fR in the staging area. The actual name of the configuration file (given here as \fB\fR) will depend on how the configuration file is found. If the system-wide DNSSEC-Tools file is used, then the name will be \fBdnssec\-tools.conf\fR. If the \fI\-config\fR option is used, then the name used with the option will be used. If a \fB.conf\fR file is found in the realm's hoard, then the full filename will be used. .SH WARNINGS .IX Header "WARNINGS" \&\fIroot\fR is not allowed to run \fBbuildrealms\fR. Some of the actions taken by \fBbuildrealms\fR can be devastating if a misconfigured (or maliciously constructed) \fIrealm\fR file is used to control construction. .PP \&\fBbuildrealms\fR 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 \fBrealm\fR file \fIrollrec\fR files, \fIkeyrec\fR files, and configuration file. .PP 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 \&\fIprior\fR to running \fBbuildrealms\fR, just in case... .SH COMMANDS .IX Header "COMMANDS" .IP \fBcreate\fR 4 .IX Item "create" The \fBcreate\fR command builds the whole realms environment. \fBbuildrealms\fR takes the following actions when given this command: .IP \fBtrees\fR 4 .IX Item "trees" The \fBtrees\fR command builds the basic directory hierarchy for each realm. The following directories are created for each realm: .SH OPTIONS .IX Header "OPTIONS" .IP \fB\-actions\fR 4 .IX Item "-actions" Display the file actions taken by \fBbuildrealms\fR. This includes directory creations, file copies, and file moves. If used in conjunction with the \&\fB\-nobuild\fR option, \fBbuildrealms\fR will not perform the actions, but will display the actions that would otherwise have been taken. .IP \fB\-clear\fR 4 .IX Item "-clear" This flag indicates that \fBbuildrealms\fR should delete the current staging area and its contents prior to building the realms. .IP "\fB\-config conffile\fR" 4 .IX Item "-config conffile" \&\fBconffile\fR is the DNSSEC-Tools configuration file to copy for each realm. .IP "\fB\-directory target\fR" 4 .IX Item "-directory target" \&\fBtarget\fR is the target directory for the realms to be built by \&\fBbuildrealms\fR. 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. .Sp If \fB\-directory\fR and \fB\-stagedir\fR use the same directory, then the realms environment will be build in the final directory. .IP \fB\-nobuild\fR 4 .IX Item "-nobuild" This option tells \fBbuildrealms\fR to go through the motions of building the new realms, but not to actually build anything. If this is used in conjunctions with the \fB\-actions\fR option, \fBbuildrealms\fR will show the actions that would have been taken. .IP "\fB\-stagedir directory\fR" 4 .IX Item "-stagedir directory" This directory in which the new realms hierarchy is built. The default staging area is \fB./staging\-buildrealms\fR if this option is not specified. .Sp If \fB\-directory\fR and \fB\-stagedir\fR use the same directory, then the realms environment will be build in the final directory. .IP \fB\-quiet\fR 4 .IX Item "-quiet" \&\fBbuildrealms\fR is prevented from printing any non-error output. This option and the \fB\-verbose\fR option are mutually exclusive. .IP \fB\-verbose\fR 4 .IX Item "-verbose" \&\fBbuildrealms\fR prints a lot of information about what it is doing. This option and the \fB\-quiet\fR option are mutually exclusive. .IP \fB\-Version\fR 4 .IX Item "-Version" Displays the version number. .IP \fB\-help\fR 4 .IX Item "-help" Displays a help message. .SH EXAMPLES .IX Header "EXAMPLES" The following examples may help clarify the use of \fBbuildrealms\fR. In each example, the following \fIrealms\fR file will be used. .PP .Vb 11 \& 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" .Ve .SS "CREATE EXAMPLE" .IX Subsection "CREATE EXAMPLE" Each realm record contains a \fIhoard\fR field that \fBbuildrealms\fR will use to find that realm's files. After running \fBbuildrealms demo.realm create\fR with the \fIrealms\fR file above, the following directories will be created: .PP .Vb 6 \& 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/ .Ve .PP 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: .PP .Vb 1 \& 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 .Ve .SS "TREES EXAMPLE" .IX Subsection "TREES EXAMPLE" After running \fBbuildrealms demo.realm trees\fR with the \fIrealms\fR file above, the following directories will be created: .PP .Vb 6 \& 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/ .Ve .PP No additional files or directories are created by this command. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2012\-2014 SPARTA, Inc. All rights reserved. .SH AUTHOR .IX Header "AUTHOR" Wayne Morrison, tewok@tislabs.com .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBdtrealms\|(8)\fR, \&\fBrealminit\|(8)\fR, \&\fBrealmset\|(8)\fR .PP \&\fBkeyrec\|(5)\fR, \&\fBrealm\|(5)\fR, \&\fBrollrec\|(5)\fR