.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GRANDVIZIER 1p"
.TH GRANDVIZIER 1p "2012-06-21" "perl v5.14.2" "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"
grandvizier \- DNSSEC\-Tools dtrealms GUI
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  grandvizier <realms\-file>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1THIS\s0 \s-1NEEDS\s0 \s-1MAJOR\s0 \s-1EDITTING\s0!!!\fR
.PP
\&\fBWarning:\fR  This is an early prototype.  Consider it to be beta quality, if 
not alpha.
.PP
\&\fBgrandvizier\fR is a \s-1GUI\s0 tool for use with monitoring and controlling the
DNSSEC-Tools \fBdtrealms\fR program.  It displays information on the current state
of the realms \fBdtrealms\fR is managing.  The user may control some aspects of
\&\fBdtrealms\fR's execution using \fBgrandvizier\fR menu commands.
.PP
\&\fBgrandvizier\fR creates a window in which to display information about each
realms.  (These realms are those in \fBdtrealms\fR's current \fIrealms\fR file.) For
each realm, it displays the realm name and the count of zones in each of these
four states:  normal, \s-1ZSK\s0 rollover, \s-1KSK\s0 rollover, and \s-1KSK\s0 phase 6 wait state.
As the rollover status of the zones in each realm changes, \fBgrandvizier\fR will
update its display for that realm.  Inactive realms, realms listed in the
\&\fIrealms\fR file but which are not in currently being run, are displayed but
have no useful information to display.
.PP
The user may also hide realms from the display.  These realms, if in the
active state, will continue to execute; however, their information will not be
displayed.  Display state for each realm will persist across \fBgrandvizier\fR
executions.
.PP
Menu commands are available for some control over \fBdtrealms\fR.  Display and
execution options for \fBgrandvizier\fR are also available through menu commands.
More information about the menu commands is available in the \s-1MENU\s0 \s-1COMMANDS\s0
section.
.PP
\&\fBgrandvizier\fR is only intended to be started by \fBdtrealms\fR, not directly by
a user.  There are two ways to have \fBdtrealms\fR start \fBgrandvizier\fR.  First,
\&\fBrealmctl\fR may be given the \fB\-display\fR option.  Second, the \fB\-display\fR
option may be given on \fBdtrealms\fR' command line.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fBgrandvizier\fR takes the following options:
.IP "\fB\-display\fR" 4
.IX Item "-display"
Tells \fBdtrealms\fR to execute \fBgrandvizier\fR as a child process.
.IP "\fB\-maxrealms\fR" 4
.IX Item "-maxrealms"
Tells \fBgrandvizier\fR how many realms to display.
.IP "\fB\-Version\fR" 4
.IX Item "-Version"
Displays the version information for \fBgrandvizier\fR and the DNSSEC-Tools
package.
.IP "\fB\-help\fR" 4
.IX Item "-help"
Displays a usage message and exits.
.SH "SCREEN LAYOUT"
.IX Header "SCREEN LAYOUT"
The \fBgrandvizier\fR window is laid out as a series of \*(L"stripes\*(R".  The top
stripe contains status information about \fBdtrealms\fR, the second stripe
contains column headers, and the bulk of the window consists of realm stripes.
The list below provides more detail on the contents of each stripe.
.PP
See the \s-1ROW\s0 \s-1COLORS\s0 section for a discussion of the colors used for the
zone stripes.
.IP "\(bu" 4
\&\fBdtrealms\fR information stripe
.Sp
The information stripe contains five pieces of information:  \fBdtrealms\fR's
current \fIrealms\fR file, the count of rolling zones, the count of stopped
zones, the count of zones to be displayed, and the amount of time \fBdtrealms\fR
waits between processing its queue.  Coincidentally, that last datum is also
the amount of time between \fBgrandvizier\fR screen updates.
.IP "\(bu" 4
column headers stripe
.Sp
This stripe contains the column headers for the columns of each realm stripe.
.IP "\(bu" 4
realm stripes
.Sp
Each realm managed by \fBdtrealms\fR (i.e., every realm in the current \fIrealms\fR
file) will have a realm stripe which describes that realm's current state.
The stripe is divided into two sections:  realm identification and the realm's
zone counts.
.Sp
The realm identification section contains the name of the realm and the
realm's \fBrollrec\fR file.
.Sp
The realm's zone counts section contains the number of zones in normal state,
\&\s-1ZSK\s0 rollover, \s-1KSK\s0 rollover, and \s-1KSK\s0 phase 6 wait state.
.Sp
See the \s-1ROW\s0 \s-1COLORS\s0 section for a discussion of the colors used for the
realm stripes.
.SH "ROW COLORS"
.IX Header "ROW COLORS"
The default \fBgrandvizier\fR configuration displays each realm in its own row
with a rotating set of colors.  The rows alternate with blue, red, and green,
as defined in the X11 \fBrgb.txt\fR file.  Row coloring can be turned off (and
on) with configuration options and menu commands.
.SH "MENU COMMANDS"
.IX Header "MENU COMMANDS"
A number of menu commands are available to control the behavior of
\&\fBgrandvizier\fR and to send commands to \fBdtrealms\fR.  These commands
are discusses in this section.
.SS "File Menu"
.IX Subsection "File Menu"
The commands in this menu are basic \s-1GUI\s0 commands.
.IP "\(bu" 4
Halt Dtrealms
.Sp
\&\fBdtrealms\fR's execution is halted immediately.  As a result, \fBgrandvizier\fR's
execution will also be halted.
.IP "\(bu" 4
Quit
.Sp
\&\fBgrandvizier\fR will stop execution.
.SS "Options Menu"
.IX Subsection "Options Menu"
The commands in this menu control the appearance and behavior of
\&\fBgrandvizier\fR.
.IP "\(bu" 4
Row Colors (toggle)
.Sp
This menu item is a toggle to turn on or off the coloring of realm stripes.
If row coloring is turned off, realm stripes will all be the same color.
If row coloring is turned on, realm stripes will be displayed in varying
colors.  See the \s-1ROW\s0 \s-1COLORS\s0 section for a discussion of row coloring.
.IP "\(bu" 4
Inactive Realms Display (toggle)
.Sp
This menu item is a toggle to turn on or off the display of inactive realms.
If display is turned off, realm stripes for inactive realms will not be
displayed.  If display is turned on, realm stripes for all realms will be
displayed.
.IP "\(bu" 4
Modification Commands (toggle)
.Sp
In some situations, it may be desirable to turn off \fBgrandvizier\fR' ability
to send commands to \fBdtrealms\fR.  This menu item is a toggle to turn on or
off this ability.
.IP "\(bu" 4
Font Size
.Sp
This menu item allows selection of font size of text displayed in the main
window.
.Sp
Normally, changing the font size causes the window to grow and shrink as
required.  However, on Mac \s-1OS\s0 X there seems to be a problem when the size
selected increases the window size to be greater than will fit on the screen.
If the font size is subsequently reduced, the window size does not shrink in
response.
.IP "\(bu" 4
Realms to Display
.Sp
This menu item allows selection of the number of realms to be displayed in
the main window.
.SS "General Control Menu"
.IX Subsection "General Control Menu"
The commands in this menu are \s-1GUI\s0 interfaces for the \fBrealmctl\fR commands
related to \fIgeneral\fR realm management.
.IP "\(bu" 4
Stop Selected Realm
.Sp
The selected realm will be moved to the inactive state.  This only has an
effect on active realms.
.Sp
A realm may be selected by clicking on its realm stripe.  If this command is
selected without a realm having been selected, a dialog box is displayed from
which a currently active realm may be chosen.
.IP "\(bu" 4
Stop All Realms
.Sp
All realms will be moved to the inactive state.  This has no effect on
currently inactive realms.
.IP "\(bu" 4
Restart Selected Inactive Realm
.Sp
The selected realm will be moved from the inactive state to the active state.
The realm will enter the active state at the same point from which it entered
the inactive state.  This only has an effect on inactive realms.
.Sp
A realm may be selected by clicking on its realm stripe.  If this command is
selected without a realm having been selected, a dialog box is displayed from
which a currently inactive realm may be chosen.
.IP "\(bu" 4
Restart All Stopped Realms
.Sp
All realms will be moved from the inactive state to the roll state.  The
realms will enter the roll state at the same point from which they entered
the inactive state.  This has no effect on currently active realms.
.IP "\(bu" 4
\&\s-1DS\s0 Published for All Zones in Selected Realm
.Sp
This command is used to indicate that all the zones in \s-1KSK\s0 rollover phase 6
in the selected realm have new \s-1DS\s0 records published by their parents.  It
moves all these realms from \s-1KSK\s0 phase 6 to \s-1KSK\s0 phase 7.  There is no effect
on realms not in \s-1KSK\s0 rollover phase 6.
.SS "Display Menu"
.IX Subsection "Display Menu"
The commands in this menu provide control over what is being displayed.
.PP
The realmstripe commands allow all, some, or none of the realm stripes to be
displayed.  Undisplayed active realms will continue to be active, but they will
do so without the \fBgrandvizier\fR window indicating this.
.IP "\(bu" 4
Realm Selection
.Sp
A dialog box is displayed that holds a list of the realms currently managed by
\&\fBdtrealms\fR.  The user may select which realms should be displayed by clicking
on the realm's checkbox.  Realms with a selected checkbox will be displayed;
realms without a selected checkbox will not be displayed.
.IP "\(bu" 4
Refresh Display
.Sp
Refresh the \fBgrandvizier\fR display.  The display will automatically refresh
after a certain number of updates; this command forces it to happen immediately
upon invocation.
.SS "Help Menu"
.IX Subsection "Help Menu"
The commands in this menu provide assistance to the user.
.IP "\(bu" 4
Help
.Sp
Display a window containing help information.
.SH "CONFIGURATION FILE"
.IX Header "CONFIGURATION FILE"
Several aspects of \fBgrandvizier\fR' behavior may be controlled from
configuration files.  Configuration value may be specified in the \s-1DNSSEC\s0 Tools
configuration file or in a more specific \fBrc.grandvizier\fR.  The system-wide
\&\fBgrandvizier\fR configuration file is in the DNSSEC-Tools configuration
directory and is named \fBgrandvizier.conf\fR.  Multiple \fBrc.grandvizier\fR
files may exist on a system, but only the one in the directory in which
\&\fBgrandvizier\fR is executed is used.
.PP
The following are the available configuration values:
.PP
.Vb 6
\&    colors              Turn on/off use of colors on realm stripes.
\&    fontsize            The size of the font in the output window.
\&    inactivecolor       The background color used for inactive zones.
\&    maxrealms           The number of realms to display.
\&    modify              Turn on/off execution of dtrealms modification commands.
\&    showinactive        Turn on/off display of inactive zones.
.Ve
.PP
The \fBrc.grandvizier\fR file is \fBonly\fR searched for in the directory in
which \fBgrandvizier\fR is executed.  The potential problems inherent in
this may cause these \fBgrandvizier\fR\-specific configuration files to be
removed in the future.
.PP
This file is in the \*(L"field value\*(R" format, where \fIfield\fR specifies the output
aspect and \fIvalue\fR defines the value for that field.  The following are the
recognized fields:
.PP
Empty lines and comments are ignored.  Comment lines are lines that start
with an octothorpe ('#').
.PP
Spaces are not allowed in the configuration values.
.PP
Choose your inactivecolors carefully.  The only foreground color used is
black, so your background colors must work well with black.
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
\&\fBgrandvizier\fR is implemented in Perl/Tk, so both Perl and Perl/Tk must be
installed on your system.
.SH "WARNINGS"
.IX Header "WARNINGS"
\&\fBgrandvizier\fR has several potential problems that must be taken into
account.
.IP "development environment" 4
.IX Item "development environment"
\&\fBgrandvizier\fR was developed and tested on a single-user system running X11
using a relatively small number of zones.  While it works fine in this
environment, it has not been run on a system with many users or in a situation
where the system console hasn't been in use by the \fBgrandvizier\fR user.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2012 \s-1SPARTA\s0, Inc.  All rights reserved.
See the \s-1COPYING\s0 file included with the DNSSEC-Tools package for details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Wayne Morrison, tewok@tislabs.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB\f(BIdtrealms\fB\|(8)\fR,
\&\fB\f(BIrealmctl\fB\|(8)\fR,
\&\fB\f(BIrollerd\fB\|(8)\fR
.PP
\&\fB\f(BINet::DNS::SEC::Tools::realm\fB\|(5)\fR