ADSUCK(1)

NAME
adsuck - DNS blacklisting daemon

SYNOPSIS
adsuck [-Ddv] [-c directory] [-f resolv.conf] [-l listen] [-p port] [-r regexfile] [-u user] hostsfile ...

DESCRIPTION
adsuck is a small DNS server that spoofs blacklisted addresses and forwards all other queries. The idea is to be able to prevent connections to undesirable sites such as ad servers, crawlers and other nasties. It can be used locally, for the road warrior, or on the network perimeter in order to protect machines from malicious sites.

adsuck replies to bad addresses with a spoofed DNS packet that has the NXdomain flag set. This in effect prevents the application that is resolving the address from trying to connect to this address. Addresses that are not matched are forwarded to the normal nameserver, as provided by resolv.conf(5).

Note that when applications try to be smart and resolve an address with the local domain name appended, it will still spoof the answer.

All non-spoofed responses are cached for the duration of the provided DNS TTL (Time To Live). The cache will be purged when adsuck receives a HUP or USR1 signal. See the SIGNALS section for more details.

The options are as follows:

-c directory
    This is the chroot directory. If it is not specified, it uses the home_dir entry from /etc/passwd.

-D  Do not daemonize.

-d  Enable debug output.

-f resolv.conf
    This is a standard formatted resolv.conf file that contains the name server that can resolve non-blacklisted entries.

-l listen
    This is the address adsuck will listen on. The default is all IP addresses.

-p port
    This is the port number that adsuck will bind to. The default is 53.

-r regexfile
    Filename of a file that contains one regex expression per line e.g. banner|ads|stat|track|click. When the expression is matched, the DNS response will be spoofed. The regex engine runs before the hostsfile match. See regex(3) and re_format(7) for more information.

-u user
    This is the user that adsuck will drop privileges to after it binds to the listen address. The default is _adsuck.

-v  Enable verbose output.

hostsfile
    This is a standard formatted hostsfile that contains all blacklisted entries. Examples of good blacklist files:

        http://rlwpx.free.fr/WPFF/hosts.htm
        http://www.mvps.org/winhelp2002/

SIGNALS
The adsuck daemon reacts to the following signals:
HUP reevaluate resolv.conf and purge cache
USR1
    reread hosts and regex files and purge cache
USR2
    output runtime stats using syslog

NOTE: when supported by the OS adsuck will monitor resolv.conf for changes and therefore alleviate the need for external stimuli via HUP. Currently only OS' with kqueue/kevent functionality support this.

FILES

hostsfile
    Blacklist entries in standard hostsfile format. The entries must point to 127.0.0.1. E.g. 127.0.0.1 badsite.com.

    If the entry points to a different address then the spoofing will not be done via NXdomain but will instead return the provided IP address. This enables the administrator to forward specific sites to an IP address that might contain a warning. In order to spoof badsite.com to 192.168.0.1 add "192.168.0.1 badsite.com" to a hostsfile.

resolv.conf
    Standard resolv.conf file that contain the actual resolving nameserver and options.

    Note: due to the way ldns works one can NOT specify a port in the resolv.conf file.

SEE ALSO
resolv.conf(5)

HISTORY
adsuck was written to do some smarter ad blocking without using individual browser components and to avoid lengthy hostsfile lookups.

AUTHORS
-nosplit

adsuck was written by Marco Peereboom <marco@peereboom.us>.

BUGS
Currently adsuck depends on ldns.