This menu contains settings to configure FreshTomato's ad blocker. It is strongly advised that you read the How Adblock Works section to understand its functioning, even if you use v2.
In this documentation, the function/menu will be spelled capitalized (“Adblock”). The script that executes will be spelled in lower case (“adblock”).
There are currently two versions of Adblock: adblock_v1 and adblock_v2.
This table lists the Adblock versions available on different types of hardware
Adblock v1 functionality is a reduced version of ad-blocking scripts taken from code outside FreshTomato. Enabling one of those scripts and FreshTomato Adblock at the same time may cause conflicts. Do not enable both.
Adblock v2 uses advanced methods to block ads. It should be the preferred choice whenever possible.
FreshTomato's Adblock works through DNS cache poisoning, as follows:
Given a list of sources, the original script simply blocks ads. However, there are other reasons for your network to avoid communicating with certain servers. Therefore, this function was renamed to reflect its progression towards a wider function: “DNS filtering”.
Enable: Checking this box turns on Adblock.
The adblock script downloads lists of URLs/domains to block, mostly from the Blacklist URL & Group-of-lists table. You can select or deselect any list in this table to be included in the downloads (the “blocklist”).
Debug mode (v1)
Checking this box enables debug mode for dnsmasq in the log. This tells FreshTomato that you want all DNS queries routed to dnsmasq to be logged to the system log (syslog). This is useful when testing/troubleshooting Adblock. For more on testing, see the Notes and Troubleshooting section of this page. This option is identical to “Debug Mode” in the DHCP/DNS/TFTP menu. Thus, in v2, it was removed from the Adblock menu.
Max Log Level (v2):
Thew new v2 interface lets you set the maximum log level output the script will generate.
Supported levels include:
The higher the setting, the more detailed will be the information recorded in the logs.
A good way to view the logs is to go to the Logs menu and enter 'adblock' in the “Find in syslog” field. This filters the log view to show only entries adblock entries. At level 7, adblock produces additional debugging files. These files are saved in /tmp/adblock.debug.$now, (where “$now” is the absolute number of seconds elapsed). References to adblock in the the trace file will then be displayed in the Web interface.
Blockfile size limit (v2 only):
Adblock v1 may crash FreshTomato if it loads lists whose combined information exceeds your router's resource capacity. This can be difficult to assess and troubleshoot. Adblock v2 comes with a customizable “limit” field. If the limit field is left empty, FreshTomato will calculate its value automatically. It will also calculate the value automatically if the router was reset to defaults.
This limit is calculated as 10% of physical RAM (when external storage is set). When no external storage is found, the limit is calculated as 6.5% of RAM. The limit can be also manually configured. However, if your device becomes unstable, it is advised that you revert to the automatically-calculated value.
To be clear, this is a limit, not a target. There's nothing wrong with having a small blockfile compared to the limit. A larger blockfile will result in longer restart times for the dnsmasq service. This is important because there will be no DHCP/DNS/TFTP functionality until dnsmasq finishes restarting.
Custom Path (v2):
An important v2 feature is the ability to configure an (optional) path to permanent storage where adblock can store relevant files. You are strongly advised to specify a custom path. A custom path enables extra functionality in the script. It allows adblock to store whole lists, their http headers and the actual compiled blockfile on external storage. This offloads RAM demand (/tmp) to permanent storage, and allows for information to survive a reboot.
This is very useful when the script is re-run (manually or automatically) and there are no updated lists or configuration changes. The check for configuration changes involves controlling any modification to nvram variables since the last script run.
When a custom path is defined, adblock will:
This runs as follows:
This saves time and resources.
Here, configuration means any externally-mapped files where blacklist_custom or whitelists are defined (For example: /mnt/USB/my_whitelist.txt). Using a Custom path also allows adblock to load faster on post-(re)boot.
This table contains a list of the blacklists FreshTomato can download and use to block ads.
On: Checking this box at the left will make a gold star appear. The star confirms Adblock will enable downloading of the blacklist in that row. When you're finished selecting which blacklists you wish to use, click Save.
Blacklist URL: This shows the location on the Internet where that blacklist can be found.
Description: Displays a name (if the publisher used one) or reference for the blacklist in that row.
Delete: If you move your mouse over a row containing a blacklist, a red “x” appears at the end of the row. Clicking “x” will delete that row, permanently deleting that blacklist.
There is no option to reset these to the original Blacklist URL entries.
If you delete a URL that's important to you, you will need to:
Add: Clicking this inserts a blank row. In this row, you can type a new URL from which to download and use an additional Blacklist URL.
You can also add a comment in the Description field.
Target lists to be downloaded must be in plain text format. As above, v2 can extract domains from lists in a variety of formats. Essentially, adblock uses a regex against each line of the file. Lines from the source file are parsed, comments are removed and then the domains are extracted. This is true regardless of where (in which column) those domains are in the list.
Group-of-lists
Currently, v2 also accepts a new list format called “Group-of-lists”. This involves feeding the script a URL which contains links to a list of furhter URLs. The Group-of-lists is an excellent way to save NVRAM space.
This can be visualized as follows:
URL |--> list
or
URL |--> Group-of-lists-file |--> URL |--> list |--> URL |--> List |--> URL |--> List |--> URL |--> List
The Group-of-lists format has limitations. One limitation is that it doesn't perform verification of the lists to assess whether they need to be downloaded or not.
adblock automatically handles EOL (End of Line) characters in files, when necessary. It converts them internally.
Group-of-lists are visible in the log file. For example, they might appear as: “[8][2]” The text in this example would mean that adblock is processing the 8th defined list in the Domain blacklist URLs & Group-of-lists on the second line (URL).
Several syntaxes are valid for this list:
Any line starting with a “#” or “!” character is considered a comment and will be ignored.
Sort a-z ↓ : Clicking this button sorts the contents of this field alphabetically.
Domain whitelist can use:
Any line starting with a “#” or “!” character is considered commented and ignored.
Sort a-z ↓ : Clicking this button sorts the field content alphabetically.
A good way to maintain the whitelist is to share it on your LAN, and educate users about nslookup verification and whitelist additions.
Such a process could be automated as follows:
/usr/sbin/adblock update
function .
For Adblock to work properly, client devices must be configured to use FreshTomato's IP address (dnsmasq) as their DNS server. This can be done by configuring a static IP address on the client device itself or through FreshTomato's DHCP Service.
For the latter, first enable DHCP in the Network menu. To enable the DNS server, select “Use internal DNS” under in the DHCP/DNS menu.
These steps are mandatory. Clients that bypass FreshTomato's DNS server will not have their ads blocked.
Three optional settings help ensure proper Adblock operation:
Adblock v1 functionality is a reduced version of ad-blocking scripts taken from code outside FreshTomato. Enabling one of those outside scripts and FreshTomato Adblock at the same time may cause conflicts. Do not enable both. Adblock v2 uses advanced methods to block ads. It should be the preferred choice whenever possible.
Adblock/DNS Filtering affects name resolution only. If an application communicates directly via IP address, Adblock cannot prevent that.
Thorough management of domain blocking can be tedious work. For example, with email spam, you'll probably have to deal with false positives.
Regardless of version, the script is always named “adblock”, and can be found at: /usr/sbin/adblock
Adblock v2 improves on the original (v1) script. V2 adds a richer feature set, with increased user interaction via a toolbar and command line options.
To get help with adblock at the command line, type adblock help
. This will produce the following output:
The additional debugging files can also be accessed at the command line by typing the command: adblock status
.
To open the last trace file automatically, simply type adblock trace
at a command shell. You will be prompted to select the preferred viewer in which to view the trace files.
The Controls button bar in the Advanced section let you control adblock script execution.
Refresh: There is now a refresh command at the bottom of the table. Refreshes are limited to a minimum frequency of 5 seconds. The more frequently you run refreshes, the higher the system load will climb.
Modifications to the adblock script configuration can be categorized as follows:
Only two operations from the above list can be run in Quick-run mode, as they don't require full processing:
Operations (4) and (5) are the most common actions performed when maintaining adblock script configuration. Quick-run operations are performed live on a running blockfile. Therefore, the adblock script must be loaded in order to run functions (4) or (5). A quick-run can be completed in literally seconds. A full-run may take minutes to complete. Any operations other than (4) or (5) above require a full-run.
Please note that “quick” is a temporary action and will allow your change to become immediately functional. In contrast, a successive full-run (manual or scheduled) would process added domains in the standard way.
Another feature of v2 is the ability to interact with adblock via command line.
As seen above in the “adblock help” screenshot, v2 has many more functions available to use:
Help
adblock help
= Displays a summary guide of the valid commands.
Status
adblock status
= Gives constant updates on adblock's operational status.
Start
adblock start
= This is the same as “Load” in the Web interface.
Stop
adblock stop
= This is the same ad “Unload” in the Web interface.
Update
adblock update
= This is the same as “Update” in the Web interface.
Upgrade
adblock upgrade
= This parameter checks online for new script versions. If one is available, it asks if you want to install the upgrade. This is a workaround until the next release. This will download the latest version of the script into /tmp (RAM) then mount it over the built-in version.
Since it is stored in RAM, it will be lost after a reboot. Therefore, an extra parameter is supported: adblock upgrade silent
. If an upgrade is available, this command triggers it, without prompting you. This switch may be used in the init script, to ensure the latest version runs, even after a reboot.
Test
adblock test $domain
= This switch lets you quickly troubleshoot a domain name.
Reset
adblock reset
= This is same as “Reset” in the web interface.
Clear/Clean
adblock clear
= This is the same as “Clear all files” in the web interface. It resets the blockfile maximum limit.adblock clean
Trace/Status
adblock trace
= This is a command line only function. When the script is run with Loglevel = 7, adblock is also running in “trace mode”. Every command executed by the script is saved into a trace (log/debug) file. You can find the trace file using adblock status
. Running adblock trace
will open the latest relevant trace file for you with even less effort.
Snapshot
adblock snapshot
= This is the same as “Snapshot” in the web interface.
Enable
adblock enable
= This is the same as “Enable” in the web interface.
Disable
adblock disable
= This is the same as “Disable” on the web interface.
To simplify and speed up testing of broken resolution or other DNS issues, use the “test” switch.
Typing: adblock test example.com
will quickly verify whether name resolution is functioning.
Specifically:
With these three pieces of information, you can easily assess whether a domain is blocked, non-existent, or intact.
As part of normal adblock operation, a crontable entry is added to perform a daily list update. Update times are now randomized to prevent DDoS of the list providers' servers. A new update time is set each time you run adblock stop
or reboot. The update's time window varies between 02:00 AM and 05:59 AM local time, depending on the script version you're running (original v1, modified v1, or v2).
To verify the current scheduled update time:
root@router:/# cru l | grep adblockJob
28 4 * * * /usr/sbin/adblock update #adblockJob#
In this example, it's 28 (min) 4 (am) * (Every day) * (Every month) * (Every day of the week).
This picture illustrates the syntax of crontable expressions:
For help automating/verifying correct crontable expressions, see: crontab.guru
If you stop adblock, the crontable expression is removed. This is by design.
You can test Blacklisted or Custom entries to see if Adblock is properly redirecting them by using the nslookup tool (Windows, Linux or MacOS). Simply run nslookup and enter the domain/URL to be tested. If it resolves to 0.0.0.0, then Adblock is working properly, and the domain is being blocked. You can also check FreshTomato's System log (Syslog) to see if Adblock activity is reflected there.
For example, this entry shows that dnsmasq replaced the true IP address of hbx.media.net with 0.0.0.0.
Jan 9 19:57:29 rt-n66 daemon.info dnsmasq[4872]: config hbx.media.net is 0.0.0.0
Adblock worked properly in this case.
If your router crashes, you may be using too many large Blacklists, which can exhaust available RAM. Try using smaller blacklists, or fewer large ones. Adblock v2 is much less likely to experience this issue.
There are websites available that allow you to test the effectiveness of your Adblock configuration. When doing so, please ensure you don't have any adblock/script-block plugins enabled on your browser or your results will be invalidated. Some good adblock testing sites include:
Adblock doesn't work with DoH and other Encrypted DNS lookups
Increasingly, devices are using DNSSEC, and encrypted DNS protocols, such as DoH [DNS over HTTP(S)]. Adblock does not work with these DNS lookup methods. This is because if lookup requests are encrypted or directed to a third-party server, Adblock can't intercept, and therefore can't poison them.
As mentioned earlier, enabling the “DoH Server” in the Blacklist URL table may remedy this problem. It will download and then block access to common DoH servers.
For troubleshooting, it is recommended that you set the loglevel setting at 7, (as described in the Settings section above). Then, analyze the logs and trace file. It's surprising how often the list providers suffer from issues such as downtime, or a broken cache. It's common to see adblock fail to download a list one day but successfully download it the next day without changes to your settings.
In order to learn what might be going wrong, it's crucial to understand adblock's status indicators. Here are a few signs which may indicate a problem:
If the Blockfile size exceeds the Blockfile size limit value, the blockfile size will be reduced. If (with limit manually set high) dnsmasq still struggles to run properly after this, the safeDnsmasqRestart() process will reduce the Blockfile size in increments of 5% and reattempt to fully start dnsmasq after each reduction. When dnsmasq functions properly, the new auto-calculated limit is set as the current Blockfile size limit.
When a trace is running, FreshTomato will display this (FIX ME!) in the Web interface:
The additional debugging files can also be accessed at the command line by typing: adblock status
To open the last trace file automatically, simply type adblock trace
at a command shell. You will be prompted to select the preferred viewer in which to view the trace files.
Apple iOS devices (paid iCloud service only)
Apple IOS devices have settings that may interfere with adblock operations. The “Limit Address Tracking” option can be disabled on a per WLAN basis, as seen in the image below:
Alternatively, you can disable this globally via the “Private Relay” setting, as seen here:
You might connect your mobile/laptop to different wireless networks at different locations. For this reason, it makes sense to disable Private Relay on a per WLAN basis. It is advised that you disable it wherever FreshTomato provides your Internet connection and Adblock is running.
Remember, these options are only available for paid iCloud customers.