.\" -*- 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 "MAKETESTZONE 1"
.TH MAKETESTZONE 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
generaterecords \- generates a test dnssec zone that can be used to DNSSEC
.SH SYNOPSIS
.IX Header "SYNOPSIS"
generaterecords \-v \-d mytestzone.example.com
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The generaterecords script generates a zone file, given a domain name,
which is then signed and modified to invalidate portions of the data
in particular ways.  Each generated record is named appropriately to
how the security data is modified (the gooda record will contain a A
record with valid DNSSEC data, but the badseca record will contain an
A record where the signature has been modified to invalidate it).
.PP
The results of this process can then be served and test secure
validators, applications, and other software can be thrown at it to
see if they properly fail or succeed under the dns security policies
being deployed.
.PP
After the files are generated, consider running \fBdonuts\fR on them to
see how the data in them has been tampered with to be invalid.
.SH PRE-REQUISITES
.IX Header "PRE-REQUISITES"
zonesigner from the dnssec-tools project
bind software 9.3.1 or greater
.SH "GETTING STARTED"
.IX Header "GETTING STARTED"
To get started creating a new zone, you'll need to tell zonesigner to
create new keys for all of the new zones that \fBmaketestzone\fR creates.
Thus, the first run of \fBmaketestzone\fR should look like:
.IP "First Time:" 4
.IX Item "First Time:"
maketestzone \-k [OTHER DESIRED OPTIONS]
.PP
After that, the generated zone files can be loaded and served in a
test server.
.PP
Once every 30 days (by default via zonesigner) the script will need to
be rerun to recreate the records and resign the data so the signature
date stamps remain valid (or in some cases invalid).
.IP "Every 30 days:" 4
.IX Item "Every 30 days:"
maketestzone [OTHER DESIRED OPTIONS]
.SH OPTIONS
.IX Header "OPTIONS"
Below are thoe options that are accepted by the \fBmaketestzone\fR tool.
.SS "Output File Naming:"
.IX Subsection "Output File Naming:"
.IP "\-o STRING" 4
.IX Item "-o STRING"
.PD 0
.IP \-\-output\-file\-prefix=STRING 4
.IX Item "--output-file-prefix=STRING"
.PD
Output prefix to use for zone files (default = db.)
.IP "\-O STRING" 4
.IX Item "-O STRING"
.PD 0
.IP \-\-output\-suffix\-signed\-file=STRING 4
.IX Item "--output-suffix-signed-file=STRING"
.PD
Output suffix to be given to zonesigner (default = .zs)
.IP "\-M STRING" 4
.IX Item "-M STRING"
.PD 0
.IP \-\-output\-modified\-file=STRING 4
.IX Item "--output-modified-file=STRING"
.PD
Output suffix for the modified zone file (default = .modified)
.IP \-D 4
.IX Item "-D"
.PD 0
.IP \-\-run\-donuts 4
.IX Item "--run-donuts"
.PD
Run donuts on the results
.IP \-\-donuts\-output\-suffix=STRING 4
.IX Item "--donuts-output-suffix=STRING"
The file suffix to use for donuts output (default = .donuts)
.SS "Output Zone Information:"
.IX Subsection "Output Zone Information:"
.IP "\-d STRING" 4
.IX Item "-d STRING"
.PD 0
.IP \-\-domain=STRING 4
.IX Item "--domain=STRING"
.PD
domain name to generate records for
.IP \-\-ns=STRING 4
.IX Item "--ns=STRING"
.PD 0
.IP \-\-name\-servers=STRING 4
.IX Item "--name-servers=STRING"
.IP "\-n STRING" 4
.IX Item "-n STRING"
.PD
Comma separated name=addr name-server records
.IP \-\-a\-addr=STRING 4
.IX Item "--a-addr=STRING"
.PD 0
.IP \-\-a\-record\-address=STRING 4
.IX Item "--a-record-address=STRING"
.PD
A record (IPv4) address to use in data
.IP \-\-aaaa\-addr=STRING 4
.IX Item "--aaaa-addr=STRING"
.PD 0
.IP \-\-a\-record\-address=STRING 4
.IX Item "--a-record-address=STRING"
.PD
AAAA record (IPv6) address to use in data
.SS "Output Data Type Selection:"
.IX Subsection "Output Data Type Selection:"
.IP "\-p STRING" 4
.IX Item "-p STRING"
.PD 0
.IP \-\-record\-prefixes=STRING 4
.IX Item "--record-prefixes=STRING"
.PD
Comma separated list of record prefixes to use
.IP "\-P STRING" 4
.IX Item "-P STRING"
.PD 0
.IP \-\-ns\-prefixes=STRING 4
.IX Item "--ns-prefixes=STRING"
.PD
Comma separated list of NS record prefixes to use
.IP \-c 4
.IX Item "-c"
.PD 0
.IP \-\-no\-cname\-records 4
.IX Item "--no-cname-records"
.PD
Don't create CNAME records
.IP \-s 4
.IX Item "-s"
.PD 0
.IP \-\-no\-ns\-records 4
.IX Item "--no-ns-records"
.PD
Don't create sub-zone records
.SS "Task Selection:"
.IX Subsection "Task Selection:"
.IP \-g 4
.IX Item "-g"
.PD 0
.IP \-\-dont\-generate\-zone 4
.IX Item "--dont-generate-zone"
.PD
Do not generate the zone; use the existing and sign/modify it
.IP \-z 4
.IX Item "-z"
.PD 0
.IP \-\-dont\-run\-zonesigner 4
.IX Item "--dont-run-zonesigner"
.PD
Do not run zonesigner to sign the records
.IP \-Z 4
.IX Item "-Z"
.PD 0
.IP \-\-dont\-destroy 4
.IX Item "--dont-destroy"
.PD
Do not destroy the records and leave them properly signed
.IP \-\-bind\-config=STRING 4
.IX Item "--bind-config=STRING"
Generate a bind configuration file snippit to load the DB sets
.IP \-\-html\-out=STRING 4
.IX Item "--html-out=STRING"
Generate a HTML page containing a list of record names
.IP \-\-apache\-out=STRING 4
.IX Item "--apache-out=STRING"
Generate a Apache config snippit for configuring apache for each zone record
.IP \-\-sh\-test\-out=STRING 4
.IX Item "--sh-test-out=STRING"
Generate a test script for running dig commands
.IP \-v 4
.IX Item "-v"
.PD 0
.IP \-\-verbose 4
.IX Item "--verbose"
.PD
Verbose output
.SS "Zonesigner Configuration:"
.IX Subsection "Zonesigner Configuration:"
.IP "\-a STRING" 4
.IX Item "-a STRING"
.PD 0
.IP \-\-zonesigner\-arguments=STRING 4
.IX Item "--zonesigner-arguments=STRING"
.PD
Arguments to pass to zonesigner
.IP \-k 4
.IX Item "-k"
.PD 0
.IP \-\-generate\-keys 4
.IX Item "--generate-keys"
.PD
Have zonesigner generate needed keys
.SS "Bind Configuration Options"
.IX Subsection "Bind Configuration Options"
.IP \-\-bind\-db\-dir=STRING 4
.IX Item "--bind-db-dir=STRING"
The base directory where the bind DB files will be placed
.SS "HTML Output Configuration"
.IX Subsection "HTML Output Configuration"
.IP \-\-html\-out\-add\-links 4
.IX Item "--html-out-add-links"
Make each html record name a http link to that address
.IP \-\-html\-out\-add\-db\-links 4
.IX Item "--html-out-add-db-links"
Add a link to each of the generated DB files.
.IP \-\-html\-out\-add\-donuts\-links 4
.IX Item "--html-out-add-donuts-links"
Add a link to each of the generated donuts error list files.
.SS "SH Test Script Configuration Options"
.IX Subsection "SH Test Script Configuration Options"
.IP \-\-sh\-test\-resolver=STRING 4
.IX Item "--sh-test-resolver=STRING"
The resolver address to force
.SS "Help Options"
.IX Subsection "Help Options"
.IP \-h 4
.IX Item "-h"
Display a help summary (short flags preferred)
.IP \-\-help 4
.IX Item "--help"
Display a help summary (long flags preferred)
.IP \-\-help\-full 4
.IX Item "--help-full"
Display all help options (both short and long)
.IP \-\-version 4
.IX Item "--version"
Display the script version number.
.SH "ADDING NEW OUTPUT"
.IX Header "ADDING NEW OUTPUT"
The following section discusses how to extend the \fBmaketestzone\fR tool
with new output modifications.
.SS "ADDING LEGEND INFORMATION"
.IX Subsection "ADDING LEGEND INFORMATION"
For the legend HTML output, the \f(CW%LegendInformation\fR hash contains a
keyname and description for each modification type.
.SS "ADDING NEW SUBZONE DIFFERENCES"
.IX Subsection "ADDING NEW SUBZONE DIFFERENCES"
The \fR\f(CI%zonesigner_domain_opts\fR\fI\fR hash lists additional arguments between
how zonesigner is called for various sub-domains.  Thus you can create
additional sub-zones with different zonesigner optionns to test other
operational parameters between parent and child.  For example:
.PP
.Vb 1
\&   \*(Aqrollzsk\-ns.\*(Aq . $opts{\*(Aqd\*(Aq} => \*(Aq\-rollzsk\*(Aq,
.Ve
.PP
Forces the rollzsk-ns test sub-zone to roll it's zsk when the zone is
signed.
.SS "ADDING NEW RECORD MODIFICATIONS"
.IX Subsection "ADDING NEW RECORD MODIFICATIONS"
Maketestzone is in early development stages but already has the
beginnings of an extnesible system allowing you to modify records at
will based on regexp => subroutine hooks.
.PP
To add a new modification, add a new keyword to the 'p' and optionally
\&'P' default flags (or add it at run time), and then add a new function
to the list of callbacks defined in the \f(CW%destroyFunctions\fR hash that is
based on your new keyword.  When the file is getting parsed and hits a
record matching your expression, your functional will be called.
Arguments can be added to the function by passing an array reference
where the first argument is the subroutine to be called, and the
remainder are additional arguments.  Output lines should be printed to
the \f(CW$fh\fR file handle.
.PP
Here's an example function that deletes the RRSIG signature of the
next record:
.PP
.Vb 4
\&  sub delete_signature {
\&      # the first 2 arguments are always passed; the other was in the
\&      # array refeence the subroutine was registered with.
\&      my ($name, $type, $expr) = @_;
\&
\&      Verbose("  deleting signatures of $_[0]");
\&
\&      # print the current line
\&      print $fh $_;
\&
\&      my $inrec = 0;
\&      while (<I>) {
\&        # new name record means we\*(Aqre done.
\&        last if /^\ew/;
\&
\&        # we\*(Aqre in a multi\-line rrsig record
\&        $inrec = 1 if (/$expr\es+$type/);
\&
\&        # print the line if we\*(Aqre not in the rrsig record
\&        print $fh $_ if (!$inrec);
\&
\&        # when done with the last line of the rrsig record, mark this spot
\&        $inrec = 0 if (/\e)/);
\&      }
\&  }
.Ve
.PP
This is then registered within \f(CW%destroyFunctions\fR.  Here's an example
of registering the function to delete the signature on a DS record:
.PP
.Vb 1
\&   \*(Aq^(nosig[\-\ew]+).*IN\es+NS\es+\*(Aq => [\e&delete_signature, \*(AqDS\*(Aq, \*(AqRRSIG\*(Aq],
.Ve
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2004\-2013 SPARTA, Inc.  All rights reserved.
See the COPYING file included with the DNSSEC-Tools package for details.
.SH AUTHOR
.IX Header "AUTHOR"
Wes Hardaker <hardaker@users.sourceforge.net>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBNet::DNS\fR
.PP
http://dnssec\-tools.sourceforge.net
.PP
\&\fBzonesigner\fR\|(1), \fBdonuts\fR\|(1)
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 1009:" 4
.IX Item "Around line 1009:"
You forgot a '=back' before '=head2'
.IP "Around line 1011:" 4
.IX Item "Around line 1011:"
\&'=item' outside of any '=over'
.IP "Around line 1039:" 4
.IX Item "Around line 1039:"
You forgot a '=back' before '=head2'
.IP "Around line 1041:" 4
.IX Item "Around line 1041:"
\&'=item' outside of any '=over'
.IP "Around line 1067:" 4
.IX Item "Around line 1067:"
You forgot a '=back' before '=head2'
.IP "Around line 1069:" 4
.IX Item "Around line 1069:"
\&'=item' outside of any '=over'
.IP "Around line 1093:" 4
.IX Item "Around line 1093:"
You forgot a '=back' before '=head2'
.IP "Around line 1095:" 4
.IX Item "Around line 1095:"
\&'=item' outside of any '=over'
.IP "Around line 1135:" 4
.IX Item "Around line 1135:"
You forgot a '=back' before '=head2'
.IP "Around line 1137:" 4
.IX Item "Around line 1137:"
\&'=item' outside of any '=over'
.IP "Around line 1149:" 4
.IX Item "Around line 1149:"
You forgot a '=back' before '=head2'
.IP "Around line 1151:" 4
.IX Item "Around line 1151:"
\&'=item' outside of any '=over'
.IP "Around line 1155:" 4
.IX Item "Around line 1155:"
You forgot a '=back' before '=head2'
.IP "Around line 1157:" 4
.IX Item "Around line 1157:"
\&'=item' outside of any '=over'
.IP "Around line 1169:" 4
.IX Item "Around line 1169:"
You forgot a '=back' before '=head2'
.IP "Around line 1171:" 4
.IX Item "Around line 1171:"
\&'=item' outside of any '=over'
.IP "Around line 1175:" 4
.IX Item "Around line 1175:"
You forgot a '=back' before '=head2'
.IP "Around line 1177:" 4
.IX Item "Around line 1177:"
\&'=item' outside of any '=over'