Banner

Introduction

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.

This documentation is available for TBlock 2.5.0 or later. Information for older versions may however be inaccurate.

Chapters summary

  1. Introduction
  2. Getting started
  3. Filter lists
  4. User rules
  5. Getting information
  6. More operations
  7. Daemon
  8. Filter list converter
  9. Configuration
  10. TBlock filter format
  11. Troubleshooting
  12. FAQ
  13. License

In this chapter

  1. Terminology
  2. How it works

Terminology

IP address

An IP address is a suite of numbers from 0 to 255, seperated by dots (for instance 8.8.8.8). 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

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.

Hosts file

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.

Database

As the name suggests, a database is simply an efficient way to store data.

Filter list

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.

Rule

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.

Filter list format / syntax

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.

Policy

A policy is the instruction a rule gives to the ad-blocker about a specific host. A policy can either be ALLOW, BLOCK or 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.

Daemon

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.

How it works

Filter list repository

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.

Hosts file and localhost

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.

Getting started

In this chapter

  1. Setting up TBlock
  2. Different profiles

Setting up TBlock

After installing TBlock, it is recommended to use the setup wizard that was introduced in TBlock 2.5.0. To do so, run:

tblock --init

Or:

tblock -1

Then, the program will ask you to choose a profile. When you're done, the setup should complete and TBlock will be ready to use. Simple, isn't it?

Different profiles

Profiles are a new feature that exists since TBlock 2.5.0. It allows users to subscribe to a pre-defined set of filter lists to help them configure TBlock in the easiest way possible.

Currently, four different profiles exist:


None

This profile doesn't subscribe to any filter list, it just updates the repository index to make it easier to subscribe to filter lists afterwards.


Light

While some people may consider it sufficient, some ads and trackers won't be blocked with this profile. This profiles subscribes to the following filter lists:


Balanced

This is the default profile for new users, that keeps a good balance between performance and blocking score. It subscribes to the following filter lists:


Aggressive

As the name suggests, this profile prioritizes high blocking score over websites appearance, and it may break some web pages or apps. It subscribes to the following filter lists:


Filter lists

In this chapter

  1. Types of filter lists and permissions
  2. Syncing the filter list repository
  3. Subscribing and updating filter lists
  4. Adding custom filter lists
  5. Unsubscribing from filter lists
  6. Managing filter lists

Types of filter lists and permissions

Official 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.

Custom filter lists

A custom filter list is a filter list that is not available on the repository, that the user had to add manually.

Permissions

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.

Syncing the filter list repository

Initial sync

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):

tblock -Y

You may also use the long operation:

tblock --sync

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.

Force-sync

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:

tblock -Yf

Or the long operation:

tblock --sync --force

Subscribing and updating filter lists

Subscribe

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

Subscribe to many filter lists

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

Subscribe and sync

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

Update

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:

tblock -U

Or the long operation:

tblock --update

Sync and update

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:

tblock -Uy

And the long operation:

tblock --update --with-sync

Sync, update and then subscribe

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

Cleaning the cache

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:

tblock -P

Or:

tblock --purge-cache

Adding custom filter lists

Adding a custom filter list

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'

Adding many filter lists

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'

Specifying the syntax of a custom filter list

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 hosts):

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.

Renaming a custom filter list

You can rename custom filter lists by running:

tblock -N id1-old id1-new id2-old id2-new

Or:

tblock --rename id1-old id1-new id2-old id2-new

Unsubscribing from filter lists

Unsubscribe

If you don't want to subscribe to a filter list anymore, you can easily remove it (in this case easylist):

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 --remove operation.

Unsubscribe and update

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

Managing filter lists permissions

Change the permissions

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 easylist):

tblock -M easylist -p AB

Or the long operation:

tblock --mod easylist --permissions AB

Note: the letter A stands for Allowing rules, B for Blocking rules, and R for 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

In this chapter

  1. What user rules are
  2. Defining user rules
  3. How redirecting rules can be useful
  4. Deleting user rules

What user rules are

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: ALLOW, BLOCK and REDIRECT.

