diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2015-04-01 18:17:47 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2015-04-01 20:41:42 +0300 |
commit | 74828acdf2dcce9e66318a2852ec4473364c7458 (patch) | |
tree | dd2fc8bdc8eb7536f5e4315f4ff9f0772942e6ca | |
parent | a51ba4fa1a4d3e2e868e1028c85145e302a1462d (diff) | |
download | dnstools-74828acdf2dcce9e66318a2852ec4473364c7458.tar.gz dnstools-74828acdf2dcce9e66318a2852ec4473364c7458.tar.bz2 |
Bigfixes
* nsdbimport/nsdbimport: Improve docs.
* whoseip/Whoseip/DB.pm: Docs formatting fix.
-rwxr-xr-x | nsdbimport/nsdbimport | 293 | ||||
-rw-r--r-- | whoseip/Whoseip/DB.pm | 1 |
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[, |