.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ROLLREC-EDITOR 1"
.TH ROLLREC-EDITOR 1 2023-07-29 "perl v5.38.0" "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
rollrec\-editor \- DNSSEC\-Tools Rollrec GUI Editor
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  rollrec\-editor [options] <rollrec\-file>
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBrollrec-editor\fR provides the capability for easy GUI-based management of
\&\fIrollrec\fR files.  A \fBrollrec\fR file contains one or more \fIrollrec\fR records.
These records are used by the DNSSEC-Tools rollover utilities (\fBrollerd\fR,
etc.) to describe zones' rollover state.  Each zone's \fIrollrec\fR record
contains such information as the zone file, the rollover phase, and logging
level.  \fIrollrec\fR files are text files and may be edited by any text editor.
\&\fBrollrec-editor\fR allows editing of only those records a user should change
and performs error checking on the data.
.PP
When \fBrollrec-editor\fR starts, a window is created that has "buttons" for each
\&\fIrollrec\fR record in the given \fIrollrec\fR file.  (In this documentation, this
window is called the Button Window.)  Clicking on the buttons selects (or
deselects) that zone.  After one or more zones are selected, one of several
commands may be executed.  Commands allow modification and deletion of
existing \fIrollrec\fR records, creation of new \fIrollrec\fR records, merging of
\&\fIrollrec\fR files, and verification of file validity.
.PP
\&\fBrollrec-editor\fR's commands are available through the menus and most have a
keyboard accelerator.  The commands are described below in the COMMANDS
section.
.PP
When a \fIrollrec\fR record is selected for modification, a new window is created
to hold the editable fields of the record.  The fields may be modified in
place.  When editing is complete, the record is "saved".  This does not save
the modified \fIrollrec\fR into its on-disk file; the file must be saved
explicitly from the Button Window.
.PP
As stated above, verification checks are performed when saving an edited
\&\fIrollrec\fR record.  One set of checks ensures that files and directories
associated with a zone actually exist.  This check may be turned off at
command start-up with the \fB\-ignore\-warns\fR command line option.  It may be
modified during execution with the "Ignore Edit Warnings" menu command.
.SS "Button Window Layout"
.IX Subsection "Button Window Layout"
The Button Window contains a button for each \fIrollrec\fR record in the
selected file.  The buttons are arranged in a table that with at least three
columns.  The number of columns may be set at command start-up with the 
\&\fB\-columns\fR command line option.  It may be modified during execution with
the "Columns in Button Window" menu command.
.PP
When setting the number of columns, \fBrollrec-editor\fR minimizes the space
required to display the selected file's \fIrollrec\fR buttons.  This will
sometimes cause the number of columns to differ from that requested.
.PP
For example, assume a \fIrollrec\fR file has 12 \fIrollrec\fR records.  The
following table shows how many rows and columns are given for each of
the given column selections.
.PP
.Vb 10
\&        column count    rows    columns
\&              1          12        1
\&              2          6         2
\&              3          4         3
\&              4          3         4
\&              5          3         4
\&              6          2         6
\&              7          2         6
\&              8          2         6
\&              9          2         6
\&              10         2         6
\&              11         2         6
\&              12         1         12
.Ve
.PP
The actual rows and columns for a requested column count will vary in order
to allow a "best-fit".
.SS "UNDOING MODIFICATIONS"
.IX Subsection "UNDOING MODIFICATIONS"
\&\fBThe "undo" capability is not currently implemented.\fR
.PP
\&\fBrollrec-editor\fR has the ability to reverse modifications it has made to a
\&\fIrollrec\fR file.  This historical restoration will only work for modifications
made during a particular execution of \fBrollrec-editor\fR; modifications made
during a previous execution may not be undone.
.PP
After a "Save" operation, the data required for reversing modifications are
deleted.  This is not the case for the "Save As" operation.
.SH OPTIONS
.IX Header "OPTIONS"
\&\fBrollrec-editor\fR supports the following options.
.IP "\fB\-columns columns\fR" 4
.IX Item "-columns columns"
This option allows the user to specify the number of columns to be used in
the Button Window.
.IP \fB\-ignore\-warns\fR 4
.IX Item "-ignore-warns"
This option causes \fBrollrec-editor\fR to ignore edit warnings when performing
validation checks on the contents of \fIrollrec\fR records.
.IP \fB\-no\-filter\fR 4
.IX Item "-no-filter"
This option turns off name filtering when \fBrollrec-editor\fR presents a
file-selection dialog for choosing a new \fIrollrec\fR file.  If this option
is not given, then the file-selection dialog will only list regular files
with a suffix of \fB.rrf\fR.
.IP \fB\-Version\fR 4
.IX Item "-Version"
Displays the version information for \fBrollrec-editor\fR and the DNSSEC-Tools
package.
.SH COMMANDS
.IX Header "COMMANDS"
\&\fBrollrec-editor\fR provides the following commands, organized by menus:
File, Edit, Commands, Rollrecs, and Options.
.SS "File Menu"
.IX Subsection "File Menu"
The File Menu contains commands for manipulating \fIrollrec\fR files and
stopping execution.
.IP \fBOpen\fR 4
.IX Item "Open"
Open a new \fIrollrec\fR file.  If the specified file does not exist, the user
will be prompted for the action to take.  If the user chooses the "Continue"
action, then \fBrollrec-editor\fR will continue editing the current \fIrollrec\fR
file.  If the "Quit" action is selected, then \fBrollrec-editor\fR will exit.
.IP \fBSave\fR 4
.IX Item "Save"
Save the current \fIrollrec\fR file.  The data for the "Undo Changes" command are
purged, so this file will appear to be unmodified.
.Sp
Nothing will happen if no changes have been made.
.IP "\fBSave As\fR" 4
.IX Item "Save As"
Save the current \fIrollrec\fR file to a name selected by the user.
.IP \fBQuit\fR 4
.IX Item "Quit"
Exit \fBrollrec-editor\fR.
.SS "Edit Menu"
.IX Subsection "Edit Menu"
The Edit Menu contains commands for general editing operations.
.IP "\fBUndo Changes\fR" 4
.IX Item "Undo Changes"
Reverse modifications made to the \fIrollrec\fR records.  This is \fBonly\fR
for the in-memory version of the \fIrollrec\fR file.
.Sp
\&\fBNot currently implemented.\fR
.SS "Commands Menu"
.IX Subsection "Commands Menu"
The Commands Menu contains commands for modifying \fIrollrec\fR records.
.IP "\fBNew Rollrec\fR" 4
.IX Item "New Rollrec"
Create a new \fIrollrec\fR record.   The user is given a new window in which to
edit the user-modifiable \fIrollrec\fR fields.  A button for the new \fIrollrec\fR
record will be inserted into the Button Window.
.Sp
After editing is completed, the "Save" button will add the new \fIrollrec\fR
record to the in-memory \fIrollrec\fR file.  The file must be saved in order to
have the new \fIrollrec\fR added to the file.
.Sp
Potentially erroneous conditions will be reported to the user at save time.  
If the \fIignore-warnings\fR flag has been turned on, then these warnings will
not be reported.  Errors (e.g., invalid log conditions) will always be
reported.
.IP "\fBDelete Selected Rollrecs\fR" 4
.IX Item "Delete Selected Rollrecs"
Delete the selected \fIrollrec\fR records.  The buttons for each selected record
will be removed from the Button Window.
.IP "\fBEdit Selected Rollrecs\fR" 4
.IX Item "Edit Selected Rollrecs"
Modify the selected \fIrollrec\fR records.   For every record selected
for modification, the user is given a new window in which to edit the
user-modifiable \fIrollrec\fR fields.  When the edit window goes away (after a
"Save" or "Cancel"), the \fIrollrec\fR record's button is deselected.
.Sp
After editing is completed, the "Save" button will add the new \fIrollrec\fR
record to the in-memory \fIrollrec\fR file.  The file must be saved in order to
have the new \fIrollrec\fR added to the file.
.Sp
Potentially erroneous conditions will be reported to the user at save time.  
If the \fIignore-warnings\fR flag has been turned on, then these warnings will
not be reported.  Errors (e.g., invalid log conditions) will always be
reported.
.IP "\fBRename Selected Rollrec\fR" 4
.IX Item "Rename Selected Rollrec"
Rename the selected \fIrollrec\fR record.   The name in the \fIrollrec\fR's "roll"
or "skip" line will be changed to the new name.  Only one \fIrollrec\fR may be
renamed at a time, and it may not be edited while the rename is taking place.
.Sp
If the \fIrollrec\fR has been modified, the new contents \fBmust\fR be written to
disk prior to the rename happening.  The user will be prompted to ensure that
this the user wishes to continue.
.IP "\fBMerge Rollrec Files\fR" 4
.IX Item "Merge Rollrec Files"
Merge a \fIrollrec\fR file with the currently open \fIrollrec\fR file.  After a
successful merge, the \fIrollrec\fR records in the second file will be added 
to the \fIend\fR of the currently open \fIrollrec\fR file.
.Sp
If there are any \fIrollrec\fR name collisions in the files, then the user will
be asked whether to continue with the merge or cancel it.  If the merge
continues, then the conflicting \fIrollrec\fR records from the "new" file will be
discarded in favor of the currently open \fIrollrec\fR file.
.IP "\fBVerify Rollrec File\fR" 4
.IX Item "Verify Rollrec File"
Verify the validity of the \fIrollrec\fR file.  The user-editable fields in the
open \fIrollrec\fR file are checked for validity.  An edit window is opened for
each \fIrollrec\fR record that registers an error or warning.
.Sp
If the \fIignore-warnings\fR flag has been turned on, then potentially erroneous
conditions will not be reported.  Errors (e.g., invalid log conditions) will
always be reported.
.IP "\fBSummarize Problems\fR" 4
.IX Item "Summarize Problems"
Summarize the warning and error counts of the \fIrollrec\fR file.  Each
\&\fIrollrec\fR record in the open \fIrollrec\fR file is checked for validity.  If
any warnings or errors are found, a window is displayed that lists the name
of each \fIrollrec\fR record and its warning and error counts.
.Sp
If the \fIignore-warnings\fR flag has been turned on, then potentially erroneous
conditions will not be reported.  Errors (e.g., invalid log conditions) will
always be reported.
.SS "View Menu"
.IX Subsection "View Menu"
The View Menu contains miscellaneous commands for viewing edit windows.
.IP "\fBSelect All Rollrecs/Unselect All Rollrecs\fR" 4
.IX Item "Select All Rollrecs/Unselect All Rollrecs"
Select or unselect all \fIrollrec\fR buttons.  All the buttons in the Button
Window will be selected or unselected.  If \fBany\fR of the buttons are not
selected, this command will cause all the buttons to become selected.  If
\&\fIall\fR of the buttons are selected, this command will cause all the buttons
to be deselected.
.Sp
This command is a toggle that switches between Select All Rollrecs and
Unselect All Rollrecs.
.IP "\fBReveal Rollrec Edit Windows\fR" 4
.IX Item "Reveal Rollrec Edit Windows"
Raise all \fIrollrec\fR edit windows.  This command brings all \fIrollrec\fR edit
windows to the front so that any that are hidden behind other windows will
become visible.
.IP "\fBClose Rollrec Edit Windows\fR" 4
.IX Item "Close Rollrec Edit Windows"
Close all \fIrollrec\fR edit windows.  This command closes and deselects all
\&\fIrollrec\fR edit windows.
.SS "Options Menu"
.IX Subsection "Options Menu"
The Options Menu allows the user to set several options that control
\&\fBrollrec-editor\fR behavior.
.IP "\fBIgnore Edit Warnings/Don't Ignore Edit Warnings\fR" 4
.IX Item "Ignore Edit Warnings/Don't Ignore Edit Warnings"
Certain operations perform validation checks on the contents of \fIrollrec\fR
records.  Warnings and errors may be reported by these checks.  This option 
controls whether or not warnings are flagged during validation.  If they
are flagged, then the operation will not continue until the warning condition
is fixed or the operation canceled.  If the warnings are ignored, then the
operation will complete without the condition being fixed.
.Sp
This command is a toggle that switches between Ignore Edit Warnings mode and
Don't Ignore Edit Warnings mode.
.IP "\fBFilter Name Selection/Don't Filter Name Selection\fR" 4
.IX Item "Filter Name Selection/Don't Filter Name Selection"
When opening \fIrollrec\fR files for editing or merging, a file-selection dialog
box is displayed to allow the user to select a \fIrollrec\fR file.  This option
controls whether a filename filter is used by the dialog box.  If Filter Names
Selection mode is used, then only regular files with a suffix of \fB.rrf\fR will
be displayed by the dialog box.  If Don't Filter Name Selection mode is used,
then all regular files will be displayed by the dialog box.
.Sp
This command is a toggle that switches between Filter Name Selection display
and Don't Filter Name Selection display.
.IP "\fBColumns in Button Window\fR" 4
.IX Item "Columns in Button Window"
Set the number of columns used in the Button Window.  See the Button Window
Layout section for more information on columns in the Button Window.
.SS "Help Menu"
.IX Subsection "Help Menu"
The Help Menu contains commands for getting assistance.
.IP \fBHelp\fR 4
.IX Item "Help"
Display a help window.
.SH "KEYBOARD ACCELERATORS"
.IX Header "KEYBOARD ACCELERATORS"
Below are the keyboard accelerators for the \fBrollrec-editor\fR commands:
.PP
.Vb 1
\&    Ctrl\-A  Select All Rollrecs
\&
\&    Ctrl\-D  Delete Selected Rollrecs
\&
\&    Ctrl\-E  Edit Selected Rollrecs
\&
\&    Ctrl\-H  Help
\&
\&    Ctrl\-K  Close Rollrec Edit Windows
\&
\&    Ctrl\-M  Merge Rollrec Files
\&
\&    Ctrl\-N  New Rollrec
\&
\&    Ctrl\-O  Open
\&
\&    Ctrl\-Q  Quit
\&
\&    Ctrl\-R  Reveal Rollrec Edit Windows
\&
\&    Ctrl\-S  Save
\&
\&    Ctrl\-U  Undo Changes  (not currently implemented)
\&
\&    Ctrl\-V  Verify Rollrec File
.Ve
.PP
These accelerators are all lowercase letters.
.SH REQUIREMENTS
.IX Header "REQUIREMENTS"
\&\fBrollrec-editor\fR is implemented in Perl/Tk, so both Perl and Perl/Tk must be
installed on your system.
.SH "KNOWN ISSUES"
.IX Header "KNOWN ISSUES"
The following are known issues.  These will be resolved in the fullness of time.
.IP \(bu 4
There is an issue with the column count and adding new \fIrollrecs\fR.
It doesn't always work properly, thus occasionally leaving some \fIrollrec\fR
buttons undisplayed.
.IP \(bu 4
There is no undo command.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2007\-2014 SPARTA, Inc.  All rights reserved.
See the COPYING 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"
\&\fBlsroll\|(1)\fR,
\&\fBrollchk\|(8)\fR,
\&\fBrollerd\|(8)\fR
\&\fBrollinit\|(8)\fR,
\&\fBrollset\|(8)\fR,
\&\fBzonesigner\|(8)\fR
.PP
\&\fBNet::DNS::SEC::Tools::rollrec\|(3)\fR
.PP
\&\fBfile\-rollrec\|(5)\fR