1BUILDREALMS(1)        User Contributed Perl Documentation       BUILDREALMS(1)
2
3
4

NAME

6       buildrealms - assist in building a DNSSEC-Tools realms environment
7

SYNOPSIS

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

DESCRIPTION

12       buildrealms helps in setting up a realms environment for use by
13       dtrealms.  buildrealms creates the required file hierarchies for each
14       realm, it moves a realm's files to their appropriate place in the
15       hierarchy, and it updates several files for the final destination.
16
17       The realm hierarchies are built in a staging area, which will hold the
18       files for all the realms.  These are rollrec files, keyrec files, key
19       files, configuration files, log files, and anything else needed for by
20       DNSSEC-Tools to manage key rollover.  After buildrealms creates these
21       files, the user should check the files to ensure that they are correct.
22       The files and directories in the staging then must be manually moved to
23       the final directory.  It is from this directory that dtrealms will
24       manage the various realms.  If the final directory isn't specified (via
25       an option), then the directory in which buildrealms was executed will
26       be the final directory.
27
28       buildrealms uses a realms file to control how it builds the realms
29       environment.  This realm entries in this file have a hoard field, which
30       is only used by buildrealms.  For each realm, this field's value is a
31       directory which holds the files needed by that particular realm.  After
32       building that realm, buildrealms removes the hoard entry from that
33       realm record.  After all the realms have been built, a copy of this
34       realms file is moved into the staging area.
35
36       There are two operations buildrealms currently provides.  These
37       operations are in support of creating and maintaining a DNSSEC-Tools
38       realms environment.  This documentation describes the operations
39       individually.
40
41   Realms Environment Creation
42       The create command builds the whole realms environment.  The realm file
43       hierarchies are built in the staging area.  After buildrealms creates
44       these files, the user should check the files to ensure that they are
45       correct.  The files and directories in the staging then must be
46       manually moved to the final directory.  If the final directory isn't
47       specified (via an option), then the directory in which buildrealms was
48       executed will be the final directory.
49
50       buildrealms takes the following actions when given the create command:
51
52       •   A file hierarchy is created for each realm.
53
54       •   A DNSSEC-Tools configuration file is put in each realm's hierarchy.
55           If the -config option is given, then the specified configuration
56           file will be copied to each realm.  If it isn't given, then each
57           realm's hoard will be searched for a file whose name ends with
58           .conf.  The first such file found will be used for that realm only.
59           If such a file is not found, then the system-wide DNSSEC-Tools
60           configuration file will be used for that realm.
61
62       •   The realm's rollrec, keyrec, zone, and key files are moved into the
63           hierarchy.  The rollrec file is named in the realms file.  The
64           keyrec and signed zone files are listed in the rollrec file.  The
65           unsigned zone files and key files are listed in the keyrec file.
66
67       •   A key archive is created for each realm's existing, expired keys.
68           The key archive is placed in the realm's state directory in the
69           staging area.  Archived keys, as listed in the keyrec files, are
70           moved to this key archive.
71
72       •   Paths in several files are adjusted for the new hierarchy and the
73           realm's final destination.  These paths include archived keys in
74           the realm's keyrec files, the key archive and rollerd log files in
75           the realm's DNSSEC-Tools configuration file, and key directories in
76           the keyrec files.
77
78   Realms Hierarchy Creation
79       The trees command builds the basic directory hierarchy for each realm
80       in the staging area.  However, no other files or directories are copied
81       or moved in to the staging area..
82
83       The following directories are created for each realm:
84
85       •   configuration directory - This holds the dnssec-tools directory.
86
87       •   dnssec-tools directory - This will hold the DNSSEC-Tools
88           configuration file.
89
90       •   state directory - This will hold the realm's state information,
91           including the key archive.
92
93       •   realm directory - This will hold  the realm's rollrec file, the
94           keyrec files, the zone files (signed and unsigned), and the key
95           files.
96

PREPARING FOR EXECUTION

