Welcome to TBlock documentation!
This is the place where you can learn how to use TBlock and how it works. If this is your first time using TBlock, we recommend you to read this documentation from the beginning, but you can also select the chapter you are interested into.
Please note that this documentation is available only for TBlock version 2.2.0 or later. The information written here may not be compatible with previous versions.
- Filter lists
- User rules
- Getting information
- More operations
- Filter list converter
An IP address is a suite of numbers from
255, seperated by dots (for instance
22.214.171.124). Every time you connect to the internet, you ISP (Internet Service Provider) assigns you a public IP address. This address is unique, and it can be used to access content on the device that has this address. In that case, the device is called a server.
DNS stands for Domain Name System. It is a service that is used by computers to connect to websites. When a computer tries to connect to
example.org, it sends a request to a DNS server, which sends a response containing the IP address of
example.org. The connection from the computer to example.org is now possible.
The hosts file is a file that is present on all operating systems. It acts like a DNS, but has a higher priority than the DNS. It can be used to redirect hosts (such as
example.org) to custom IP addresses.
As the name suggests, a database is simply an efficient way to store data.
A filter list is a text file, containing a list of domains (for instance
example.com), that can be used by an ad-blocker to block all domains that are on it. Depending on the format, it is possible to also whitelist some domains inside a filter list. Whithout filter lists, ad blocking wouldn't be possible.
A rule is a way to tell an ad-blocker what to do about a specific domain. In fact, a filter list is a set of rules, that tells the ad-blocker which domains to block and which not to block.
The format (or syntax) of a filter list is simply a way to write rules inside the list so that the ad-blocker understands what to do with the specified hosts. Different ad-blockers use different formats. For instance, Adblock Plus uses an advanced syntax that allows to block hosts under certain conditions. This is not possible with others, such as AdAway or pi-hole, or TBlock. However, TBlock supports the most popular filter lists. It means the users should not have to worry about that.
A policy is the instruction a rule gives to the ad-blocker about a specific host. A policy can either be
REDIRECT. If the policy is
ALLOW, then the host is whitelisted. If the policy is
BLOCK, the host is blocked, and if it is
REDIRECT, the domain is redirected to the ip address specified in the rule.
In computing, a daemon is a program that runs in the background, performing invisible but yet important tasks for the daily user. Without daemons, it wouldn't be possible to have a graphical desktop.
As we already said, filter lists are essential for an efficient protection against advertising and tracking. However, finding these filter lists may be difficult for a new user. That's why TBlock has an official filter list repository, allowing the user to use them just with one simple operation. Almost all filter lists available on the repository are also mirrored by the team behind TBlock, to improve decentralization in case a server is down.
To block domains, TBlock uses the hosts file. With it, it redirects all blocked domains to the local IP address,
0.0.0.0. That way, when a program or a web page tries to connect to a blocked domain, it connects to the local address instead. It means that the requested tracking script or advert is not available and thus not loaded.
- Types of filter lists and permissions
- Syncing the filter list repository
- Subscribing and updating filter lists
- Adding custom filter lists
- Unsubscribing from filter lists
- Managing filter lists
Official filter lists are filter lists that can be found on the filter list repository. Some details (such as syntax, license and homepage) about them are also provided.
A custom filter list is a filter list that is not available on the repository, that the user had to add manually.
Permissions are a way to control which rule policies a specific filter list is allowed to use. By default, filter lists are only allowed to set blocking rules.
The filter list repository is what makes TBlock unique. With a simple command, users can subscribe to the most popular and powerful lists available. Before being able to subscribe to these official filter lists, however, it is important to sync the repository, so that TBlock knows what these lists are and where to download them. To do so, you only have to run this as root (or with administration permissions):
You may also use the long operation:
Since new filter lists are regularly added to the repository, it is important to keep it up-to-date, by syncing the repository as frequently as possible.
Note: the daemon allows you to automate the process of syncing the repository.
By default, if your local version of the repository is up-to-date, nothing will be done. However, you may want to force-sync, to sync it even if it is up-to-date. To do so, simply run:
Or the long operation:
tblock --sync --force
To subscribe to a filter list (in this case
easylist), simply run:
tblock -S easylist
You may use the long operation as well:
tblock --subscribe easylist
Of course, you can subscribe as many filter lists as you want at the same time, by appending them at the end of the command (also works with long operation):
tblock -S easylist easyprivacy tblock-base
Since it is recommended to sync the filter list repository as frequently as possible, you may want to sync the repository while subscribing to filter lists in only one operation:
tblock -Sy easylist
Or the long operation:
tblock --subscribe --with-sync easylist
Once you've subscribed to the filter lists you want to, it is important to keep them up-to-date as well (for instance if a list contains a false-positive host). To do so, simply run:
Or the long operation:
Since it is important to keep both repository and filter lists up-to-date, you may want to sync/update them at the same time:
And the long operation:
tblock --update --with-sync
You can also sync the repository, update all filter lists and then subscribe to new lists with a single operation:
tblock -Syu easyprivacy
Or the long version (really long this time):
tblock --subscribe --with-sync --with-update easyprivacy
When TBlock fetches a filter lists, it automatically stores it in cache. However, you may want to delete cached filter lists to free up some space on your device. To do so, run:
To add a custom filter list, you have to give it a name that doesn't already exist on the repository. You also need to specify the link/local path of the plain text filter list. To do so:
tblock -C example-org 'https://example.org/list.txt'
You can also use the long operation:
tblock --add-custom example-org 'https://example.org/list.txt'
You can also subscribe to many custom filter lists at the same time, by appending them at the end of the command (always the name first, and then the link/path of the list):
tblock -C \ example-org 'https://example.org/list.txt' \ local-list '/home/user/blocklist.txt'
Thanks to TBlock's advanced technology, you usually shouldn't have to worry about the syntax of the custom filter list you are adding. However, with huge lists, you can save some time by specifying manually the syntax (in this example
tblock -C example-org 'https://example.org/list.txt' -x hosts
There is also a long operation available:
tblock --add-custom example-org 'https://example.org/list.txt' --custom-syntax hosts
Note: if you specify the syntax, TBlock will use it for all the custom filter lists that are given in the same command. It means that you can't use this option if you are trying to add two lists that have different formats.
You can rename custom filter lists by running:
tblock -N id1-old id1-new id2-old id2-new
tblock --rename id1-old id1-new id2-old id2-new
If you don't want to subscribe to a filter list anymore, you can easily remove it (in this case
tblock -R easylist
You may want to use the long operation:
tblock --remove easylist
Note: just as subscribing, you can remove several filter lists at the same time by passing them after the
Once a filter list is removed, so are its rules. However, if another filter list blocks the same domains than the removed list, you need to update your lists for the rules to be restored. You can do so by running:
tblock -Ru easylist
Or the long operation:
tblock --remove --with-update easylist
By default, filter lists are only allowed to define blocking rules. However, you can grant them the permission to define allowing or redirecting rules.
To grant a filter list allowing and blocking permissions (in this example
tblock -M easylist -p AB
Or the long operation:
tblock --mod easylist --permissions AB
Note: the letter
Astands for Allowing rules,
Bfor Blocking rules, and
Rfor Redirecting rules.
To grant a filter list allowing and redirecting permission only:
tblock -M easylist -p AR
Note: redirecting rules can compromise your network traffic and lead to MITM attacks. Be sure to fully trust the filter lists you grant the "redirecting" permission.
To restore the default permissions (blocking only):
tblock -M easylist -p B
User rules are rules that are set directly by the user. They have a greater priority than regular rules, which means they overwrite rules that are set by filter lists. They can be useful for allowing domains that are blocked without having to remove a whole filter list.
Exactly like regular rules, they can have three different policies:
To allow domains (prevent it from being blocked/redirected by filter lists), run:
tblock -a example.com example.org
Or the long operation:
tblock --allow example.com example.org
With TBlock, you can also add wildcards allowing rules. Here, to allow all subdomains of
example.org but not
tblock -a *.example.org
To block domains, run:
tblock -b example.com example.org
Or the long operation:
tblock --block example.com example.org
Redirecting domains should not be done, unless you know exactly what you are doing. If so, then you can redirect the domains you want to a specific IP address (in this case
tblock -r example.com example.org -i 0.0.0.0
Or the long operation:
tblock --redirect example.com example.org --ip 0.0.0.0
To delete existing user rules, use the operation:
tblock -d example.org example.com
Or its long alternative:
tblock --delete-rule example.org example.com
Sometimes, it can be useful to know whether a domain is blocked, allowed, redirected, or if the rule doesn't exist. You may also want to know which rules a specific filter list contains. You can list all rules present in TBlock's database:
Or the long operation:
It is important to see which rules are user rules and which ones aren't, because user rules have a higher priority than other rules. To list all user rules:
The long version:
tblock --list-rules --user
You can also list all rules that are set by filter lists, but exclude user rules from them:
tblock --list-rules --standard
You can also list the rules from a specific filter list only (or several). Here we'll assume that you want to list the rules from
tblock -lm easylist easyprivacy
With the long version:
tblock --list-rules --from-filters easylist easyprivacy
Listing user rules is useful, but what if we want to simply check if a rule exists?
A solution would be to run:
tblock -l | grep "example.org"
However, with this solution, we can't see which filter list owns the rule. But it's alright, because TBlock 2.2.0 introduced a new option for this purpose!
tblock -W example.org
tblock --which example.org
Just as you can list rules, you can also list filter lists.
When you list filter lists, all filter lists are shown by default (both the ones available on the repository and the ones you added manually):
To list only the filter lists that have been manually added by the user, run:
Or the long version:
tblock --list --custom
To list only filter lists that are in the repository index:
Or, with the long operation:
tblock --list --on-repo
You can also list only the filter lists you are subscribing to:
tblock --list --subscribing
You can also list only the filter lists you are not subscribing to:
tblock --list --not-subscribing
The options can be combined together. For instance, to list all filter lists that are both available in the repository index and subscribed:
tblock --list --on-repo --subscribing
To list only filter lists that are both available in the repository index and not subscribed:
tblock --list --on-repo --not-subscribing
You can search a specific word or tag accross filter lists, just as you would do with a search engine.
To search for filter lists that block tracking, for instance, we would run:
tblock -Q "tracking"
tblock --search "tracking"
Just as with the listing operation, the four options
--not-subscribing can be added to the search operation to filter the results.
For instance, if we wanted to search for blocklists that block ads and that we are not subscribing to, we would run:
tblock -Qz "ads"
tblock --search --not-subscribing "ads"
If we want to search for filter lists that include
easylist, that are available in the repository index and that we are subscribing to, we need to run:
tblock -Qwk "easylist"
tblock --search --on-repo --subscribing "easylist"
We can also display information about a specific filter list (such as name, whether we are subscribing to it, tags, source, license, rules count, etc.). Assuming we want to get information about
easylist, we have to run:
tblock -I easylist
tblock --info easylist
If your hosts file was modified, you may want TBlock to refresh its rules (update the hosts file without updating your filter lists). To do so:
The long operation:
To disable the protection and restore your default hosts file, run:
With the long operation:
If you disabled TBlock, it is easy to enable its protection again:
If we want to see if TBlock is active or not, the total rules count, or the number of active filter lists, we can do so by running:
Or the long operation:
Like all command-line tools, it is possible to display a help page for TBlock:
To show current version and licensing information, run:
The daemon was introduced in TBlock version 2.0.0. It is a simple utility that runs in background and that can perform the following tasks:
- Update the filter lists (and sync the repository index) at a regular time interval
- Protect the hosts file against being edited by another program or user
By default, only one instance of the daemon can run at the same time. When an instance of the daemon starts, it creates a PID file, and, if the file already exists then it fails to start. The PID file is removed when the instance of the running daemon stops.
To start an instance of the daemon, simply run (assuming your configuration is located under
tblockd -dc /etc/tblock.conf
Or the long alternative:
tblockd --daemon --config=/etc/tblock.conf
If an instance of the daemon is already running, you are not able to start another instance by default. However, you can do that by telling the new instance to ignore the PID file:
tblockd -dnc /etc/tblock.conf
Or with the long version:
tblockd --daemon --no-pid --config=/etc/tblock.conf
The converter is yet another great feature provided by TBlock. It allows users to easily convert filter lists from a syntax to another one. This can be useful for distributing home-made lists, while assuring their compatiblity with different ad-blockers.
To list available filter list formats/syntax, run:
To detect the format/syntax of a filter list, run (assuming the file you want to check is
tblockc -g list.txt
Or the long operation:
tblockc --get-syntax list.txt
The converter allows you to convert a filter list into another format. Here, we'll convert
filter.txt into the
hosts format, and write the output to
tblockc -C filter.txt -s hosts -o output.txt
tblockc --convert filter.txt --syntax hosts --output output.txt
By default, the converter detects the format of the input list. However, since this operation can be slow with huge blocklist, you can specify it manually.
Here, the format of the
tblockc -C filter.txt -i adblockplus -s hosts -o output.txt
tblockc --convert filter.txt --input-syntax adblockplus --syntax hosts --output output.txt
By default, the converter only converts compatible rules. However, you can choose to also convert comments:
tblockc -Cc filter.txt -s hosts -o output.txt
tblockc --convert --comments filter.txt --syntax hosts --output output.txt
TBlock's configuration file is located under
/etc/tblock.conf on GNU/Linux and under
"%ALLUSERSPROFILE%\TBlock\conf.ini on Windows. It can be used to modify TBlock's behavior.
By default, TBlock redirects blocked domains to
0.0.0.0. However, if you want to change this value, for instance to
127.0.0.1, you just need to write this line under the
[default] section of your config:
[default] # Let's change the default blocking address default_ip = 127.0.0.1
By default, TBlock redirects blocked domains to the local IPv4 address only. If you want to enable redirecting to IPv6, write the following line (still under the
# Let's allow IPv6 redirecting rules and IPv6 blocking allow_ipv6 = false
Note: your hosts file will be twice bigger than before if you enable this setting.
Just as we can change the default IPv4 blocking address, we can also change the IPv6 one, by writing under the
default_ipv6 = ::1
By default, filter lists are only allowed to set blocking rules. If you want to change this setting, simply write under the
[default] section in your config (here to allow filter lists to set allowing and blocking rules by default):
# Default filter permissions (A for Allow, B for Block, R for Redirect) # Multiple permissions are supported. default_permissions = AB
Note: it is discouraged to set the redirecting permissions by default, since this can possibly lead to security flaws on your device. Only give this permissions to filter lists you fully trust!
By default, the daemon updates both the filter lists and the repository index. If you want to change this setting, write:
[daemon] # Do not sync the repository index when updating filter lists sync_repo = false
By default, filter lists are updated every 4 hours. You can change this value (for instance to 8 hours) by writing under the
[daemon] section of your config:
# Update filter lists every x minutes frequency = 480
Note: the time specified here is in minutes. For one hour, we will write
60, for two
By default, filter lists are updated normally. If you want to force-update instead, edit the following line under the
# Force-update filter lists force = true
By default, the daemon prevents other programs or users from editing your hosts file while running. This improves the security of your device, but you may want to disable it. To do so, simply write the following line under the
anti_hijack = false
Here is a list of the common issues
The daemon does keeps updating every 240 minutes, even though I specified a lower value in the configuration file
This bug is usually caused by the fact that you specified a value that's too low for the daemon in your configuration file. The lowest value supported by the daemon is 60 minutes. If the value you specified is lower than 60 minutes, it will automatically change it to 240 minutes (which is the default value).
When running TBlock as root, you can possibly get an error message such as:
importlib.metadata.PackageNotFoundError: No package metadata was found for tblock
ModuleNotFoundError: No module named 'tblock'
This is usually caused by the fact that you installed TBlock using
pip and its
--user option. To solve that, follow the steps below.
First, remove the Python package:
pip uninstall --user tblock
Depeding on the installation method you choose, the daemon might not be installed under
/usr/bin/tblockd, but rather under
To fix that, you simply have to create a symbolic link under
/usr/bin/tblockd, pointing to the real executable:
ln -s /usr/local/bin/tblockd /usr/bin/tblockd
Since TBlock uses the hosts file, it gives you a systemwide protection. However, it can't block specific scripts like browser addons do. It means that you may still see some sneaky ads. The only thing you can do is to subscribe to more and to bigger filter lists.
If you use Tor Browser or if your browser uses DNS-over-HTTPS, it will interfere with TBlock. Since TBlock acts like a DNS server, it can't be used if the browser proxies the DNS requests. You'll have to disable your browser's settings, or, in the case of Tor Browser, simply don't care.
Simply because that means that they would by able to redirect any domain to any server they want. This could cause compromise all your network traffic.
For example, a filter list could redirect your mail server to a phishing website, and you wouldn't even notice. This is why it is recommended to allow only trusted filter lists to set redirecting rules.
You can check at any time if there are any redirecting rules set by running:
tblock -l | grep "REDIRECT"
It depends. If the issue you found is a vulnerability, than please report it to us via an encrypted email. Otherwise, have a look at this document that contains useful information for reporting issues.
If you want to make a backup of the filter lists you subscribe to, you can simply run the following:
tblock -Lk > tblock-backup.txt
Then, to restore it:
tblock -Sy $(cat tblock-backup.txt)
This documentation is published under the GNU Free Documentation License, Version 1.3:
Copyright (C) 2022 Twann. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
TBlock is released under the GNU General Public License, Version 3.0.
TBlock's website is released under the Creative Commons Attribution-ShareAlike 4.0 International License.