Provided by: dnssec-tools_2.0-1_all bug

NAME

       blinkenlights - DNSSEC-Tools rollerd GUI

SYNOPSIS

         blinkenlights <rollrec-file>

DESCRIPTION

       blinkenlights is a GUI tool for use with monitoring and controlling the DNSSEC-Tools
       rollerd program.  It displays information on the current state of the zones rollerd is
       managing.  The user may control some aspects of rollerd's execution using blinkenlights
       menu commands.

       blinkenlights creates a window in which to display information about each zone rollerd is
       managing.  (These zones are those in rollerd's current rollrec file.)  As a zone's
       rollover status changes, blinkenlights will update its display for that zone.  Skipped
       zones, zones listed in the rollrec file but which are not in rollover or normal operation,
       are displayed but have very little useful information to display.

       The user may also select a set of zones to hide from the display.  These zones, if in the
       rolling state, will continue to roll; however, their zone information will not be
       displayed.  Display state for each zone will persist across blinkenlights executions.

       Menu commands are available for controlling rollerd.  The commands which operate on a
       single zone may be executed by keyboard shortcuts.  The zone may be selected either by
       clicking in its "zone stripe" or by choosing from a dialog box.  Display and execution
       options for blinkenlights are also available through menu commands.  More information
       about the menu commands is available in the MENU COMMANDS section.

       blinkenlights is only intended to be started by rollerd, not directly by a user.  There
       are two ways to have rollerd start blinkenlights.  First, rollctl may be given the
       -display option.  Second, the -display option may be given on rollerd's command line.

OPTIONS

       blinkenlights takes the following options:

       -display
           Tells rollerd to execute blinkenlights as a child process.

       -maxzones
           Tells blinkenlights how many zones to display.

       -Version
           Displays the version information for blinkenlights and the DNSSEC-Tools package.

       -help
           Displays a usage message and exits.

SCREEN LAYOUT

       The blinkenlights window is laid out as a series of "stripes".  The top stripe contains
       status information about rollerd, the second stripe contains column headers, and the bulk
       of the window consists of zone stripes.  The list below provides more detail on the
       contents of each stripe.

       See the WINDOW COLORS section for a discussion of the colors used for the zone stripes.

       •   rollerd information stripe

           The information stripe contains five pieces of information:  rollerd's current rollrec
           file, the count of rolling zones, the count of skipped zones, the count of zones to be
           displayed, and the amount of time rollerd waits between processing its queue.
           Coincidentally, that last datum is also the amount of time between blinkenlights
           screen updates.

       •   column headers stripe

           This stripe contains the column headers for the columns of each zone stripe.

       •   zone stripes

           Each zone managed by rollerd (i.e., every zone in the current rollrec file) will have
           a zone stripe which describes that zone's current state.  The stripe is divided into
           three sections:  zone identification, the current rollover state, and the zone's
           DNSSEC keys.

           The zone identification section contains the name of the zone, the name of the zone's
           rollrec entry, and the zone's zonegroup.

           The rollover state section contains the rollover phase number, a text explanation of
           the phase, and the amount of time remaining in that rollover phase.  The phase
           explanation is "normal operation" when the zone isn't currently in rollover.

           The DNSSEC key section contains two subsections, one for the zone's ZSK keys and
           another for the zone's KSK keys.  Each subsection contains the names of the signing
           sets active for the zone.  The ZSK subsection lists the Current, Published, and New
           ZSK keys; the KSK subsection lists the Current and Published.

           See the WINDOW COLORS section for a discussion of the colors used for the zone
           stripes.

WINDOW COLORS

       The default blinkenlights configuration uses window coloring to provide visual cues and to
       aid in easily distinguishing zone information.  The default window coloring behavior gives
       each zone stripe has its own color and the rollover state section of each zone stripe is
       shaded to show the zone's phase.  Window coloring can be turned off (and on) with
       configuration options and menu commands.

   Color Usage
       The two window coloring behaviors are discussed more fully below:

       •   zone stripe colors

           Each rolling zone's stripe is given one of three colors:  blue, red, or green.  The
           color is assigned on a top-down basis and the colors wrap if there are more than three
           zones.  So, the first zone is always blue, the second zone red, the third zone green,
           the fourth zone blue, etc.

           The colors do not stay with a particular zone.  If a rolling zone becomes a skipped
           zone, the zone stripes will be reassigned new colors to account for that skipped zone.

           Skipped zones are not colored with these three colors.  Stripes for skipped zones are
           colored either grey or a color set in the configuration file.  If you choose to use a
           non-standard color for skipped zones your should ensure that it is not one of the
           colors used for rolling zones' stripes.  Modifying the skipcolor configuration field
           allows the skipped-zone color to be changing.

           The colors configuration field can be used to turn on or off the use of colors for
           zone stripes.  If stripe coloring is turned off, then every stripe will be displayed
           using the skipcolor color.

       •   rollover-state shading

           The only portion of a zone stripe that changes color is the status column; the color
           of the rest of the zone stripe stays constant.  Before a zone enters rollover, the
           status column is the same color as the rest of the stripe.  When the zone enters
           rollover, the status column's color is changed to a very light shade of the stripe's
           normal color.  As the rollover phases progress towards rollover completion, the status
           column's shade darkens.  Once rollover completes, the status column returns again to
           the same shade as the rest of that stripe.

           The shading configuration field can be used to turn on or off the use of shading in
           the rollover-state column.  If shading is turned off, then the zone stripe will be a
           solid color.

           See the CONFIGURATION FILE section for information on setting the configuration
           fields.

   Colors Used
       The color names are taken from the X11 rgb.txt file (X11 1.1.3 - XFree86 4.4.0 for MacOS
       X.)  If these aren't available in your rgb.txt file, similar names should be selected.
       The actual red/green/blue values used are given below to assist in finding suitable
       replacements.  These values were taken from the rgb.txt file.

       Blue Shades:

           blue                0   0 255
           lightblue2        178 223 238
           darkslategray1    151 255 255
           skyblue1          135 206 255
           steelblue1         99 184 255
           turquoise1          0 245 255
           cornflower blue   100 149 237
           dodger blue        30 144 255

       Red Shades:

           red               255   0   0
           pink              255 192 203
           lightsalmon1      255 160 122
           tomato            255  99  71
           indianred         205  92  92
           violetred1        255  62 150
           orangered1        255  69   0
           firebrick1        255  48  48

       Green Shades:

           green               0 255   0
           darkseagreen1     193 255 193
           darkolivegreen1   202 255 112
           lightgreen        144 238 144
           seagreen1          84 255 159
           spring green        0 255 127
           greenyellow       173 255  47
           lawngreen         124 252   0

MENU COMMANDS

       A number of menu commands are available to control the behavior of blinkenlights and to
       send commands to rollerd.  These commands are discusses in this section.

   File Menu
       The commands in this menu are basic GUI commands.

       •   Halt Rollerd After Current Operations

           rollerd's execution is halted after completing its current set of zone operations.  As
           a result, blinkenlights' execution will also be halted.

       •   Halt Rollerd Now

           rollerd's execution is halted immediately.  As a result, blinkenlights' execution will
           also be halted.  If rollerd's command queue already contains a set of commands, they
           may be processed prior to this command.

       •   Quit

           blinkenlights will stop execution.

   Options Menu
       The commands in this menu control the appearance and behavior of blinkenlights.

       •   Row Colors (toggle)

           This menu item is a toggle to turn on or off the coloring of zone stripes.  If row
           coloring is turned off, zone stripes will all be the same color.  If row coloring is
           turned on, zone stripes will be displayed in varying colors.  See the WINDOW COLORS
           section for a discussion of row coloring.

       •   Status Column Shading (toggle)

           This menu item is a toggle to turn on or off the shading of the zone status column.
           If shading is turned off, the zone stripes will present a solid, unchanging band of
           color for each zone.  If shading is turned on, the color of the zone status column
           will change according to the zone's rollover state.

       •   Skipped Zones Display (toggle)

           This menu item is a toggle to turn on or off the display of skipped zones.  If display
           is turned off, zone stripes for skipped zones will not be displayed.  If display is
           turned on, zone stripes for all zones will be displayed.

       •   Status Times Display (toggle)

           This menu item is a toggle to turn on or off the display of status times.  If display
           is turned off, the remaining time for a rollover phase will not be displayed in the
           "Status" column.  If display is turned on, the remaining times will be displayed.

       •   Modification Commands (toggle)

           In some situations, it may be desirable to turn off blinkenlights' ability to send
           commands to rollerd.  This menu item is a toggle to turn on or off this ability.  If
           the commands are turned off, then the "ZSK Control" and "KSK Control" menus and their
           keyboard shortcuts are disabled.  If the commands are turned on, then the "ZSK
           Control" and "KSK Control" menus and their keyboard shortcuts are enabled.

       •   Font Size

           This menu item allows selection of font size of text displayed in the main window.

           Normally, changing the font size causes the window to grow and shrink as required.
           However, on Mac OS 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.

       •   Zones to Display

           This menu item allows selection of the number of zones to be displayed in the main
           window.

   General Control Menu
       The commands in this menu are GUI interfaces for the rollctl commands related to general
       zone management.

       •   Sign Selected Zone

           rollerd is instructed to sign the selected zone.  The zone will only be signed; no key
           rollover will occur.

       •   Sign All Zones

           rollerd is instructed to sign all the zones it manages.  The zone will only be signed;
           no key rollover will occur.

       •   Sign Active Zones

           rollerd is instructed to sign all the zones it manages.  Skipped zones will not be
           signed.  The zone will only be signed; no key rollover will occur.

       •   Run the Queue

           rollerd is awoken and runs through its queue of zones.  The operation required for
           each zone is then performed.

       •   Skip Selected Zone

           The selected zone will be moved to the skipped state.  This only has an effect on
           rolling zones.  A zone may be selected by clicking on its zone stripe.  If this
           command is selected without a zone having been selected, a dialog box is displayed
           from which a currently rolling zone may be chosen.

       •   Skip All Zones

           All zones will be moved to the skipped state.  This has no effect on currently skipped
           zones.

       •   Restart Selected Skipped Zone

           The selected zone will be moved from the skipped state to the roll state.  The zone
           will re-enter the roll state at the same point from which it entered the skip state;
           it will not be moved to the beginning of either KSK or ZSK rollover.  This only has an
           effect on skipped zones.  A zone may be selected by clicking on its zone stripe.  If
           this command is selected without a zone having been selected, a dialog box is
           displayed from which a currently skipped zone may be chosen.

       •   Restart All Skipped Zones

           All zones will be moved from the skipped state to the roll state.  The zones will re-
           enter the roll state at the same point from which they entered the skip state; they
           will not be moved to the beginning of either KSK or ZSK rollover.  This has no effect
           on currently rolling zones.

   ZSK Control Menu
       The commands in this menu are GUI interfaces for the rollctl commands related to ZSK-
       specific zone management.

       •   Roll Selected Zone's ZSK

           The selected zone's ZSK will be moved to the rollover state.  This has no effect on
           zones that are already in rollover.  A zone may be selected by clicking on its zone
           stripe.  If this command is selected without a zone having been selected, a dialog box
           is displayed from which a currently skipped zone may be chosen.

       •   Roll All Zones' ZSKs

           All zones' ZSKs will be moved to the rollover state.  This has no effect on currently
           rolling zones.

   KSK Control Menu
       The commands in this menu are GUI interfaces for the rollctl commands related to KSK-
       specific zone management.

       •   DS Published for Selected Zone

           This command is used to indicate that the selected zone's parent has published a new
           DS record for the zone.  It moves the zone from phase 5 to phase 6 of KSK rollover.

       •   DS Published for All Zones

           This command is used to indicate that all the zones in KSK rollover phase 5 have new
           DS records published by their parents.  It moves all these zones from phase 5 to phase
           6 of KSK rollover.  There is no effect on zones not in KSK rollover phase 5.

       •   Roll Selected Zone's KSK

           The selected zone's KSK will be moved to the rollover state.  This has no effect on
           zones that are already in rollover.  A zone may be selected by clicking on its zone
           stripe.  If this command is selected without a zone having been selected, a dialog box
           is displayed from which a currently skipped zone may be chosen.

       •   Roll All Zones' KSKs

           All zones' KSKs will be moved to the rollover state.  This has no effect on currently
           rolling zones.

   Display Menu
       The commands in this menu provide control over what is being displayed.  There are
       commands for displaying and hiding both zone stripes, columns of key sets, columns of
       rollrec names, and columns of zonenames.

       The zonestripe commands allow all, some, or none of the zone stripes to be displayed.
       Undisplayed rolling zones will continue to roll, but they will do so without the
       blinkenlights window indicating this.

       The data column commands allow individual columns of data to be hidden or displayed.  The
       zone status column may not be hidden.  Only one of the rollrec name and zonename columns
       may be hidden at a time.

       •   Zone Selection

           A dialog box is displayed that holds a list of the zones currently managed by rollerd.
           The user may select which zones should be displayed by clicking on the zone's
           checkbox.  Zones with a selected checkbox will be displayed; zones without a selected
           checkbox will not be displayed.

       •   Display All Zones

           All zones will be displayed in the blinkenlights window.

       •   Hide All Zones

           No zones will be displayed in the blinkenlights window.

       •   Rollrec Name (toggle)

           This menu item is a toggle to turn on or off the display of rollrec names.  If display
           is turned off, the column holding the rollrec names will be removed from the display
           and the display window will shrink.  If display is turned on, the column holding the
           rollrec names will be restored to the display and the display window will be expanded.

           When displayed, the rollrec names will always be the leftmost columns.

       •   Zone Name (toggle)

           This menu item is a toggle to turn on or off the display of the zone names in a
           rollrec entry.  If display is turned off, the column holding the zone names will be
           removed from the display and the display window will shrink.  If display is turned on,
           the column holding the zone names will be restored to the display and the display
           window will be expanded.

           When displayed, the zone name will always be the second-from left or leftmost column,
           depending on if the rollrec name is also being displayed.

       •   Zonegroup Name (toggle)

           This menu item is a toggle to turn on or off the display of the zoneground in rollrec
           entries.  If display is turned off, the column holding the rollrec names will be
           removed from the display and the display window will shrink.  If display is turned on,
           the column holding the rollrec names will be restored to the display and the display
           window will be expanded.

           When displayed, the rollrec names will always be the in one of the first through third
           columns, depending on if the rollrec name and zone name are also being displayed.

       •   KSK Sets (toggle)

           This menu item is a toggle to turn on or off the display of KSK signing set names.  If
           display is turned off, the columns holding the KSK signing set names and labels will
           be removed from the display and the display window will shrink.  If display is turned
           on, the columns holding the KSK signing set names and labels will be restored to the
           display and the display window will be expanded.

           When displayed, KSK signing sets will always be the rightmost columns.

       •   ZSK Sets (toggle)

           This menu item is a toggle to turn on or off the display of ZSK signing set names.  If
           display is turned off, the columns holding the ZSK signing set names and labels will
           be removed from the display and the display window will shrink.  If display is turned
           on, the columns holding the ZSK signing set names and labels will be restored to the
           display and the display window will be expanded.

           When displayed, ZSK signing sets will always be immediately to the right of the zone
           status column.

       •   Hide All Keysets

           Turns off display of the KSK and ZSK signing set names.

       •   Show All Keysets

           Turns on display of the KSK and ZSK signing set names.

       •   Refresh Display

           Refresh the blinkenlights display.  The display will automatically refresh after a
           certain number of updates; this command forces it to happen immediately upon
           invocation.

   Help Menu
       The commands in this menu provide assistance to the user.

       •   Help

           Display a window containing help information.

       •   About Blinkenlights

           Display a window containing version information on blinkenlights and DNSSEC-Tools.

CONFIGURATION FILE

       Several aspects of blinkenlights' behavior may be controlled from configuration files.
       Configuration value may be specified in the DNSSEC Tools configuration file or in a more
       specific rc.blinkenlights.  The system-wide blinkenlights configuration file is in the
       DNSSEC-Tools configuration directory and is named blinkenlights.conf.  Multiple
       rc.blinkenlights files may exist on a system, but only the one in the directory in which
       blinkenlights is executed is used.

       The following are the available configuration values:

           colors      Turn on/off use of colors on zone stripes.
           fontsize    The size of the font in the output window.
           maxzones    The number of zones to display.
           modify      Turn on/off execution of rollerd modification commands.
           noshow      Turn off display of particular columns.
           shading     Turn on/off shading of the status columns.
           showskip    Turn on/off display of skipped zones.
           skipcolor   The background color used for skipped zones.

       The rc.blinkenlights file is only searched for in the directory in which blinkenlights is
       executed.  The potential problems inherent in this may cause these blinkenlights-specific
       configuration files to be removed in the future.

       This file is in the "field value" format, where field specifies the output aspect and
       value defines the value for that field.  The following are the recognized fields:

       Empty lines and comments are ignored.  Comment lines are lines that start with an
       octothorpe ('#').

       Spaces are not allowed in the configuration values.

       Choose your skipcolors carefully.  The only foreground color used is black, so your
       background colors must work well with black.

       The noshow command controls display of the various data columns.  The command valid values
       are:

           rollrecs    Turn off display of the rollrec names column.
                       This value may not be used with "noshow zonenames".
           zonenames   Turn off display of the zonenames column.
                       This value may not be used with "noshow rollrecs".
           zonegroups  Turn off display of the zonegroups column.
           kskset      Turn off display of the KSK signing set columns.
           zskset      Turn off display of the ZSK signing set columns.
           keysets     Turn off display of the KSK and ZSK signing set columns.

REQUIREMENTS

       blinkenlights is implemented in Perl/Tk, so both Perl and Perl/Tk must be installed on
       your system.

WARNINGS

       blinkenlights has several potential problems that must be taken into account.

       development environment
           blinkenlights 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 blinkenlights user.

       long-term performance issues
           In early tests, the longer blinkenlights runs, the slower the updates become.  This is
           probably a result of the Tk implementation or the way Tk interfaces with X11.  This is
           pure supposition, though.

           This performance impact is affected by a number of things, such as the number of zones
           managed by rollerd and the length of rollerd's sleep interval.  Large numbers of zones
           or very short sleep intervals will increase the possibility of blinkenlights'
           performance degrading.

           This appears to have been resolved by periodically performing a complete rebuild of
           the screen.  blinkenlights keeps track of the number of screen updates it makes and
           rebuilds the screen when this count exceeds a threshold.  The threshold is built into
           blinkenlights and stored in the $paintmax variable.  This threshold may be adjusted if
           there are too many screen rebuilds or if blinkenlights' performance slows too much.
           Raising the number will reduce the screen rebuilds; lowering the number will (may)
           increase performance.

       display irregularities
           If the user modifies the number of zones to be displayed, then sometimes the
           blinkenlights window is left in an irregular state.  The requested number of zones are
           displayed, but there is a large grey void above and below the zone display.  This is
           an occasional problem and will be fixed as time allows.

COPYRIGHT

       Copyright 2006-2013 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

       bubbles(8), rollctl(8), rollerd(8), zonesigner(8)

       Net::DNS::SEC::Tools::timetrans(3)

       Net::DNS::SEC::Tools::keyrec(5), Net::DNS::SEC::Tools::rollrec(5),