Defining user rules

Allowing a domain

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

Allow wildcards

With TBlock, you can also add wildcards allowing rules. Here, to allow all subdomains of example.org but not example.org itself:

tblock -a *.example.org

Blocking a domain

To block domains, run:

tblock -b example.com example.org

Or the long operation:

tblock --block example.com example.org

Redirecting a domain

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 0.0.0.0):

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

How redirecting rules can be useful

Usually, it is not recommended to use redirecting rules since it may compromise your network traffic. However, they can still be useful for advanced user. Here is an example where redirecting rules are really helpful.

Mapping your devices on a local area network (LAN)

Let's say that you own a Raspberry Pi that you've manually configured to always have the same IP address on your local network. The address is probably something like 192.168.250.67.

However, if you want to access it remotely from your desktop computer, you'll have to enter the IP address every time you want to initiate a ssh connection to it. That's where TBlock can help you. Instead of having to remember the complicated IP address, you can give the domain name that you want to your local device. For instance:

tblock -r rpi.local -i 192.168.250.67

Or:

tblock --redirect rpi.local --ip=192.168.250.67

This will allow you to access your Raspberry Pi under the domain name rpi.local instead of the complicated IP address.

Deleting user rules

Deleting a set of rules

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

Getting information

In this chapter

  1. Listing rules
  2. Querying domains
  3. Listing filter lists
  4. Browsing filter lists

Listing rules

Listing rules

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:

tblock -l

Or the long operation:

tblock --list-rules

Listing user rules only

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:

tblock -le

The long version:

tblock --list-rules --user

Listing non-user rules only

You can also list all rules that are set by filter lists, but exclude user rules from them:

tblock -lt

Or:

tblock --list-rules --standard

Listing rules from specific filter lists only

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 easylist and easyprivacy:

tblock -lm easylist easyprivacy

With the long version:

tblock --list-rules --from-filters easylist easyprivacy

Querying domains

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!

Simply run:

tblock -W example.org

Or:

tblock --which example.org

Listing filter lists

Just as you can list rules, you can also list filter lists.

Listing all 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):

tblock -L

Or:

tblock --list

Listing custom filter lists only

To list only the filter lists that have been manually added by the user, run:

tblock -Lc

Or the long version:

tblock --list --custom

Listing only non-custom filter lists

To list only filter lists that are in the repository index:

tblock -Lw

Or, with the long operation:

tblock --list --on-repo

Listing only subscribed filter lists

You can also list only the filter lists you are subscribing to:

tblock -Lk

Or:

tblock --list --subscribing

Listing only not-subscribed filter lists

You can also list only the filter lists you are not subscribing to:

tblock -Lz

Or:

tblock --list --not-subscribing

Listing non-custom and subscribed filter lists

The options can be combined together. For instance, to list all filter lists that are both available in the repository index and subscribed:

tblock -Lwk

Or:

tblock --list --on-repo --subscribing

Listing non-custom and not-subcribed filter lists

To list only filter lists that are both available in the repository index and not subscribed:

tblock -Lwz

Or:

tblock --list --on-repo --not-subscribing

Getting less information

In automated scripts, you may want to get only the name of the filter lists and not other information about them. That's where the --quiet option becomes useful:

tblock -Lq

Or:

tblock --list --quiet

Browsing filter lists

Searching

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"

Or:

tblock --search "tracking"

Getting less information

In automated scripts, you may want to get only the name of the filter lists and not other information about them. That's where the --quiet option becomes useful:

tblock -Qq "tracking"

Or:

tblock --search --quiet "tracking"

Filtering search results

Just as with the listing operation, the four options --custom, --on-repo, --subscribing and --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"

Or:

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"

Getting information about a specific filter list

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

Or:

tblock --info easylist

More operations

In this chapter

  1. Toggling protection
  2. Getting status information
  3. Show help and version information

Toggling protection

Refreshing rules

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:

tblock -H

The long operation:

tblock --update-hosts

Disabling protection

To disable the protection and restore your default hosts file, run:

tblock -D

With the long operation:

