Follow the conversation @ community.ubnt.com

Please show your thanks by donating to the project using Square Cash or PayPal

We greatly appreciate any and all donations - Thank you! Funds go to maintaining development servers and networks.

1. Overview
2. Donate
3. Copyright
4. Licenses
5. Latest Version
6. Change Log
7. Features
8. Compatibility
9. Installation
   1. Using apt-get
   2. Using dpkg
10. Upgrade
11. Reconfigure
12. Removal
13. Frequently Asked Questions
    1. Can I donate to project?
    2. Does the install backup my blacklist configuration before deleting it?
    3. Does update-dnsmasq run automatically?
    4. How do I add or delete sources?
    5. How do I back up my blacklist configuration and restore it later?
    6. How do I configure dnsmasq?
    7. How do I configure local file sources instead of internet based ones?
    8. How do I disable/enable dnsmasq blacklisting?
    9. How do I exclude or include a host or a domain?
    10. How do I globally exclude or include hosts or a domains?
    11. How do I use the command line switches?
    12. How do can keep my USG configuration after an upgrade, provision or reboot?
    13. How does whitelisting work?
    14. What is the difference between blocking domains and hosts?
    15. Which blacklist sources are installed by default?

EdgeMax dnsmasq DNS blacklisting and redirection is inspired by the users at EdgeMAX Community

[Top]

• Copyright © 2020 Helm Rock Consulting

[Top]

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the FreeBSD Project.

[Top]

• Refactor code to conserve RAM in small memory systems (e.g. ER-X)
• 11Mb less RAM consumption with default lists

[Top]

• See changelog for details.

[Top]

• Adds DNS blacklisting integration to the EdgeRouter configuration
• Generates configuration files used directly by dnsmasq to redirect dns lookups
• Integrated with the EdgeMax OS CLI
• Any FQDN in the blacklist will force dnsmasq to return the configured dns redirect IP address

[Top]

• edgeos-dnsmasq-blacklist has been tested on the EdgeRouter ERLite-3, ERPoe-5, ER-X, ER4 UniFi Security Gateway USG3 and USG4 routers
  • EdgeMAX versions: v1.9.7+hotfix.4-v2.0.8, UniFi: v4.4.12-v4.4.44.5213871

[Top]

• Using apt-get - works for all routers
• Using dpkg - best for disk space constrained routers

[Top]

• Add the blacklist debian package repository using the router's CLI shell

configure
set system package repository blacklist components main
set system package repository blacklist description 'Britannic blacklist debian stretch repository'
set system package repository blacklist distribution stretch
set system package repository blacklist url 'https://raw.githubusercontent.com/britannic/debian-repo/master/blacklist/'
commit;save;exit

• Add the GPG signing key

sudo curl -L https://raw.githubusercontent.com/britannic/debian-repo/master/blacklist/public.key | sudo apt-key add -

• Update the system repositorities and install edgeos-dnsmasq-blacklist

sudo apt-get update && sudo apt-get install edgeos-dnsmasq-blacklist

[Top]

curl -L -O https://raw.githubusercontent.com/britannic/blacklist/master/edgeos-dnsmasq-blacklist_1.1.8.1_mips.deb
sudo dpkg -i edgeos-dnsmasq-blacklist_1.1.8.1_mips.deb

[Top]

• Ensure the router has enough space, by removing unnecessary files

sudo apt-get clean cache
delete system image

• Now download and install the edgeos-dnsmasq-blacklist package

curl -L -O https://raw.githubusercontent.com/britannic/blacklist/master/edgeos-dnsmasq-blacklist_1.1.8.1_mipsel.deb
sudo dpkg -i edgeos-dnsmasq-blacklist_1.1.8.1_mipsel.deb

[Top]

• If the repository is set up and you are using apt-get:

sudo apt-get update && sudo apt-get upgrade edgeos-dnsmasq-blacklist

• Note, if you are using dpkg, it cannot upgrade packages, so follow these instructions and the previous package version will be automatically removed before the new package version is installed

[Top]

• If the Unifi Security Gateway has been re-provisioned you might need to re-enable the blacklists, in order to do so run:

sudo dpkg-reconfigure edgeos-dnsmasq-blacklist

[Top]

sudo apt-get remove --purge edgeos-dnsmasq-blacklist

[Top]

• Use these CLI configure commands:
• Disable:

configure
set service dns forwarding blacklist disabled true
commit;save;exit

• Enable:

configure
set service dns forwarding blacklist disabled false
commit;save;exit

[Top]

• If a blacklist configuration already exists, the install routine will automatically back it up to /config/user-data/blacklist.$(date +'%FT%H%M%S').cmds

[Top]

• use the following commands (make a note of the file name):

export DATE=$(date +'%FT%H%M%S'); echo "Backing up blacklist configuration to: /config/user-data/blacklist.${DATE}.cmds"; show configuration commands | grep blacklist > /config/user-data/blacklist.$(date +'%FT%H%M%S').cmds

• After installing the latest version, you can merge your backed up configuration:

configure
.  /config/user-data/blacklist.[date string].cmds
commit;save;exit

• If you prefer to delete the default configuration and restore your previous configuration, run these commands:

configure
delete service dns forwarding blacklist
.  /config/user-data/blacklist.[date string].cmds
commit;save;exit

[Top]

• Use these CLI shell commands to view the current sources or scan the log for previous downloads:

show configuration commands | match source
grep downloaded /var/log/update-dnsmasq.log

[Top]

• Use these commands to configure a local file source

set service dns forwarding blacklist hosts source myhosts description 'Blacklist file source'
set service dns forwarding blacklist hosts source myhosts dns-redirect-ip 0.0.0.0
set service dns forwarding blacklist hosts source myhosts file /config/user-data/blist.hosts.src

