valtz.1

   1 .TH valtz 1
   2
   3 .SH NAME
   4 valtz \- Validate tinydns-data files.
   5
   6 .SH SYNOPSIS
   7
   8 Validate one or more tinydns-data files:
   9
  10   \fBvaltz\fR [\fB-r\fR] [\fB-R\fR] [\fB-i\fR] \fItinydns-file1\fR [\fItinydns-file2 ...\fR]
  11
  12 Filter bad lines out of one or more tinydns-data files:
  13
  14   \fBvaltz\fR [\fB-HiIqrRt\fR] [\fB-T \fItypes\fR\fR] -f \fItinydns-file1\fR [\fItinydns-file2 ...\fR]
  15
  16 Filter bad lines using filter configuration files:
  17
  18   \fBvaltz\fR [\fB-fHiIqrRt\fR] [\fB-T \fItypes\fR\fR] -F \fIfilter-file1\fR [\fIfilter-file2 ...\fR]
  19
  20 Show the built-in help:
  21
  22   \fBvaltz\fR -h
  23
  24 .SH OPTIONS
  25
  26 .IP \fB-h\fR
  27 Display usage summary.
  28 .IP \fB-f\fR
  29 Filter out invalid lines and write the rest to stdout.
  30 .IP \fB-F\fR
  31 Treat the program's arguments as filter configuration files rather than
  32 as tinydns-data files. See the ADVANCED FILTERING section below for more
  33 information.
  34 .IP \fB-r\fR
  35 Allow "fqdn" fields to be empty, thereby denoting the root.
  36 When using ADVANCED FILTERING, this is the default behavior for "deny" filters,
  37 and can be obtained explicitly for "allow" filters by specifying "allow ."
  38 .IP \fB-R\fR
  39 Allow "mname" and "p" fields to be empty. This is probably not very
  40 useful.
  41 .IP \fB-i\fR
  42 Allow "ip" fields to be empty. These lines do not generate any records.
  43 .IP \fB-I\fR (filtering only)
  44 Include rejected lines as comments in output.
  45 .IP \fB-q\fR (filtering only)
  46 Do not print valid lines to standard out.
  47 .IP \fB-t\fR (filtering only)
  48 Don't ignore comment lines (beginning with a "#" character).
  49 .IP \fB-T \fItypes\fR\fR (advanced filtering only)
  50 Specify additional allowed record types, on top of the ones
  51 allowed by the filter configuration files.
  52
  53 .SH OUTPUT
  54 When validating, ideally no output is generated. Any errors are
  55 printed to standard error.
  56 .P
  57 When filtering, the acceptable lines are printed to standard out.
  58
  59 .SH EXIT CODE
  60 The exit code will be 0 if nothing has gone wrong. If any validation
  61 error occured, the return value is incremented by 1. If a disallowed
  62 record type was encountered, the return value is incremented by 2.
  63 If you forgot to pass the required filename arguments (either the
  64 tinydns-data files or the filter configuration files), then we exit
  65 immediately with code 4.
  66
  67 .SH ADVANCED FILTERING
  68 When the \fB-F\fR flag is used, valtz performs "advanced filtering"
  69 controlled by filter configuration files that are specified on the
  70 command line. These files contain one or more of the following
  71 directives, each of which may appear only once unless otherwise
  72 specified:
  73 .IP \fBzonefile\ \fIpaths\fR\fR
  74 Directly specifies the tinydns-data files to which this filter
  75 applies.
  76 .IP \fBzonefile\ file:\fIzonelist\fR\fR
  77 Indirectly specifies the tinydns-data files to which this filter
  78 applies, by referencing another \fIzonelist\fR that contains one path
  79 (to a tinydns-data file) per line.
  80 .IP \fBextralog\ \fIlogfile\fR\fR
  81 Log errors to \fIlogfile\fR in addition to printing them to standard
  82 error. Useful when you have many tinydns-data files and want to keep
  83 their results separate.
  84 .IP \fBdeny\ \fIpattern\fR\fR
  85 Place the filter in "implicit allow" mode, so that all records are
  86 allowed unless their "fqdn" is explicitly matched by the
  87 perl-compatible regular expression \fIpattern\fR. May appear more than
  88 once.
  89 .IP \fBdeny\ file:\fIdenylist\fR\fR
  90 Place the filter in "implicit allow" mode, so that all records are
  91 allowed unless their "fqdn" is explicitly matched by a line in
  92 \fIdenylist\fR, which should contain one perl-compatible regular
  93 expression per line. May appear more than once.
  94 .IP \fBallow\ \fIpattern\fR\fR
  95 Place the filter in "implicit deny" mode, so that all records are
  96 denied unless their "fqdn" is explicitly matched by the
  97 perl-compatible regular expression \fIpattern\fR. May appear more than
  98 once.
  99 .IP \fBallow\ file:\fIallowlist\fR\fR
 100 Place the filter in "implicit deny" mode, so that all records are
 101 denied unless their "fqdn" is explicitly matched by a line in
 102 \fIallowlist\fR, which should contain one perl-compatible regular
 103 expression per line. May appear more than once.
 104 .IP \fBallowtype\ \fItypes\fR\fR
 105 Specifies a whitespace-separated list allowed record types. When used,
 106 even comment lines (type "#") must explicitly be allowed if you want
 107 to include them in the output. Valid record types are "%", ".", "&",
 108 "=", "+", "@", "#", "-", "'", "^", "C", "S", "Z", and ":".
 109
 110 .SH EXAMPLES
 111
 112 .IP \[bu] 2
 113 Validate a file without errors:
 114
 115 .nf
 116 .I $ valtz example.org.tinydns
 117 .I $ echo $?
 118 0
 119 .fi
 120
 121 .IP \[bu] 2
 122 Validate a file \fBwith\fR errors:
 123
 124 .nf
 125 .I $ valtz example.com.tinydns
 126 File example.com.tinydns
 127   line 5; err 1 !example.com.::127.0.0.1:
 128     unknown record type: #21
 129 .I $ echo $?
 130 1
 131 .fi
 132
 133 .IP \[bu] 2
 134 Filter invalid lines out of the given file:
 135
 136 .nf
 137 .I $ valtz -f example.com.tinydns 2>/dev/null
 138 Zexample.com.:dns1.example.com.:admin.example.com.:
 139 &example.com.::dns1.example.com.:
 140 &example.com.::dns2.example.com.:
 141 +example.com.:127.0.0.1:
 142 Cwww.example.com.:example.com.:
 143 .fi
 144
 145 .IP \[bu] 2
 146 Use advanced filtering with a configuration file that drops everything
 147 except SOA and A records (of type "Z" and "+", respectively):
 148
 149 .nf
 150 .I $ cat keep-SOA-A-records.valtz
 151 zonefile example.com.tinydns
 152 allowtype Z +
 153 .I $ valtz -F keep-SOA-A-records.valtz 2>/dev/null
 154 Zexample.com.:dns1.example.com.:admin.example.com.:
 155 +example.com.:127.0.0.1:
 156 .fi