tblock --disable

Enabling protection

If you disabled TBlock, it is easy to enable its protection again:

tblock -E

Or:

tblock --enable

Getting status information

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:

tblock -s

Or the long operation:

tblock --status

Show help and version information

Showing help page

Like all command-line tools, it is possible to display a help page for TBlock:

tblock -h

Or:

tblock --help

Showing version and license information

To show current version and licensing information, run:

tblock -v

Or:

tblock --version

Daemon

In this chapter

  1. Daemon quick overview
  2. Starting the daemon

Daemon quick overview

History & use

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

Multiple instances

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.

Starting the daemon

Starting a single instance

To start an instance of the daemon, simply run (assuming your configuration is located under /etc/tblock.conf):

tblockd -dc /etc/tblock.conf

Or the long alternative:

tblockd --daemon --config=/etc/tblock.conf

Starting another instance

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

Filter list converter

In this chapter

  1. Introduction to the converter
  2. Working with syntax
  3. Using the converter

Introduction to the converter

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.

Working with syntax

Listing available formats

To list available filter list formats/syntax, run:

tblockc -l

Or:

tblockc --list-syntax

Get the format of a file

To detect the format/syntax of a filter list, run (assuming the file you want to check is list.txt):

tblockc -g list.txt

Or the long operation:

tblockc --get-syntax list.txt

Using the converter

Convert a filter list

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 output.txt:

tblockc -C filter.txt -s hosts -o output.txt

Or:

tblockc --convert filter.txt --syntax hosts --output output.txt

Convert and specify the input format

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 filter.txt is adblockplus:

tblockc -C filter.txt -i adblockplus -s hosts -o output.txt

Or:

tblockc --convert filter.txt --input-syntax adblockplus --syntax hosts --output output.txt

Keep comments

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

Or:

tblockc --convert --comments filter.txt --syntax hosts --output output.txt

Configuration

In this chapter

  1. Hosts configuration
  2. Policy configuration
  3. Daemon configuration

Hosts configuration

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.

Change default blocking address

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 [hosts] section of your config:

[hosts]
# Change the way the hosts file is built by TBlock
# NOTE: You need to rebuild your hosts file with `tblock -H` for these changes to apply

# Change the default IPv4 redirecting address for blocked domains
default_ip = 127.0.0.1

Enable IPv6 blocking

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 [hosts] section):

# Allow IPv6 rules and IPv6-based blocking
# WARNING: this will cause your hosts file to be twice as big as before
allow_ipv6 = false

Note: your hosts file will be twice bigger than before if you enable this setting.

Change default IPv6 blocking address

Just as we can change the default IPv4 blocking address, we can also change the IPv6 one, by writing under the [hosts] section:

# Change the default IPv6 redirecting address for blocked domains
# This will only be used if `allow_ipv6` is set to `true`
default_ipv6 = ::1

Policy configuration

Change default filter lists permissions

By default, filter lists are only allowed to set allowing and blocking rules. If you want to change this setting, simply write under the [policy] section in your config (here to allow filter lists to set allowing and blocking rules by default):

[policy]
# Change the default permissions to give to different filter lists
# Use A to give Allowing permission, B to give Blocking permission, and R to give Redirecting permission
# Multiple permissions can be given by concatenating them together (i.e. Allowing + Blocking => AB)
# NOTE: This will not affect filter lists you are already subscribing to

# WARNING: it is highly discouraged to give the Redirecting permission to all filter lists here. 
# Instead, it should rather be made manually by using `tblock -M`
# More information here: https://tblock.codeberg.page/docs/faq.html#why-isnt-it-recommended-to-let-filter-lists-to-set-redirecting-rules-by-default

# Default permissions for filter lists that are available in the repository index
regular = AB

Change default custom filter lists permissions

Since TBlock 2.5.0, it is possible to set different permissions for custom filter lists. To do so, simply write under the [policy] section:

# Default permissions for custom filter lists
custom = 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!

Daemon configuration

Syncing the repository index

By default, the daemon updates both the filter lists and the repository index. If you want to change this setting, write:

