1BUILDREALMS(1) User Contributed Perl Documentation BUILDREALMS(1)
2
6 buildrealms - assist in building a DNSSEC-Tools realms environment
7
9 buildrealms [options] <realmsfile> <command> <command-args>
10
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 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 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 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 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 buildrealms takes the following actions when given the create command:
51 • A file hierarchy is created for each realm.
53 • 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 • 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 • 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 • 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 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 The following directories are created for each realm:
84 • configuration directory - This holds the dnssec-tools directory.
86 • dnssec-tools directory - This will hold the DNSSEC-Tools
88 configuration file.
89 • state directory - This will hold the realm's state information,
91 including the key archive.
92 • 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
98 In preparing a realms file and the realm hoards for buildrealms, there
99 are several things that should be kept in mind.
100 • Use relative paths for the rollrec file and three directories in
102 the realms file.
103 • 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 • At the end of the creation process, the realms file will be copied
109 into the top level of the staging area.
110 • 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 • 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 • 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
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 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 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
145 create
146 The create command builds the whole realms environment.
147 buildrealms takes the following actions when given this command:
148 trees
150 The trees command builds the basic directory hierarchy for each
151 realm. The following directories are created for each realm:
152
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 -clear
162 This flag indicates that buildrealms should delete the current
163 staging area and its contents prior to building the realms.
164 -config conffile
166 conffile is the DNSSEC-Tools configuration file to copy for each
167 realm.
168 -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 If -directory and -stagedir use the same directory, then the realms
176 environment will be build in the final directory.
177 -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 -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 If -directory and -stagedir use the same directory, then the realms
190 environment will be build in the final directory.
191 -quiet
193 buildrealms is prevented from printing any non-error output. This
194 option and the -verbose option are mutually exclusive.
195 -verbose
197 buildrealms prints a lot of information about what it is doing.
198 This option and the -quiet option are mutually exclusive.
199 -Version
201 Displays the version number.
202 -help
204 Displays a help message.
205
207 The following examples may help clarify the use of buildrealms. In
208 each example, the following realms file will be used.
209 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 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 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 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 staging-buildrealms/r-example/
246 staging-buildrealms/r-example/dnssec-tools/
247 staging-buildrealms/r-test/
248 staging-buildrealms/r-test/dnssec-tools/
249 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 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 staging-buildrealms/demo.realm
261 staging-buildrealms/configs/example/dnssec-tools/dnssec-tools.conf
263 staging-buildrealms/configs/test/dnssec-tools/dnssec-tools.conf
264 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 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 TREES EXAMPLE
289 After running buildrealms demo.realm trees with the realms file above,
290 the following directories will be created:
291 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 staging-buildrealms/r-example/
300 staging-buildrealms/r-test/
301 staging-buildrealms/states/
303 staging-buildrealms/states/example/
304 staging-buildrealms/states/test/
305 No additional files or directories are created by this command.
307
309 Copyright 2012-2014 SPARTA, Inc. All rights reserved.
310
312 Wayne Morrison, tewok@tislabs.com
313
315 dtrealms(8), realminit(8), realmset(8)
316 keyrec(5), realm(5), rollrec(5)
318perl v5.38.0 2023-07-19 BUILDREALMS(1)