98       In preparing a realms file and the realm hoards for buildrealms, there
99       are several things that should be kept in mind.
100
101       •   Use relative paths for the rollrec file and three directories in
102           the realms file.
103
104       •   All a realm's files should be stored in its hoard.  They do not
105           have to be in a particular place in the directory, as long as the
106           rollrec and keyrec files are accurate.
107
108       •   At the end of the creation process, the realms file will be copied
109           into the top level of the staging area.
110
111       •   After specific files (e.g., rollrecs, keyrecs, etc.) are moved into
112           a realm's part of the staging area, the remaining files in the
113           hoard will be moved into the realm's realmdir part of the staging
114           area.  The hierarchical organization of the remaining hoard files
115           will be preserved.
116
117       •   The contents of a keyrec's archive directory in the realm's hoard,
118           as defined by the archivedir field, will be moved to
119           <statedir>/key-archive in the staging area.
120
121       •   The configuration file for a realm will be put in
122           <configdir>/dnssec-tools/<conffile> in the staging area.  The
123           actual name of the configuration file (given here as <conffile>)
124           will depend on how the configuration file is found.  If the system-
125           wide DNSSEC-Tools file is used, then the name will be
126           dnssec-tools.conf.  If the -config option is used, then the name
127           used with the option will be used.  If a .conf file is found in the
128           realm's hoard, then the full filename will be used.
129

WARNINGS

131       root is not allowed to run buildrealms.  Some of the actions taken by
132       buildrealms can be devastating if a misconfigured (or maliciously
133       constructed) realm file is used to control construction.
134
135       buildrealms is not clairvoyant.  It does the best it can, but it is a
136       general tool.  The resulting realms should be checked to ensure they
137       are set up as desired.  In particular, you should check the realm file
138       rollrec files, keyrec files, and configuration file.
139
140       No reverse functionality has been implemented, so once run, the files
141       are modified, moved, and copied.  It might not be a bad idea to back up
142       your files prior to running buildrealms, just in case...
143

COMMANDS

145       create
146           The create command builds the whole realms environment.
147           buildrealms takes the following actions when given this command:
148
149       trees
150           The trees command builds the basic directory hierarchy for each
151           realm.  The following directories are created for each realm:
152

OPTIONS

154       -actions
155           Display the file actions taken by buildrealms.  This includes
156           directory creations, file copies, and file moves.  If used in
157           conjunction with the -nobuild option, buildrealms will not perform
158           the actions, but will display the actions that would otherwise have
159           been taken.
160
161       -clear
162           This flag indicates that buildrealms should delete the current
163           staging area and its contents prior to building the realms.
164
165       -config conffile
166           conffile is the DNSSEC-Tools configuration file to copy for each
167           realm.
168
169       -directory target
170           target is the target directory for the realms to be built by
171           buildrealms.  The new realms will not be moved to this directory,
172           but the realms' files will reflect the use of this directory.  If
173           this option is not specified, the current directory will be used.
174
175           If -directory and -stagedir use the same directory, then the realms
176           environment will be build in the final directory.
177
178       -nobuild
179           This option tells buildrealms to go through the motions of building
180           the new realms, but not to actually build anything.  If this is
181           used in conjunctions with the -actions option, buildrealms will
182           show the actions that would have been taken.
183
184       -stagedir directory
185           This directory in which the new realms hierarchy is built.  The
186           default staging area is ./staging-buildrealms if this option is not
187           specified.
188
189           If -directory and -stagedir use the same directory, then the realms
190           environment will be build in the final directory.
191
192       -quiet
193           buildrealms is prevented from printing any non-error output.  This
194           option and the -verbose option are mutually exclusive.
195
196       -verbose
197           buildrealms prints a lot of information about what it is doing.
198           This option and the -quiet option are mutually exclusive.
199
200       -Version
201           Displays the version number.
202
203       -help
204           Displays a help message.
205

EXAMPLES

