From ba4943829d013a6443c5bdec626ac7e2cc02d698 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Wed, 21 Oct 2020 11:15:52 -0400 Subject: [PATCH] Add a man page. --- CHANGES | 1 + valtz.1 | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 valtz.1 diff --git a/CHANGES b/CHANGES index d9ba52e..a82591d 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,7 @@ New in version 0.8 ================== +* Add a man (1) page * Dropped "-x" flag; the return code is always non-zero on error now. * Warn about IP addresses in hostname fields * Add support for SRV records diff --git a/valtz.1 b/valtz.1 new file mode 100644 index 0000000..5fd6ec7 --- /dev/null +++ b/valtz.1 @@ -0,0 +1,155 @@ +.TH valtz 1 + +.SH NAME +valtz \- Validate tinydns-data files. + +.SH SYNOPSIS + +Validate one or more tinydns-data files: + + \fBvaltz\fR [\fB-r\fR] [\fB-R\fR] [\fB-i\fR] \fItinydns-file1\fR [\fItinydns-file2 ...\fR] + +Filter bad lines out of one or more tinydns-data files: + + \fBvaltz\fR [\fB-HiIqrRst\fR] [\fB-T \fItypes\fR\fR] -f \fItinydns-file1\fR [\fItinydns-file2 ...\fR] + +Filter bad lines using filter configuration files: + + \fBvaltz\fR [\fB-fHiIqrRst\fR] [\fB-T \fItypes\fR\fR] -F \fIfilter-file1\fR [\fIfilter-file2 ...\fR] + +Show the built-in help: + + \fBvaltz\fR -h + +.SH OPTIONS + +.IP \fB-h\fR +Display usage summary. +.IP \fB-f\fR +Filter out invalid lines and write the rest to stdout. +.IP \fB-F\fR +Treat the program's arguments as filter configuration files rather than +as tinydns-data files. See the ADVANCED FILTERING section below for more +information. +.IP \fB-r\fR +Allow "fqdn" fields to be empty, thereby denoting the root. +When using ADVANCED FILTERING, this is the default behavior for "deny" filters, +and can be obtained explicitly for "allow" filters by specifying "allow ." +.IP \fB-R\fR +Allow "mname" and "p" fields to be empty. This is probably not very +useful. +.IP \fB-i\fR +Allow "ip" fields to be empty. These lines do not generate any records. +.IP \fB-I\fR (filtering only) +Include rejected lines as comments in output. +.IP \fB-q\fR (filtering only) +Do not print valid lines to standard out. +.IP \fB-s\fR +-s Don't skip files ending with ",v", "~", ".bak", ".log", ".old", ".swp", and ".tmp". +.IP \fB-t\fR (filtering only) +Don't ignore comment lines (beginning with a "#" character). +.IP \fB-T \fItypes\fR\fR (advanced filtering only) +Specify additional allowed record types, on top of the ones +allowed by the filter configuration files. + +.SH OUTPUT +When validating, ideally no output is generated. Any errors are +printed to standard error. +.P +When filtering, the acceptable lines are printed to standard out. + +.SH EXIT CODE +The exit code will be 0 if nothing has gone wrong. If a validation +error occurs, the return value is incremented by 1. If a disallowed +record type is encountered, the return value is incremented by 2. + +.SH ADVANCED FILTERING +When the \fB-F\fR flag is used, valtz performs "advanced filtering" +controlled by filter configuration files that are specified on the +command line. These files contain one or more of the following +directives, each of which may appear only once unless otherwise +specified: +.IP \fBzonefile\ \fIpaths\fR\fR +Directly specifies the tinydns-data files to which this filter +applies. +.IP \fBzonefile\ file:\fIzonelist\fR\fR +Indirectly specifies the tinydns-data files to which this filter +applies, by referencing another \fIzonelist\fR that contains one path +(to a tinydns-data file) per line. +.IP \fBextralog\ \fIlogfile\fR\fR +Log errors to \fIlogfile\fR in addition to printing them to standard +error. Useful when you have many tinydns-data files and want to keep +their results separate. +.IP \fBdeny\ \fIpattern\fR\fR +Place the filter in "implicit allow" mode, so that all records are +allowed unless their "fqdn" is explicitly matched by the +perl-compatible regular expression \fIpattern\fR. May appear more than +once. +.IP \fBdeny\ file:\fIdenylist\fR\fR +Place the filter in "implicit allow" mode, so that all records are +allowed unless their "fqdn" is explicitly matched by a line in +\fIdenylist\fR, which should contain one perl-compatible regular +expression per line. May appear more than once. +.IP \fBallow\ \fIpattern\fR\fR +Place the filter in "implicit deny" mode, so that all records are +denied unless their "fqdn" is explicitly matched by the +perl-compatible regular expression \fIpattern\fR. May appear more than +once. +.IP \fBallow\ file:\fIallowlist\fR\fR +Place the filter in "implicit deny" mode, so that all records are +denied unless their "fqdn" is explicitly matched by a line in +\fIallowlist\fR, which should contain one perl-compatible regular +expression per line. May appear more than once. +.IP \fBallowtype\ \fItypes\fR\fR +Specifies a whitespace-separated list allowed record types. When used, +even comment lines (type "#") must explicitly be allowed if you want +to include them in the output. Valid record types are "%", ".", "&", +"=", "+", "@", "#", "-", "'", "^", "C", "S", "Z", and ":". + +.SH EXAMPLES + +.IP \[bu] 2 +Validate a file without errors: + +.nf +.I $ valtz example.org.tinydns +.I $ echo $? +0 +.fi + +.IP \[bu] 2 +Validate a file \fBwith\fR errors: + +.nf +.I $ valtz example.com.tinydns +File example.com.tinydns + line 5; err 1 !example.com.::127.0.0.1: + unknown record type: #21 +.I $ echo $? +1 +.fi + +.IP \[bu] 2 +Filter invalid lines out of the given file: + +.nf +.I $ valtz -f example.com.tinydns 2>/dev/null +Zexample.com.:dns1.example.com.:admin.example.com.: +&example.com.::dns1.example.com.: +&example.com.::dns2.example.com.: ++example.com.:127.0.0.1: +Cwww.example.com.:example.com.: +.fi + +.IP \[bu] 2 +Use advanced filtering with a configuration file that drops everything +except SOA and A records (of type "Z" and "+", respectively): + +.nf +.I $ cat keep-SOA-A-records.valtz +zonefile example.com.tinydns +allowtype Z + +.I $ valtz -F keep-SOA-A-records.valtz 2>/dev/null +Zexample.com.:dns1.example.com.:admin.example.com.: ++example.com.:127.0.0.1: +.fi -- 2.44.2