NAME

Net::DNS::Dynamic::Adfilter - A DNS ad filter

DESCRIPTION

This is a DNS server intended for use as an ad filter for a local area network. Its function is to load lists of ad domains and nullify DNS queries for those domains to the loopback address. Any other DNS queries are proxied upstream, either to a specified list of nameservers or to those listed in /etc/resolv.conf. The module can also load and resolve host definitions found in /etc/hosts as well as hosts defined in a sql database.

Externally maintained lists of ad hosts may be loaded periodically through a specified url. A local addendum of hosts may also be specified. Ad host listings must conform to a one host per line format:

  # ad nauseam
  googlesyndication.com
  facebook.com
  twitter.com
  ...
  adinfinitum.com

Once running, local network dns queries can be addressed to the host's ip. This ip is echoed to stdout.

SYNOPSIS

    my $adfilter = Net::DNS::Dynamic::Adfilter->new();

    $adfilter->run();

Without any arguments, the module will function simply as a proxy, forwarding all requests upstream to nameservers defined in /etc/resolv.conf.

ATTRIBUTES

ask_pgl_hosts

    my $adfilter = Net::DNS::Dynamic::Adfilter->new(

        ask_pgl_hosts => {
            url => 'http://pgl.yoyo.org/adservers/serverlist.php?hostformat=nohtml&showintro=0&&mimetype=plaintext',
            path => '/var/named/adhosts',     #path to ad hosts
            refresh => 7,                     #ttl in days (default = 7)
        },
    );

The ask_pgl_hosts hashref defines a url that returns a single column list of ad hosts. In the module's current version, this is the only acceptable format. A path string defines where the module will write a local copy of this list. The refresh value determines what age (in days) the local copy may be before it is refreshed. This value also determines the lifespan (ttl) of queries based upon this list.

ask_more_hosts

    my $adfilter = Net::DNS::Dynamic::Adfilter->new(

        ask_more_hosts => {
            path => '/var/named/morehosts',  #path to secondary hosts
        },
    );

The ask_more_hosts hashref contains only a path string that defines where the module will access an addendum of ad hosts to nullify. As above, a single column is the only acceptable format.

LEGACY ATTRIBUTES

From the parent class Net::DNS::Dynamic::Proxyserver.

ask_etc_hosts

    my $adfilter = Net::DNS::Dynamic::Adfilter->new(

        ask_etc_hosts => { ttl => 3600 },        #if set, parse and resolve /etc/hosts; ttl in seconds
    );

Definition of ask_etc_hosts activates parsing of /etc/hosts and resolution of matching queries with a lifespan of ttl (in seconds).

ask_sql_hosts

If defined, the module will query an sql database of hosts, provided the database file can be accessed (read/write) with the defined uid/gid.

    my $adfilter = Net::DNS::Dynamic::Adfilter->new( 

        ask_sql => {
            ttl => 60, 
            dsn => 'DBI:mysql:database=db_name;host=localhost;port=3306',
            user => 'my_user',
            pass => 'my_password',
            statement => "SELECT ip FROM hosts WHERE hostname='{qname}' AND type='{qtype}'"
        },
        uid => 65534, #only if necessary
        gid => 65534,
    );

The 'statement' is a SELECT statement, which must return the IP address for the given query name (qname) and query type (qtype, like 'A' or 'MX'). The placeholders {qname} and {qtype} will be replaced by the actual query name and type. Your statement must return the IP address as the first column in the result.

debug

The debug option logs actions to stdout and may be set from 1-3 with increasing output: the module will feedback (1) adfilter.pm logging, (2) nameserver logging, and (3) resolver logging.

host

The IP address to bind to. If not defined, the server binds to all (*).

port

The tcp & udp port to run the DNS server under. Defaults to 53.

uid

The optional user id to switch to after the socket has been created.

gid

The optional group id to switch to after the socket has been created.

nameservers

An arrayref of one or more nameservers to forward any DNS queries to. Defaults to nameservers listed in /etc/resolv.conf.

nameservers_port

Specify the port of the remote nameservers. Defaults to the standard port 53.

CAVEATS

It will be necessary to manually adjust the host's network dns settings to take advantage of the filtering. On Mac hosts, uncommenting the networksetup system calls of adfilter.pm will automate this.

AUTHOR

David Watson <dwatson@cpan.org>

SEE ALSO

scripts/adfilter.pl in the distribution

Net::DNS::Dynamic::Proxyserver

COPYRIGHT AND LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

cpanm Net::DNS::Dynamic::Adfilter

perl -MCPAN -e shell
install Net::DNS::Dynamic::Adfilter