FreeBSD Manual Pages
dns2blackhole(8) System Manager's Manual dns2blackhole(8) NAME dns2blackhole -- Malware Prevention through Domain Blocking (Black Hole). DESCRIPTION dns2blackhole is a set of Bourne Shell csh scripts that fetch host files from public host file providers that contain the FQDN [ Fully Qualified Domain Names ] of sites that fall into the following categories, adware, malware, exploit, hijackers, harvesters, tracking, phishing, fake news, fraud, spam, sex, porn, gambling, advertisements, misleading marketing, illegal pharmacy, warez/piracy and others. The output of the dns2blackhole scripts may be fed directly into the ports/package versions of unbound, named, or dnsmask DNS servers to block those FQDN thus protecting user devices from being compromised or bothered seeing things of no interest. The base built-in version of unbound titled "local_unbound" can also be configured to work using the dns2blackhole method. This black hole method is another layer of protection that you can customize to your needs. These public host file providers in general have staffs that collect, analyze and create FQDN lists which are available to the general public. The collection of data may utilize software that rolls through ranges of IP addresses world wide simulating a browser behavior allowing itself to be compromised. The data acquired is then analyzed and placed in the hosts file if it's determined to be detrimental to a normal browser. These are the things people want to protect their computers from. Host files first started to be created in the past when harmful sites were less than 100. These host files were used to feed into Unix flavored operating systems /etc/host files and Microsoft Windows host files. This is how they got their name which continues in use to today even though the hosts files are now too large to function in the operating system host file without causing severe slow downs. How does blocking work. Most DNS server software have their own record syntax for passing a list of FQDN to the server telling the server to return a NOT found reply without doing a public internet DNS request lookup. This not only speeds up the loading of browser pages but also protects other applications from accessing those sites. Memory limits. There is a relationship between the memory size of the computer and how large of a FQDN list can be loaded into the dns server your using. The dns2blackhole-update1 script creates a FQDN list of 130,100 entries that has been tested loading into a computer with 2 GB of memory. The dns2blackhole-update2 script creates a FQDN list of 1.6 million entries that has been tested loading into a computer with 16 GB of memory. You may try commenting out some file fetches in dns2blackhole-update2 to make the resulting FQDN list smaller to see if it will load on your computer's memory size. dns2blackhole and unbound server. The dns2blackhole Bourne Shell csh scripts are customized for use with the unbound server as installed from the ports or package system. The update1 and update2 scripts have alternate commented out code to work with named and dnsmask DNS servers. Just follow the comments in those scripts for instructions. A unbound.conf file is included to simplify unbound setup. 1. Execute dns2blackhole-update1 At the end of this script it has the "servive unbound restart" command that will cause a message. You can ignore this message because we have not installed unbound yet. "unbound does not exist in /etc/rc.d or the local startup directories (/usr/local/etc/rc.d), or is not executable" 2. Install unbound by issuing "pkg install unbound" or using the port method. 3. In the /etc/rc.conf file, comment out this if it's there local_unbound_enable="YES" and add unbound_enable="YES" The built-in local_unbound version can not co-exist with the port/package version of unbound. Select one or the other. 4. Bkup resolv.conf cp /etc/resolv.conf /etc/resolv.conf.org Delete the contents of the /etc/resolv.conf and add this line nameserver 127.0.0.1 Make it immutable using "chflags -R schg /etc/resolv.conf" This makes it un-writable by anyone, Contents will never change. This stops /etc/resolv.conf being refreshed at boot time with DNS information from your ISP over riding the nameserver 127.0.0.1 statement needed to drive host dns requests to unbound. Use "ls -lo /etc/resolv.conf" to see its flags. Use "chflags -R noschg /etc/resolv.conf" to return to normal. 5. Copy /usr/local/etc/dns2blackhole/dns2blackhole-unbound.conf to /usr/local/etc/unbound/unbound.conf 6. If you have a LAN behind this host and want those LAN device's DNS requests to also go through the hosts unbound server. Change the hosts DHCP server config file DNS IP address to the LAN IP address assigned to the host network adapter the LAN is on. 7. Reboot your system to enable the configration changes and auto start unbound. dns2blackhole and local_unbound server. 1. Edit the /usr/local/bin/dns2blackhole-update1 and update2 scripts and follow the comments to enable local_unbound use. All it takes is un-commiting two lines near the front of the script. 2. Execute dns2blackhole-update1 At the end of this script it has the "servive local_unbound restart" command that will cause a message. You can ignore this message because we have not enabled local_unbound yet. "Cannot 'restart' local_unbound. Set local_unbound_enable to YES in /etc/rc.conf or use 'onerestart' instead of 'restart'." 3. The base built-in version of unbound titled "local_unbound" is disabled by default until the local_unbound_enable="YES" line is added to the /etc/rc.conf file and the system is re-booted. As part of the first boot process some configureation files are automaticly created. It is mandatory that this "first boot" be accomplished first before continuing with the following steps. 4. Bkup resolv.conf cp /etc/resolv.conf /etc/resolv.conf.org Delete the contents of the /etc/resolv.conf and add this line nameserver 127.0.0.1 Then make it immutable using "chflags -R schg /etc/resolv.conf" This makes it un-writable by anyone, Contents will never change. This stops /etc/resolv.conf being refreshed at boot time with DNS information from your ISP over riding the nameserver 127.0.0.1 statement needed to drive host dns requests to unbound. Use "ls -lo /etc/resolv.conf" to see its flags. Use "chflags -R noschg /etc/resolv.conf" to return to normal. 5. Bkup resolvconf.conf cp /etc/resolvconf.conf /etc/resolvconf.conf.org Delete the contents of the /etc/resolvconf.conf and add this line libc=NO Please note that the word "NO" is upper case. 6. Bkup unbound.conf cp /var/unbound/unbound.conf /var/unbound/unbound.conf.org Copy /usr/local/etc/dns2blackhole/dns2blackhole-unbound.conf to /var/unbound/unbound.conf Edit the /var/unbound/unbound.conf file and follow the comments to enable local_unbound. 7. If you have a LAN behind this host and want those LAN device's DNS requests to also go through the hosts local_unbound server. Change the hosts DHCP server config file DNS IP address to the LAN IP address assigned to the host network adapter the LAN is on. 8. Issue the "service local_unbound restart" command. Host file providers. As of 09/11/2017 every public host file provider identifiable on the internet is fetched by the dns2blackhole update1 and update2 scripts. The only difference between them is update1 fetches providers that provide text host files and update2 fetches providers that provide compressed host files. Many really bad FQDN sites are contained in many of the individual provider hosts files. Rest assured that these duplicates are removed before being fed to the DNS server software being used. All host file providers are not as diligent at removing FQDN that are no longer registered in the public DSN system as some of the other providers. Adding these unknown dead FQDN to the DNS server being used causes no harm. If in the future you identify additional host files it's very easy to add them to either of the 2 update scripts. The output of update1 and update2 combined together yield 1.6 million blocked FQDN, and that size will continue to grow for sure. WhiteListing or BlackListing your own FQDN. BlackListing is the way you add your own FQDN of sites you want blocked. WhiteListing is the way you remove some FQDN that are contained in the downloaded provider host files that you don't want blocked any longer. You edit whitelist.txt or the blacklist.txt files in /usr/local/etc/unbound directory adding your FQDN starting in position one of each line. Do not leave a blank line at the end of the file. You then run the update1 and or update2 to get your whitelist.txt and/or blacklist.txt files applied. These two files are the permanent way to apply your customized configuration across host file updates. Be careful to not delete them or you will have to start from scratch to re-build their content. The quick and dirty method is to edit the fqdn-list file deleteing the FQDN you don't want blocked IE: WhiteListed. Or adding FQDN you want blocked IE: BlackListed. Then enable the new content by issuing the "service unbound restart" command. dns2blackhole files. dns2blackhole.8 This man page your reading now dns2blackhole-unbound.conf Pre-configured unbound.conf file dns2blackhole-update1 updates all host text files dns2blackhole-update2 updates all host compressed files dns2blackhole-sanitize sub-routine used by update1 & update2 dns2blackhole-sort-fqdn sub-routine used by update1 & update2 dns2blackhole-whitelist sub-routine used by update1 & update2 dns2blackhole usage. At your choice, update1 can be run without update2. Note that update2 has option to auto install the 7zip package and use it to un-compress the downloaded files or default to using tar to un-compress the downloaded files. Read the comments in update2 for details. The host file providers do not update their downloadable files on a dependable cycle. Somewhere between 2 to 12 times a year. If you decide to run the update scripts as a crom job more often that monthly, it would just be a waste of process time. Unbound setup instructions. 1. unbound comes with a built-in "root zone" which negates the need for a "forward-zone: section" all together. This built-in "root zone" sends DNS requests to the up-stream public DSN servers. Verify that your host firewall doesn't have rules restricting port 53 to using only your ISP's DNS IP addresses. 2. Use service unbound restart command after making changes to the content of your unbound.conf file. Note: Any unbound.conf content errors causes the unbound server to not start. This means ALL DNS requests go un-serviced, basically your host system and LAN users are dead in the water until you fix things. The service unbound stop command results in the same thing. 3. Take note: The unbound man pages are not FreeBSD specific. Unbound is open source software that runs on many different platforms so it's man pages have to be general in content. Some statements and ideas expressed are incorrect based on the FreeBSD way of doing things. 4. The /usr/local/etc/unbound/unbound.conf.sample file shows all the possible options available in the unbound.conf file. The defaults are designed to create a running unbound server. In most all cases the following working unbound.conf file contains the default over rides necessary for a working unbound server. # Start of the working unbound.conf file. # Server config section. server: # For the unbound port/package version use this directory: /usr/local/etc/unbound chroot: "/usr/local/etc/unbound" chroot: "" # disable chroot pidfile: /usr/local/etc/unbound/unbound.pid include: /usr/local/etc/unbound/fqdn-list # For the local_unbound version use this # directory: /var/unbound # chroot: /var/unbound # chroot: "" # disable chroot # pidfile: /var/run/local_unbound.pid # include: /var/unbound/fqdn-list # Specify the interfaces to answer queries from by ip-address. # The default is to listen to localhost (127.0.0.1 and ::1) only. # Specify 0.0.0.0 and ::0 to bind to all available interfaces. interface: ::0 # listen on all ipv6 interfaces interface: 0.0.0.0 # listen on all ipv4 interfaces # Control which clients are allowed to make (recursive) queries # to this server. Specify classless netblocks with /size and action. # By default everything is refused, except for localhost. # Example 10.0.0.0/8 is the ip address block assigned to the LAN. access-control: 10.0.0.0/8 allow access-control: 127.0.0.0/8 allow # Remote control config section. # Remote control must be enabled before the unbound-control(8) # command can be used to send commands to the running unbound server. # To enable security, execute the unbound-control-setup command # to set up the keys and certificates. # This remote-control: section enables remote-control with # security disabled. remote-control: control-enable: yes control-interface: /var/run/unbound.ctl control-use-cert: no AUTHOR Joe Barbish <dns2blackhole@a1poweruser.com> FreeBSD ports 15.0 October 22, 2017 dns2blackhole(8)
NAME | DESCRIPTION | How does blocking work. | Memory limits. | dns2blackhole and unbound server. | dns2blackhole and local_unbound server. | Host file providers. | WhiteListing or BlackListing your own FQDN. | dns2blackhole files. | dns2blackhole usage. | Unbound setup instructions. | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dns2blackhole&sektion=8&manpath=FreeBSD+Ports+15.0>