Follow the conversation @ community.ui.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.
- Overview
- Donate
- Copyright
- Licenses
- Latest Version
- Change Log
- Features
- Compatibility
- Installation
- Upgrade
- Reconfigure
- Removal
- Frequently Asked Questions
- Can I donate to project?
- Does the install backup my blacklist configuration before deleting it?
- Does update-dnsmasq run automatically?
- How do I add or delete sources?
- How do I back up my blacklist configuration and restore it later?
- How do I configure dnsmasq?
- How do I configure local file sources instead of internet based ones?
- How do I use standalone or failover mode?
- How do I disable/enable dnsmasq blacklisting?
- How do I exclude or include a host or a domain?
- How do I globally exclude or include hosts or a domains?
- How do I use the command line switches?
- How do can keep my USG configuration after an upgrade, provision or reboot?
- How does whitelisting work?
- What is the difference between blocking domains and hosts?
- Which blacklist sources are installed by default?
- How do I troubleshoot dnsmasq blacklisting?
EdgeMax dnsmasq DNS blacklisting and redirection is inspired by the users at Ubiquiti UISP Community
- Copyright © 2023 Helm Rock Consulting
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
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.
-
Fixed Issue #66 documentation issue* Fixed Issue #56 removed large source StevenBlack/hosts as it prevented dnsmasq from starting on ER-X routers
-
It can be installed using
set service dns forwarding blacklist hosts source githubSteveBlack url 'https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts'
set service dns forwarding blacklist hosts source githubSteveBlack description 'Blacklists adware and malware websites'
set service dns forwarding blacklist hosts source githubSteveBlack prefix '0.0.0.0 '- See changelog for details.
- 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
- 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.6-v2.0.9-hotfix.6
- UniFi versions: 4.4.34.5140624-4.4.57.5578372
- Using apt-get - works for all routers
- Using dpkg - best for disk space constrained routers
- 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/public/'
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 -f edgeos-dnsmasq-blacklist- You may see reports of unmet dependencies, run this command to fix that:
apt --fix-broken installcurl -L -O https://raw.githubusercontent.com/britannic/blacklist/master/edgeos-dnsmasq-blacklist_1.2.4.9_mips.deb
sudo dpkg -i edgeos-dnsmasq-blacklist_1.2.4.9_mips.deb- 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.2.4.9_mipsel.deb
sudo dpkg -i edgeos-dnsmasq-blacklist_1.2.4.9_mipsel.deb- If the repository is set up and you are using apt-get:
sudo apt-get update && sudo apt-get install -f --only-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
- 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-blacklistsudo apt-get remove --purge edgeos-dnsmasq-blacklist- 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- 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
- use the following commands (make a note of the file name) in the shell (not in configure):
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- 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- 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-
The update-dnsmasq binary checks for an active configuration in the following locations:
- Uses the EdgeOS/UniFi shell API to get the active blacklist configuration
- /config/config.boot (only used if -safe switch is used)
- /config/user-data/blacklist.failover.cfg (only used if it has been created and the -safe switch is used)
-
If no configuration is found, update-dnsmasq will remove any dnsmasq blocklists it previously created
- 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
- Alternatively follow the instructions for how do I use standalone or failover mode?
- 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. No Coin Filter has this format:
# No Coin Filter List #
# https://raw.githubusercontent.com/hoshsadiq/adblock-nocoin-list/master/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 nocoinfilterlist description '127.0.0.1 based host and domain list'
set service dns forwarding blacklist hosts source nocoinfilterlist prefix '127.0.0.1 '
set service dns forwarding blacklist hosts source nocoinfilterlist url 'https://raw.githubusercontent.com/hoshsadiq/adblock-nocoin-list/master/hosts.txt'
commit;save;exit- 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- 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- dnsmasq whitelists any entries it finds in the configuration files domains and hosts (or servers) that have a hash in place of the IP address (the "#" forces dnsmasq to forward the DNS request to the router's configured nameservers)
- e.g. for servers (hosts)
server=/www.bing.com/#- e.g. for domains
address=/bing.com/#- 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.
- update-dnsmasq has the following commandline switches available:
/config/scripts/update-dnsmasq -h
-dir string
Override dnsmasq directory (default "/etc/dnsmasq.d")
-f <file>
<file> # Load a config.boot file
-h Display help
-safe
Fail over to /config/user-data/blacklist.failover.cfg
-v Verbose display
-version- 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- 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.
- View last update log:
tail /var/log/update-dnsmasq.log
Total entries extracted = Total sites blocked
Timestamp = Last time the update ran- Manually update the dnsmasq configuration files from sources:
sudo /config/scripts/update-dnsmasq -v- Check if a domain or hostname is being blocked or manually excluded:
grep [host.domain.tld] /etc/dnsmasq.d/*- Or:
grep [domain.tld] /etc/dnsmasq.d/*
-
Note: If the domain/hostname is manually excluded it will appear in one of the *.whitelisted-*.conf files
-
Display installed edgeos-dnsmasq-blacklist version:
sudo /config/scripts/update-dnsmasq -version