• File contents example for /config/user-data/blist.hosts.src:

gsmtop.net
click.buzzcity.net
ads.admoda.com
stats.pflexads.com
a.glcdn.co
wwww.adleads.com
ad.madvertise.de
apps.buzzcity.net
ads.mobgold.com
android.bcfads.com
req.appads.com
show.buzzcity.net
api.analytics.omgpop.com
r.edge.inmobicdn.net
www.mmnetwork.mobi
img.ads.huntmad.com
creative1cdn.mobfox.com
admicro2.vcmedia.vn
admicro1.vcmedia.vn

[Top]

• Follow these instructions on how to automatically install edgeos-dnsmasq-blacklist
• Generate and download a config.gateway.json file from your USG following these instructions
• Here's a sample config.gateway.json
• Once the config.gateway.json has been generated, it will need to be uploaded to your UniFi controller per the instructions

[Top]

• Using the CLI configure command, to delete domains and hosts sources:

configure
delete service dns forwarding blacklist domains source malc0de
delete service dns forwarding blacklist hosts source yoyo.org
commit;save;exit

• To add a source, first check it can serve a text list and also note the prefix (if any) before the hosts or domains, e.g. http://www.malwaredomainlist.com/ has this format:

#               MalwareDomainList.com Hosts List           #
#   http://www.malwaredomainlist.com/hostslist/hosts.txt   #
#         Last updated: Mon, 04 Dec 17 19:18:42 +0000      #


127.0.0.1  localhost
127.0.0.1  0koryu0.easter.ne.jp
127.0.0.1  109-204-26-16.netconnexion.managedbroadband.co.uk
127.0.0.1  1866809.securefastserver.com

• So the prefix is "127.0.0.1 "
• Here's how to creating the source in the CLI:

configure
set service dns forwarding blacklist hosts source malwaredomainlist description '127.0.0.1 based host and domain list'
set service dns forwarding blacklist hosts source malwaredomainlist prefix '127.0.0.1  '
set service dns forwarding blacklist hosts source malwaredomainlist url 'http://www.malwaredomainlist.com/hostslist/hosts.txt'
commit;save;exit

[Top]

• Use these example commands to globally include or exclude blacklisted entries:

configure
set service dns forwarding blacklist exclude cdn.visiblemeasures.com
set service dns forwarding blacklist include www.nastywebsites.com
commit;save;exit

[Top]

• Use these example commands to include or exclude blacklisted entries:

configure
set service dns forwarding blacklist domains exclude visiblemeasures.com
set service dns forwarding blacklist domains include domainsnastywebsites.com
set service dns forwarding blacklist hosts exclude cdn.visiblemeasures.com
set service dns forwarding blacklist hosts include www.nastywebsites.com
commit;save;exit

[Top]

*dnsmasq will whitelist any entries in the configuration file domains and hosts (servers) with a hash in place of an IP address (the "#" force dnsmasq to forward the DNS request to the router's configured nameservers)

• i.e. servers (hosts)

server=/www.bing.com/#

• i.e. domains

address=/bing.com/#

[Top]

• Yes, a scheduled task is created and run daily at midnight with a random start delay is used ensure other routers in the same time zone won't overload the source servers.
• The random start delay window is configured in seconds using this command - this example sets the start delay between 1-10800 seconds (0-3 hours):

set system task-scheduler task update_blacklists executable arguments 10800

• It can be reconfigured using these CLI configuration commands:

set system task-scheduler task update_blacklists executable path /config/scripts/update-dnsmasq-cronjob.sh
set system task-scheduler task update_blacklists executable arguments 10800
set system task-scheduler task update_blacklists interval 1d

• For example, to change the execution interval to every 6 hours, use this command:

set system task-scheduler task update_blacklists interval 6h

• In daily use, no additional interaction with update-dnsmasq is required. By default, cron will run update-dnsmasq at midnight each day to download the blacklist sources and update the dnsmasq configuration files in /etc/dnsmasq.d. dnsmasq will automatically be reloaded after the configuration file update is completed.

[Top]

• update-dnsmasq has the following commandline switches available:

/config/scripts/update-dnsmasq -h
    -dir string
            Override dnsmasq directory (default "/etc/dnsmasq.d")
    -f [full file path]
            [full file path] # Load a config.boot file
    -h   Display help
    -v   Verbose display
    -version
            Show version

[Top]

• dnsmasq may need to be configured to ensure blacklisting works correctly
  • Here is an example using the EdgeOS configuration shell

configure
set service dns forwarding cache-size 2048
set service dns forwarding except-interface [Your WAN i/f]
set service dns forwarding name-server [Your choice of IPv4 Internet Name-Server]
set service dns forwarding name-server [Your choice of IPv4 Internet Name-Server]
set service dns forwarding name-server [Your choice of IPv6 Internet Name-Server]
set service dns forwarding name-server [Your choice of IPv6 Internet Name-Server]
set service dns forwarding options bogus-priv
set service dns forwarding options domain-needed
set service dns forwarding options domain=mydomain.local
set service dns forwarding options enable-ra
set service dns forwarding options expand-hosts
set service dns forwarding options localise-queries
set service dns forwarding options strict-order
set service dns forwarding system
set system name-server 127.0.0.1
set system name-server '::1'
commit; save; exit

[Top]

• The difference lies in the order of update-dnsmasq's processing algorithm. Domains are processed first and take precedence over hosts, so that a blacklisted domain will force update-dnsmasq's source parser to exclude subsequent hosts from the same domain. This reduces dnsmasq's list of lookups, since it will automatically redirect hosts for a blacklisted domain.

[Top]