REALMINIT(1p)						User Contributed Perl Documentation					     REALMINIT(1p)

NAME

       realminit - Create new realm records for a DNSSEC-Tools realms file.

SYNOPSIS

	 realminit [options] <realm1> ... <realmN>

DESCRIPTION

       realminit creates new realm entries for a realms file.  dtrealms manages multiple distinct DNSSEC-Tools rollover environments running
       simultaneously.	Each rollover environment, called a realm, is defined in a realms file.  dtrealms uses this file to determine how to run
       the rollover environment.  This is useful for such things as managing very large collections of zones, segregating customer zones, and
       software tests.

       The newly generated realm entries are written to standard output, unless the -out option is specified.

       A realms file contains a number of entries, one for each managed realm.	A realm entry has this format:

	   realm "example"
	       state	      "active"
	       configdir      "/usr/realms/configs/example"
	       statedir       "/usr/realms/states/example"
	       realmsdir      "/usr/realms/realms-files/example"
	       rollrec	      "example.rrf"
	       administrator  "bob@cat.example.com"
	       display	      "1"
	       manager	      "rollerd"
	       args	      "-display -loglevel phase"

       Multiple realm entries may be created with a single execution of realminit.  Except for the entry's name field, the entries will be exactly
       the same unless the '=' metacharacter is used in the command-line options.  If the values of the configdir, statedir, realmdir, rollrec,
       administrator, args, or user options contain an '=', then it will be replaced with the realm's name when building the entry.  See the
       EXAMPLES section for examples of how options are used by realminit.

OPTIONS

       realminit may be given the following options:

       -active
	   This indicates that dtrealms should start the realm when dtrealms starts.  realms are active by default.

       -administrator
	   This is the email address for the realm's administrator.

       -args
	   This is a set of command-line arguments passed to the realm's rollover manager when the realm is started.

       -configdir
	   This is the realm's configuration directory.  This will contain such files as the DNSSEC-Tools configuration file for that realm.

       -display
	   This indicates if the realm should be included in grandvizier output.

       -inactive
	   This indicates that dtrealms should not start the realm when dtrealms starts.

       -manager
	   This is the rollover manager for the realm.	rollerd is the default rollover manager, but other managers may be used.

       -out output-file
	   The new realm entries will be appended to output-file.  The file will be created if it does not exist.

	   If this option is not given, the new rollrec entries will be written to standard output.

       -realmdir
	   This is the realm's data directory.	This directory is expected to contain the rollrec file, zone files, keyrec files, and key files
	   for the zones in that realm.

       -rollrec
	   This is the path to the realm's rollrec file.  This is used to control rollover actions for the realm.  If it is not an absolute path,
	   it will be assumed to be relative to the realmdir field.

       -statedir
	   This is the realm's state directory.  This will contain such files as that realm's rollrec lock file and the rollerd communications
	   socket.  If the statedir is not defined for a realm, then the realm's configdir is used for that value.

       -user
	   This is the user that the realm is executed as.  (This is not yet implemented in dtrealms.)

       -help
	   Display a usage message.

       -Version
	   Display version information for realminit and DNSSEC-Tools.

EXAMPLES

       The following options should make clear how realminit deals with options and the new realms.  Example 1 will show the complete new realm
       record.	For the sake of brevity, the remaining examples will only show the fields relevant to that example.  Further examples will also
       use short-hand forms of the option names.

   Example 1.  One realm, with -statedir
       This example shows the realm generated by giving realminit a single realm.

	   $ realminit -active -configdir /realms/confs/example -statedir /realms/states/example -realmdir /realms/realms/example -rollrec example.rrf -admin bob@cat.example.com -args "-loglevel phase -logfile logger" example

	   realm       "example"
	       state	       "active"
	       configdir       "/realms/confs/example"
	       statedir        "/realms/states/example"
	       realmdir        "/realms/realms/example"
	       rollrec	       "example.rrf"
	       administrator   "bob@cat.example.com"
	       display	       "1"
	       manager	       "rollerd"
	       args	       "-loglevel phase -logfile logger"

   Example 2.  One realm, without -statedir
       This example shows the realm generated by giving realminit a single realm.

	   $ realminit -active -configdir /realms/confs/example -realmdir /realms/realms/example -rollrec example.rrf -admin bob@cat.example.com -args "-loglevel phase -logfile logger" example

	   realm       "example"
	       state	       "active"
	       configdir       "/realms/confs/example"
	       statedir        "/realms/confs/example"
	       ...

   Example 3.  Two realms, without metacharacters
       This example shows the realms generated by giving realminit two realms, without using the special "=" metacharacter.

	   $ realminit -configdir /realms/confs/example -statedir /realms/states/example -realmdir /realms/realms/example -rollrec example.rrf -admin bob@cat.example.com example test

	   realm       "example"
	       configdir       "/realms/confs/example"
	       statedir        "/realms/states/example"
	       realmdir        "/realms/realms/example"
	       rollrec	       "example.rrf"
	       administrator   "bob@cat.example.com"
	       ...

	   realm       "test"
	       configdir       "/realms/confs/example"
	       statedir        "/realms/states/example"
	       realmdir        "/realms/realms/example"
	       rollrec	       "example.rrf"
	       administrator   "bob@cat.example.com"
	       ...

   Example 4.  Two realms, with metacharacters
       This example shows the realms generated by giving realminit two realms, and that uses the special "=" metacharacter.

	   $ realminit -configdir /realms/confs/= -statedir /realms/states/= -realmdir /realms/realms/= -rollrec =.rrf -admin bob@cat.=.com example test

	   realm       "example"
	       configdir       "/realms/confs/example"
	       statedir        "/realms/states/example"
	       realmdir        "/realms/realms/example"
	       rollrec	       "example.rrf"
	       administrator   "bob@cat.example.com"
	       ...

	   realm       "test"
	       configdir       "/realms/confs/test"
	       statedir        "/realms/states/test"
	       realmdir        "/realms/realms/test"
	       rollrec	       "test.rrf"
	       administrator   "bob@cat.test.com"
	       ...

COPYRIGHT

       Copyright 2012 SPARTA, Inc.  All rights reserved.  See the COPYING file included with the DNSSEC-Tools package for details.

AUTHOR

       Wayne Morrison, tewok@tislabs.com

SEE ALSO

       lsrealm(1), dtrealms(8), realmchk(8)

       Net::DNS::SEC::Tools::realm.pm(3),

       file-realmrec.pm(5)

perl v5.14.2							    2012-06-21							     REALMINIT(1p)