summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org>2015-04-01 15:17:47 (GMT)
committer Sergey Poznyakoff <gray@gnu.org>2015-04-01 17:41:42 (GMT)
commit74828acdf2dcce9e66318a2852ec4473364c7458 (patch) (side-by-side diff)
treedd2fc8bdc8eb7536f5e4315f4ff9f0772942e6ca
parenta51ba4fa1a4d3e2e868e1028c85145e302a1462d (diff)
downloaddnstools-74828acdf2dcce9e66318a2852ec4473364c7458.tar.gz
dnstools-74828acdf2dcce9e66318a2852ec4473364c7458.tar.bz2
Bigfixes
* nsdbimport/nsdbimport: Improve docs. * whoseip/Whoseip/DB.pm: Docs formatting fix.
Diffstat (more/less context) (ignore whitespace changes)
-rwxr-xr-xnsdbimport/nsdbimport293
-rw-r--r--whoseip/Whoseip/DB.pm1
2 files changed, 264 insertions, 30 deletions
diff --git a/nsdbimport/nsdbimport b/nsdbimport/nsdbimport
index e2969c8..dc93c6d 100755
--- a/nsdbimport/nsdbimport
+++ b/nsdbimport/nsdbimport
@@ -1,5 +1,5 @@
#! /usr/bin/perl
-# Copyright (C) 2014 Sergey Poznyakoff <gray@gnu.org>
+# Copyright (C) 2015 Sergey Poznyakoff <gray@gnu.org>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@@ -138,10 +138,10 @@ my @rrtypes = ('A', 'AAAA', 'A6', 'AFSDB',
'CNAME', 'DNAME', 'DNSKEY', 'DS',
'EUI48', 'EUI64', 'HINFO', 'ISDN',
'KEY', 'LOC', 'MX', 'NAPTR',
- 'NS', 'NSEC', 'NXT', 'NXT',
- 'PTR', 'RP', 'RRSIG', 'RT',
- 'SIG', 'SOA', 'SPF', 'SRV',
- 'TXT', 'WKS', 'X25');
+ 'NS', 'NSEC', 'NXT', 'PTR',
+ 'RP', 'RRSIG', 'RT', 'SIG',
+ 'SOA', 'SPF', 'SRV', 'TXT',
+ 'WKS', 'X25');
my $rx_rr = array_to_regexp(@rrtypes);
# ###################
@@ -397,7 +397,7 @@ sub zimport {
# ###################
my $conffile;
-my $origin;
+my $origin = '.';
GetOptions("h" => sub {
pod2usage(-message => "$progname: $progdescr",
@@ -422,10 +422,10 @@ unless (defined($conffile)) {
($conffile) = grep { -e $_ } (
'.nsdbimport.conf',
"$ENV{HOME}/.nsdbimport.conf",
- '/etc/.nsdbimport.conf');
+ '/etc/nsdbimport.conf');
}
-abend(EX_USAGE, "no configuration file; please use the --config option")
+abend(EX_OSFILE, "no configuration file; please use the --config option")
unless defined $conffile;
my %kw = ('database' => 1,
@@ -509,6 +509,20 @@ B<nsdbimport>
=head1 DESCRIPTION
+Imports DNS records from zone files in BIND-compatible format into a SQL
+database. The format of the database (or, more precisely, SQL statements
+used to populate the database) is determined by configuration file.
+
+Source files can either be listed as command line arguments, or read directly
+from BIND configuration file, supplied by the B<--bind-config> option. In
+former case, it is recommended to define explicit origin using the
+B<--origin> option.
+
+When using B<--bind-config> option, no files can be given in the command line.
+Instead, B<nsdbimport> parses B<named> configuration file and selects B<zone>
+statements that have type B<master>. Then it imports files listed in these
+statements. In this case, origin is determined automatically for each file.
+
=head1 OPTIONS
=over 4
@@ -526,10 +540,10 @@ file names will be searched in that directory.
Read configuration from I<FILE>. If this option is not given, B<nsdbimport>
tries the following files: F<.nsdbimport.conf>, F<~/.nsdbimport.conf> and
-F</etc/.nsdbimport.conf>. First of them which exists is read. See the
+F</etc/nsdbimport.conf>. First of them which exists is read. See the
section B<CONFIGURATION> below for a discussion of configuration file format.
-=item B<--bind-config=>, B<--from-config=>I<FILE>
+=item B<--bind-config>, B<--from-config=>I<FILE>
Parse BIND configuration file I<FILE> and process all files corresponding
to master zones. Note, that this option relies on B<cfpeek>(1) being
@@ -570,17 +584,18 @@ Configuration file supplies credentials for accessing the database and
templates for the SQL queries (normally, B<INSERT> statements) to be
used in order to import records of particular B<RR> types.
-Upon startupe B<nsdbimport> looks for the following files (in that order):
-F<.nsdbimport.conf>, F<~/.nsdbimport.conf>, or F</etc/.nsdbimport.conf>.
-First of them that exists is read and parsed as a configuration file.
-
-If the command line option B<--config> (B<-c>) is given, its value is
-taken as the name of the configuration file to read. In that case,
-default configuration files are not scanned.
-
-Configuration consists of I<keyword>=I<value> pairs. Any amount of white
-space is allowed on either side of the equals sign. Each pair occupies
-a single logical line. To split very long lines, the usual backslash
+If the command line option B<--config> (B<-c>) is given, B<nsdbimport>
+takes its value as the name of configuration file to read. Otherwies,
+it tries to read file F<.nsdbimport.conf> from the current working
+directory. If it does not exist, the program looks it up in the home
+directory of the user. If that file doesn't exist either,
+F</etc/nsdbimport.conf> is read. If none of these files exists,
+B<nsdbimport> terminates with error code .
+
+The configuration file consists of statements -- pairs I<keyword>=I<value>,
+occupying a single logical line. Within a statement, any amount of white
+space is allowed before I<keyword>, after I<value> and on either side of
+the equals sign. To split very long lines, the usual backslash
escaping is used: any line ending with a backslash immediately followed
by a newline indicates continuation on the next line. The newline character
is stripped off and the contents of the next line is appended in its place.
@@ -589,13 +604,13 @@ Comments begin with B<#> character and extend to the end of physical line.
Empty lines are ignored.
-The following statements configure database credentials
+The following statements configure database credentials:
=over 4
=item B<database=>I<STRING>
-Database name.
+Database name.
=item B<host=>I<NAME>
@@ -603,11 +618,12 @@ Hostname or IP address of the host running the database server.
=item B<port=>I<NUM>
-Port number, if differs from the default.
+Port number, if it differs from the default.
=item B<db-params=>I<STRING>
-Additional options.
+Additional database-specific options. E.g. path to the UNIX socket file, or
+the like.
=item B<user=>I<STRING>
@@ -636,17 +652,234 @@ Enable or disable processing of B<$GENERATE> directives. Such directives
usually insert enormous amount of data into the database and therefore
are disabled by default. Set B<generate = yes> to enable them.
-=item B<rr-query=>I<TEMPLATE>
+=back
+
+=head2 Query templates
+
+SQL statements used to actually import DNS data into the database are
+formed using I<templates>. Configuration statements that define templates
+have the following form:
+
+=over 4
+
+B<I<rrtype>-query = >I<TEMPLATE>
+
+=back
+
+where I<rrtype> is the B<RR> of the record converted to lower case. At the
+time of this writing, B<nsdbimport> supports the following B<RR> types: B<A>,
+B<AAAA>, B<A6>, B<AFSDB>, B<CNAME>, B<DNAME>, B<DNSKEY>, B<DS>, B<EUI48>,
+B<EUI64>, B<HINFO>, B<ISDN>, B<KEY>, B<LOC>, B<MX>, B<NAPTR>, B<NS>, B<NSEC>,
+B<NXT>, B<PTR>, B<RP>, B<RRSIG>, B<RT>, B<SIG>, B<SOA>, B<SPF>, B<SRV>,
+B<TXT>, B<WKS>, B<X25B>. Thus, for example, the statement B<soa-query> defines
+the query used to import B<SOA> records.
+
+However, you don't need to define a template for each possible B<RR> type.
+Instead you can use the I<generic query>, which is defined using the following
+statement:
+
+=over 4
+
+B<rr-query = >I<TEMPLATE>
+
+=back
+
+This query will be used whenever no particular query is defined for the
+B<RR> type of a record being imported.
+
+The I<TEMPLATE> used in B<*-query> statements must be a valid SQL statement
+(normally, an B<INSERT>), with I<macro references> used in place of the
+actual data. In its simplest form, a macro reference is B<${I<macro>}>,
+where I<macro> is the name of a macro variable. Upon executing the statement,
+macro references are replaced with the actual values of the corresponding
+variables. The following variables are defined for all B<RR> types:
+
+=over 4
+
+=item B<rr>
+
+The B<RR> type.
+
+=item B<origin>
+
+Origin of the record.
+
+=item B<label>
+
+Label (or I<owner-user>) of the record.
+
+=item B<ttl>
+
+TTL value (seconds).
+
+=item B<data>
+
+Data (or I<right-hand side>) of the record.
+
+=item B<locus>
+
+Location of the source record in the input file (B<I<file-name>:I<line-number>>).
+
+=back
+
+For example, given the following input file F<example.zone>:
+
+ $ORIGIN example.com.
+ www 1H A 192.0.2.1
+
+the second line will produce the following macro variables:
+
+ rr = A
+ origin = example.com.
+ ttl = 3600
+ data = 192.0.2.1
+ locus = example.zone:2
+
+For B<MX> records, the following two macro variables are defined:
+
+=over 4
+
+=item B<mx>
+
+Host name of the MX server.
+
+=item B<mx_priority>
+
+Server priority
+
+=back
+
+For B<SOA> records, the following additional variables are defined:
+
+=over 4
+
+=item B<ns>
+
+Hostname of the principal NS server.
+
+=item B<resp_person>
+
+Email address of the responsible person (in standard NS notation: B<@> being
+substituted by a dot).
+
+=item B<serial>
+
+Serial number.
+
+=item B<refresh>
+
+Zone refresh interval (seconds).
+
+=item B<retry>
+
+Retry interval (seconds).
+
+=item B<expire>
+
+Expire interval (seconds).
+
+=item B<minimum>
+
+Minimum initerval (seconds).
+
+=back
+
+More complex form of macro references allows for I<flags>, which control how
+the value of the variable is represented after expansion. Flags are specified
+as a comma-separated list following a colon after the variable name, e.g.:
-A generic query which inserts a single B<RR> record in the database. It
-will be used whenever a record is imported that has no special query
-statement defined for its B<RR> type.
+=over 4
+
+B<${label:-@}>
=back
+
+The construct above expands to the actual value of label, unless it is empty,
+in which case it expands to B<@>.
+
+The following flags are recognized (brackets denoting optional part:
+
+=over 4
+
+=item B<?>[I<text>]
+
+If the variable is not defined or empty, displays a warning message. Default
+I<text> is B<I<var> not defined>, where I<var> is replaced with the name
+of the variable in question.
+
+=item B<->I<text>
+
+If the variable is not defined or empty, replace it with I<text>.
+
+=item B<+>I<text>
+
+If the variable is defined, expand to I<text>, instead of its value.
+
+=item B<.>[I<text>]
+
+If the expansion of the variable does not end with a dot, append to it a dot
+and the current origin. If I<text> is supplied, use it as the origin. For
+example, if B<origin=example.com> and B<data=www>, then B<${data:.}> will
+produce B<www.example.com>.
+
+=item B<@>[I<text>]
+
+If variable expands to the apex symbol (B<@>), replace it with the actual
+origin. If I<text> is supplied, use it instead.
+
+=back
+
+=head1 FILES
+
+Configuration files:
+
+=over 4
+
+=item F<.nsdbimport.conf>
+
+=item F<~/.nsdbimport.conf>
+
+=item F</etc/nsdbimport.conf>
+
+=back
+
+=head1 EXIT CODES
+
+=over 4
+
+=item 0
+
+Successful termination.
+
+=item 64
+
+Invalid command line usage.
+
+=item 66
+
+Failed to open a zone file.
+
+=item 69
+
+Can't open B<nsdbimport> configuration file or failed to execute SQL query.
+
+=item 72
+
+Configuration file does not exist or is not readable. This can refer to both
+the B<nsdbimport> configuration file and to BIND configuration file, supplied
+with the B<--bind-config> option.
+
+=item 78
+
+Exited due to errors in configuration file.
+
+=back
=head1 BUGS
-Only MySQL is supported.
+Only MySQL is supported and tested.
+
+Need to ensure proper quoting of SQL query arguments.
=head1 SEE ALSO
diff --git a/whoseip/Whoseip/DB.pm b/whoseip/Whoseip/DB.pm
index a455a01..4a63aff 100644
--- a/whoseip/Whoseip/DB.pm
+++ b/whoseip/Whoseip/DB.pm
@@ -62,6 +62,7 @@ Whoseip::DB - WhoseIP cache database
=head1 SYNOPSIS
use Whoseip::DB;
+
use Whoseip::DB qw(:all);
$dbf = Whoseip::DB::ipdb_open($filename[,

Return to:

Send suggestions and report system problems to the System administrator.