207       The following examples may help clarify the use of buildrealms.  In
208       each example, the following realms file will be used.
209
210           realm "example"
211               state           "active"
212               configdir       "configs/example"
213               statedir        "states/example"
214               realmdir        "r-example"
215               rollrec         "demo-example.rollrec"
216               administrator   "zonefolks@example.com"
217               display         "1"
218               manager         "rollerd"
219               args            "-loglevel phase -logfile log.example"
220               hoard           "r-example"
221
222           realm "test"
223               state           "active"
224               realmdir        "r-test"
225               configdir       "configs/test"
226               statedir        "states/test"
227               rollrec         "demo-test.rollrec"
228               manager         "rollerd"
229               args            "-loglevel tmi -logfile log.test"
230               display         "1"
231               hoard           "r-test"
232
233   CREATE EXAMPLE
234       Each realm record contains a hoard field that buildrealms will use to
235       find that realm's files.  After running buildrealms demo.realm create
236       with the realms file above, the following directories will be created:
237
238           staging-buildrealms/
239           staging-buildrealms/configs/
240           staging-buildrealms/configs/example/
241           staging-buildrealms/configs/example/dnssec-tools/
242           staging-buildrealms/configs/test/
243           staging-buildrealms/configs/test/dnssec-tools/
244
245           staging-buildrealms/r-example/
246           staging-buildrealms/r-example/dnssec-tools/
247           staging-buildrealms/r-test/
248           staging-buildrealms/r-test/dnssec-tools/
249
250           staging-buildrealms/states/
251           staging-buildrealms/states/example/
252           staging-buildrealms/states/example/key-archive/
253           staging-buildrealms/states/test/
254           staging-buildrealms/states/test/key-archive/
255
256       The following files will be moved into the staging area.  In the
257       interests of brevity this is only a subset of files moved to the
258       staging area; most of the key files have not been included:
259
260           staging-buildrealms/demo.realm
261
262           staging-buildrealms/configs/example/dnssec-tools/dnssec-tools.conf
263           staging-buildrealms/configs/test/dnssec-tools/dnssec-tools.conf
264
265           staging-buildrealms/r-example/demo-example.rollrec
266           staging-buildrealms/r-example/demo.com
267           staging-buildrealms/r-example/demo.com.signed
268           staging-buildrealms/r-example/dsset-demo.com.
269           staging-buildrealms/r-example/dsset-example.com.
270           staging-buildrealms/r-example/dsset-test.com.
271           staging-buildrealms/r-example/example.com
272           staging-buildrealms/r-example/example.com.signed
273           staging-buildrealms/r-example/Kdemo.com.+005+16933.key
274           staging-buildrealms/r-example/Kdemo.com.+005+16933.private
275           staging-buildrealms/r-example/test.com
276           staging-buildrealms/r-example/test.com.signed
277
278           staging-buildrealms/r-test/demo-test.rollrec
279           staging-buildrealms/r-test/dev.com
280           staging-buildrealms/r-test/dev.com.signed
281           staging-buildrealms/r-test/dsset-dev.com.
282           staging-buildrealms/r-test/dsset-test.com.
283           staging-buildrealms/r-test/Ktest.com.+005+34236.key
284           staging-buildrealms/r-test/Ktest.com.+005+34236.private
285           staging-buildrealms/r-test/test.com
286           staging-buildrealms/r-test/test.com.signed
287
288   TREES EXAMPLE
289       After running buildrealms demo.realm trees with the realms file above,
290       the following directories will be created:
291
292           staging-buildrealms/
293           staging-buildrealms/configs/
294           staging-buildrealms/configs/example/
295           staging-buildrealms/configs/example/dnssec-tools/
296           staging-buildrealms/configs/test/
297           staging-buildrealms/configs/test/dnssec-tools/
298
299           staging-buildrealms/r-example/
300           staging-buildrealms/r-test/
301
302           staging-buildrealms/states/
303           staging-buildrealms/states/example/
304           staging-buildrealms/states/test/
305
306       No additional files or directories are created by this command.
307
309       Copyright 2012-2014 SPARTA, Inc.  All rights reserved.
310

AUTHOR

312       Wayne Morrison, tewok@tislabs.com
313

SEE ALSO

315       dtrealms(8), realminit(8), realmset(8)
316
317       keyrec(5), realm(5), rollrec(5)
318
319
320
321perl v5.38.0                      2023-07-19                    BUILDREALMS(1)
Impressum