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-HiIqrRst\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-fHiIqrRst\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-s\fR
  48 -s Don't skip files ending with ",v", "~", ".bak", ".log", ".old", ".swp", and ".tmp".
  49 .IP \fB-t\fR (filtering only)
  50 Don't ignore comment lines (beginning with a "#" character).
  51 .IP \fB-T \fItypes\fR\fR (advanced filtering only)
  52 Specify additional allowed record types, on top of the ones
  53 allowed by the filter configuration files.
  54
  55 .SH OUTPUT
  56 When validating, ideally no output is generated. Any errors are
  57 printed to standard error.
  58 .P
  59 When filtering, the acceptable lines are printed to standard out.
  60
  61 .SH EXIT CODE
  62 The exit code will be 0 if nothing has gone wrong. If a validation
  63 error occurs, the return value is incremented by 1. If a disallowed
  64 record type is encountered, the return value is incremented by 2.
  65
  66 .SH ADVANCED FILTERING
  67 When the \fB-F\fR flag is used, valtz performs "advanced filtering"
  68 controlled by filter configuration files that are specified on the
  69 command line. These files contain one or more of the following
  70 directives, each of which may appear only once unless otherwise
  71 specified:
  72 .IP \fBzonefile\ \fIpaths\fR\fR
  73 Directly specifies the tinydns-data files to which this filter
  74 applies.
  75 .IP \fBzonefile\ file:\fIzonelist\fR\fR
  76 Indirectly specifies the tinydns-data files to which this filter
  77 applies, by referencing another \fIzonelist\fR that contains one path
  78 (to a tinydns-data file) per line.
  79 .IP \fBextralog\ \fIlogfile\fR\fR
  80 Log errors to \fIlogfile\fR in addition to printing them to standard
  81 error. Useful when you have many tinydns-data files and want to keep
  82 their results separate.
  83 .IP \fBdeny\ \fIpattern\fR\fR
  84 Place the filter in "implicit allow" mode, so that all records are
  85 allowed unless their "fqdn" is explicitly matched by the
  86 perl-compatible regular expression \fIpattern\fR. May appear more than
  87 once.
  88 .IP \fBdeny\ file:\fIdenylist\fR\fR
  89 Place the filter in "implicit allow" mode, so that all records are
  90 allowed unless their "fqdn" is explicitly matched by a line in
  91 \fIdenylist\fR, which should contain one perl-compatible regular
  92 expression per line. May appear more than once.
  93 .IP \fBallow\ \fIpattern\fR\fR
  94 Place the filter in "implicit deny" mode, so that all records are
  95 denied unless their "fqdn" is explicitly matched by the
  96 perl-compatible regular expression \fIpattern\fR. May appear more than
  97 once.
  98 .IP \fBallow\ file:\fIallowlist\fR\fR
  99 Place the filter in "implicit deny" mode, so that all records are
 100 denied unless their "fqdn" is explicitly matched by a line in
 101 \fIallowlist\fR, which should contain one perl-compatible regular
 102 expression per line. May appear more than once.
 103 .IP \fBallowtype\ \fItypes\fR\fR
 104 Specifies a whitespace-separated list allowed record types. When used,
 105 even comment lines (type "#") must explicitly be allowed if you want
 106 to include them in the output. Valid record types are "%", ".", "&",
 107 "=", "+", "@", "#", "-", "'", "^", "C", "S", "Z", and ":".
 108
 109 .SH EXAMPLES
 110
 111 .IP \[bu] 2
 112 Validate a file without errors:
 113
 114 .nf
 115 .I $ valtz example.org.tinydns
 116 .I $ echo $?
 117 0
 118 .fi
 119
 120 .IP \[bu] 2
 121 Validate a file \fBwith\fR errors:
 122
 123 .nf
 124 .I $ valtz example.com.tinydns
 125 File example.com.tinydns
 126   line 5; err 1 !example.com.::127.0.0.1:
 127     unknown record type: #21
 128 .I $ echo $?
 129 1
 130 .fi
 131
 132 .IP \[bu] 2
 133 Filter invalid lines out of the given file:
 134
 135 .nf
 136 .I $ valtz -f example.com.tinydns 2>/dev/null
 137 Zexample.com.:dns1.example.com.:admin.example.com.:
 138 &example.com.::dns1.example.com.:
 139 &example.com.::dns2.example.com.:
 140 +example.com.:127.0.0.1:
 141 Cwww.example.com.:example.com.:
 142 .fi
 143
 144 .IP \[bu] 2
 145 Use advanced filtering with a configuration file that drops everything
 146 except SOA and A records (of type "Z" and "+", respectively):
 147
 148 .nf
 149 .I $ cat keep-SOA-A-records.valtz
 150 zonefile example.com.tinydns
 151 allowtype Z +
 152 .I $ valtz -F keep-SOA-A-records.valtz 2>/dev/null
 153 Zexample.com.:dns1.example.com.:admin.example.com.:
 154 +example.com.:127.0.0.1:
 155 .fi