[daemon]
# Change the behavior of the daemon
# NOTE: You need to restart the daemon for these changes to apply

# Sync the repository when updating filter lists
sync_repo = false

Changing the update frequency

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:

# How often the filter lists should be updated (value expressed in minutes)
frequency = 480

Note: the time specified here is in minutes. For one hour, we will write 60, for two 120, etc.

Force-update

By default, filter lists are updated normally. If you want to force-update instead, edit the following line under the [daemon] section:

# Force-update filter lists (this is usually not needed)
force = true

Protection against hosts file modification

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 [daemon] section:

# Detect changes made to the hosts file by other programs/others and overwrite them
anti_hijack = false

TBlock filter format

Even though TBlock supports a wide variety of filter list formats, not all formats are 100% compatible with TBlock. For instance, the hosts file format doesn't support allowing rules, and the AdblockPlus format doesn't support redirecting a domain to a given IP address. TBlock filter list format aims to be a simple way to write filter lists that are fully supported by TBlock.

Defining rules

Rules are written under a specific section that tells TBlock what to do with the given hosts. For instance, to allow some domains, they must be written inside the allow section:

[allow]
example.org
example.com

To block domains, they must go inside the block section:

[block]
example.org
example.com

Now, to redirect domains, it's not really complicated either. You just have to include the IP address where the domains should be redirected inside the redirect section definition:

[redirect "127.0.0.2"]
example.org
example.com

Note: you can also specify an IPv6 address inside the section definition.

Adding comments

Like most ad-blockers filter list formats, you can add comments by writting # as the first character of a line:

# This is a comment

Final thoughts

You can, of course, have multiple sections inside a single filter list. However, to keep it as little as possible, it is recommended to only have one section for each policy.

For instance, you should rather do that:

# This is good

[allow]
example.org
example.com

[block]
ns1.example.org
ns2.example.org

[redirect "127.0.0.2"]
ns1.example.com

[redirect "::1"]
ns2.example.com

Than that:

# This is BAD

[allow]
example.org

[block]
ns1.example.org

[allow]
example.com

[block]
ns2.example.org

[redirect "127.0.0.2"]
ns1.example.com

[redirect "::1"]
ns2.example.com

Troubleshooting

Here is a list of the common issues

Domains are not blocked

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.

Error: database is locked

Sometimes, when you run an operation with TBlock, you see an error saying:

Error: database is locked, please wait for other processes to terminate.
If you are sure that the daemon or any other instances are not running, you can delete:
-> /var/lib/tblock/.db_lock

What it means is that there is probably another process that is using TBlock's database at the time. Usually, it's the daemon that is simply updating your filter lists. However, if TBlock recently crashed, it can also be a side-effect of the crash. In that case, and after checking that there are no other processes running, you can delete /var/lib/tblock/.db_lock to fix this issue.

tblock module not found

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

Next, install it again with pipx or any other installation method.

Daemon is unable to start: /usr/bin/tblockd does not exist

Depeding on the installation method you choose, the daemon might not be installed under /usr/bin/tblockd, but rather under /usr/bin/local/bin/tblockd.

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

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).

FAQ

Why do I still see ads after installing and setting up TBlock?

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. You may also want to install uBlock Origin in addition to TBlock.

Is there a graphical interface for TBlock?

Yes! However, it is currently in Open Alpha, which means that there is no stable release right now. If you like, you can help us testing and finding bugs. More information are available on Codeberg.

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"

I think I found an issue. What should I do?

It depends. If the issue you found is a vulnerability, than please follow carefully the instructions written here. Otherwise, have a look at this document that contains useful information for reporting issues.

How to backup my filter lists?

If you want to make a backup of the filter lists you subscribe to, you can simply run the following:

tblock -Lkq > tblock-backup.txt

Then, to restore it:

tblock -Sy $(cat tblock-backup.txt)

License

This documentation

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

TBlock is released under the GNU General Public License, Version 3.0.

Website

TBlock's website is released under the Creative Commons Attribution-ShareAlike 4.0 International License.