NAME
Net::DNS::Dynamic::Adfilter - A DNS ad filter
VERSION
version 0.067
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.
The module loads externally maintained lists of ad hosts intended for use by Adblock Plus, a popular ad filtering extension for the Firefox browser. Use of the lists focuses only on third-party listings, since these generally define dedicated ad/tracking hosts.
A locally maintained blacklist/whitelist can also be loaded. In this case, host listings must conform to a one host per line format.
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
adblock_stack
my $adfilter = Net::DNS::Dynamic::Adfilter->new(
adblock_stack => [
{
url => 'http://pgl.yoyo.org/adservers/serverlist.php?hostformat=adblockplus&showintro=0&startdate[day]=&startdate[month]=&startdate[year]=&mimetype=plaintext',
path => '/var/named/pgl-adblock.txt', #path to ad hosts
refresh => 7, #refresh value in days (default = 7)
},
{
url => 'abp:subscribe?location=https%3A%2F%2Feasylist-downloads.adblockplus.org%2Feasyprivacy.txt&title=EasyPrivacy&requiresLocation=https%3A%2F%2Feasylist-downloads.adblockplus.org%2Feasylist.txt&requiresTitle=EasyList';
path => '/var/named/easyprivacy.txt',
refresh => 5,
},
],
);The adblock_stack arrayref encloses one or more hashrefs composed of three parameters: a url that returns a list of ad hosts in adblock plus format; a path string that defines where the module will write a local copy of the list; a refresh value that determines what age (in days) the local copy may be before it is refreshed.
There are dozens of adblock plus filters scattered throughout the internet. You can load as many as you like, though one or two lists such as those listed above should suffice.
A collection of lists is available at http://adblockplus.org/en/subscriptions. The module will accept standard or abp:subscribe? urls. You can cut and paste encoded subscription links directly.
blacklist
my $adfilter = Net::DNS::Dynamic::Adfilter->new(
blacklist => {
path => '/var/named/blacklist', #path to secondary hosts
},
);The blacklist hashref contains only a path string that defines where the module will access a local list of ad hosts to nullify. As mentioned above, a single column is the only acceptable format:
# ad nauseam
googlesyndication.com
facebook.com
twitter.com
...
adinfinitum.comwhitelist
my $adfilter = Net::DNS::Dynamic::Adfilter->new(
whitelist => {
path => '/var/named/whitelist', #path to whitelist
},
);The whitelist hashref, like the blacklist hashref, contains only a path parameter to a single column list of hosts. These hosts will be removed from the filter.
LEGACY ATTRIBUTES
From the parent class Net::DNS::Dynamic::Proxyserver.
host
The IP address to bind to. If not defined, the server binds to all (*). This might not be possible on some networks. Use the host's local ip address.
port
The tcp & udp port to run the DNS server under. Defaults to 53.
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.
debug
The debug option logs actions to stdout and can be set from 1-3 with increasing output: the module will feedback (1) adfilter.pm logging, (2) nameserver logging, and (3) resolver logging.
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.
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.
CAVEATS
It will be necessary to manually set dns settings to the host's local ip in order to take advantage of the filtering. On Mac hosts, uncommenting the networksetup system calls in the module 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.