.\" -*- 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 "CONVERTAR 1"
.TH CONVERTAR 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
convertar \- Converts trust anchor repositories from one format to another
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBconvertar\fR operates on input and output files of different Trust
Anchor Repository (TAR) formats.  \fBconvertar\fR decides what type of
file format is being referred to by a "type:filename" specification.
Options can be passed to the convertar module by using a '/' delimited
specifier in the \fItype\fR identifier.  Such as
"type/option=value/other=othervalue:filename".  See below for a list
of different input and output formats that \fBconvertar\fR understands by
default and what options they take.
.PP
See the \fINet::DNS::SEC::Tools::TrustAnchor\fR module and its
documentation for writing new plugins to allow \fBconvertar\fR to understand
other TAR formats.
.SH EXAMPLES
.IX Header "EXAMPLES"
This command will read in an \fBitar.xml\fR file (available from
https://itar.iana.org/) and convert it to a file that can be read in
by BIND's \fBnamed\fR application:
.PP
.Vb 1
\&  # convertar \-i itar:itar.xml \-o bind:bind.conf
.Ve
.PP
Read in multiple files, merge them together and write them out to two
different output file formats (the libval format is printed to stdout):
.PP
.Vb 1
\&  # convertar \-i itar:itar.xml,csv:local.csv \-o bind:bind.conf,libval:\-
.Ve
.SH "FILE SPECIFICATION CONVENTIONS"
.IX Header "FILE SPECIFICATION CONVENTIONS"
Types and files (e.g. for the \-i and \-o switches) are specificied
using the following format:
.PP
.Vb 1
\&  type:/path/to/file
.Ve
.PP
The \fItype\fR portion of the specification dictates what internal module
will attempt to read in the file.  The file portion of the
specification may or may not be required (but the ':' always is) and
may or may not point to a real file, depending on the module in charge
of the content.  Some modules may, for exmaple, load content from the
network.  For types that can read and write to a file, a '\-' may be
specified as a file to print to or read from standard output.
.PP
File formats MAY be infered from a trailing suffix, if the trailing
suffix.  EG, if a referenced file is foo.csv then internally convertar
will translate this to "csv:foo.csv".
.SH "FILE FORMATS"
.IX Header "FILE FORMATS"
The following file formats are known by default to \fBconvertar\fR:
.IP bind 4
.IX Item "bind"
A BIND name server (\fBnamed\fR) compatible trust anchor configuration file.
This can be included within a master \fBnamed.conf\fR file using the
"include" directive.
.Sp
The \fIbind\fR option can also take a \fI/write_expectations=1\fR flag when
writing to write an options {} section that will turn on dnssec and
require validation for zones from all the imported data.
.Sp
E.G. bind/write_expectations=1:named.conf
.IP secspider 4
.IX Item "secspider"
This is merely an alias that fetches the specspider
(http://secspider.cs.ucla.edu/) bind configuration file and then parse
it using the bind file format.
.Sp
WARNING: The PGP signature on the downloaded file is NOT checked.
.IP csv 4
.IX Item "csv"
A comma-separated list format.
.IP dump 4
.IX Item "dump"
A Perl hash \fIdump\fR format.  This should be used mostly for debugging of
newly developed modules as it shows the internal hash structure that is
passed between modules.
.IP itar 4
.IX Item "itar"
IANA's \fIitar\fR format, which is an XML-based format of trust anchor
keys.  IANA's file is available from https://itar.iana.org/.
.Sp
Specifying only 'itar:' line only (or itar:URL), \fBconvertar\fR will
attempt to retrieve the current remote ITAR respository file directly.
.Sp
WARNING: The PGP signature on the downloaded file is NOT checked.
.Sp
NOTE: support for downloading the ITAR repository over the network
requires the LWP::UserAgent module to be installed.
.IP libval 4
.IX Item "libval"
The \fIlibval\fR format is the configuration file format that
DNSSEC-Tool's \fIlibval\fR library uses.
.Sp
The \fIlibval\fR option can also take a \fI/write_expectations=1\fR flag
when writing to specify that the default (:)
zone-security-expectation's should be populated to require validation
of all the zones with imported data.  All other zones will have a
policy set to 'ignore.
.Sp
E.G. libval/write_expectations=1:dnsval.conf
.IP mf 4
.IX Item "mf"
The master file (\fImf\fR) format is also available from the \fIitar\fR web
site.
.IP dns 4
.IX Item "dns"
The \fIdns\fR format performs live queries of records attached to a
domain name to request either DS or DNSKEY records.  By default,
DNSKEY records will be queried.  The specific type to be queried can
be specified by preceeding the zone name with a "ds/" or "dnskey/"
prefix.  Example valid 'dns:' type specifications:
.Sp
.Vb 3
\&  dns:dnssec\-tools.org
\&  dns:ds/dnssec\-tools.org
\&  dns:dnskey/dnssec\-tools.org
.Ve
.Sp
Also, if you want to read dnskeys from the network but convert
them to ds records, you can use the /tods flag:
.Sp
.Vb 1
\&  dns/tods=1:dnssec\-tools.org
.Ve
.Sp
The DNS type can not output records and is only useful for reading in
information.
.Sp
WARNING: The keys and data being retrieved are not internally
validated and thus should not be trusted unless a secured resolver is
being used.
.SH OPTIONS
.IX Header "OPTIONS"
.IP "\fB\-i STRING\fR" 4
.IX Item "-i STRING"
.PD 0
.IP \fB\-\-input\-file=STRING\fR 4
.IX Item "--input-file=STRING"
.PD
Input file(s) to process.
.Sp
\&\fBconvertar\fR will read in the specified file(s).  Multiple files can
be separated by commas.
.IP "\fB\-o STRING\fR" 4
.IX Item "-o STRING"
.PD 0
.IP \fB\-\-output\-file=STRING\fR 4
.IX Item "--output-file=STRING"
.PD
Output file(s) to write.
.Sp
\&\fBconvertar\fR will write out these specified file(s) in the requested
output formats.  Multiple files can be separated by commas.
.IP \fB\-h\fR 4
.IX Item "-h"
.PD 0
.IP \fB\-\-help\fR 4
.IX Item "--help"
.IP \fB\-\-help\-full\fR 4
.IX Item "--help-full"
.PD
Displays command line help information.
.IP \fB\-\-gui\fR 4
.IX Item "--gui"
.PD 0
.IP \fB\-\-no\-gui\fR 4
.IX Item "--no-gui"
.PD
Controls the use of the optional GUI.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2009\-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 AT users DOT sourceforge DOT net >
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fINet::DNS::SEC::Tools::TrustAnchor\fR(3)