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.

While this documentation focuses more on the command-line tool tblock, it also contains installation instructions and some tips for the GUI.

ℹ️ Info
This documentation is available for TBlock 2.7.3 or later. Information for older versions may be inaccurate.

Installation

Chapters in this section

Install on Arch Linux

📝 Note
Since version 2.7.0, the package tblock contains system services for the following init systems: systemd, openrc, runit and dinit.

From the AUR

There is an AUR package available for tblock. You can install it using your favourite AUR helper or by cloning the repository locally.

$ git clone https://aur.archlinux.org/tblock.git tblock
$ cd tblock
$ makepkg -si

A package for tblock-gui is also provided on the AUR.

$ git clone https://aur.archlinux.org/tblock-gui.git tblock-gui
$ cd tblock-gui
$ makepkg -si

🟢 Tip
The package tblock-gui depends on tblock. You should build and install tblock before trying to build tblock-gui.

Using Chaotic-AUR

TBlock is also packaged in the chaotic-aur third-party repository.

$ sudo pacman -S tblock

The GUI is also available in this repository:

$ sudo pacman -S tblock-gui

Install on Debian

📝 Note
Since version 2.7.0, the package tblock contains system services for the following init systems: systemd, openrc, runit and dinit.

Debian packages for both tblock and tblock-gui are provided on the releases pages of the repositories.

Click here to view releases of tblock
Click here to view releases of tblock-gui

After downloading the package(s), we need to install them:

$ sudo apt install ./tblock_*.deb
$ sudo apt install ./tblock-gui_*.deb

🟢 Tip
The package tblock-gui depends on tblock. You should install tblock before tblock-gui.

Install on Fedora

If you are running an Fedora-based distribution, you can enable TBlock's third-party repository to install TBlock and to receive updates in an easy way.

Enable TBlock's COPR

$ sudo dnf copr enable twann/tblock

Install the package(s)

$ sudo dnf install tblock
$ sudo dnf install tblock-gui

Install on macOS

⚠️ Warning
TBlock hasn't yet been officially tested on macOS, so there might be unresolved issues. If you do have TBlock installed on your macOS system, your feedback would be very much appreciated.

ℹ️ Info
The user interface is still work-in-progress for Windows and macOS. TBlock is only available as a command-line tool for both of these platforms. More information is available here.

Installation

If you are using macOS, you can install TBlock with the homebrew package manager.

Enable TBlock's third-party repository

$ brew tap tblock/tap https://codeberg.org/tblock/homebrew-tap

Install the package

$ brew install tblock

Troubleshooting

After installing, you might encounter the following error:

$ sudo tblock --init
sudo: tblock: command not found

Just append the following line to ~/.bashrc or ~/.zshrc, depending on your shell:

alias sudo="PATH=$PATH:$(brew --prefix)/bin:$(brew --prefix)/sbin sudo"

Install on Ubuntu

TBlock has an official PPA available for Ubuntu or Ubuntu-based distributions.

Enable the PPA

$ sudo add-apt-repository ppa:twann4/tblock

Update the repositories

$ sudo apt update

Install the package(s)

$ sudo apt install tblock
$ sudo apt install tblock-gui

Install on Windows

⚠️ Warning
It seems that a huge hosts file can cause Windows to use a lot of CPU and even become unresponsive. It also seems to impact the amount of time required to connect to a network. This issue is typically caused by Windows, not TBlock. We are nevertheless trying to find a way of reducing this problem from our end. More information is available here.

ℹ️ Info
The user interface is still work-in-progress for Windows and macOS. TBlock is only available as a command-line tool for both of these platforms. More information is available here.

With scoop (recommended)

It is possible to install TBlock on Windows using the scoop package manager.

Add TBlock's third-party repository

> scoop bucket add tblock https://codeberg.org/tblock/bucket

Install the package

> scoop install tblock

Download the installer

TBlock also has a graphical installer available for Windows, available on the releases page.

Click here to view releases of tblock

⚠️ Warning
Don't forget to verify the signature of your download if you choose this method.

Build & install from source

If no package is available for your distribution, you can install TBlock and TBlock GUI from source.

Build and install `tblock`

Download and extract the latest stable tarball

$ wget https://codeberg.org/tblock/tblock/archive/x.x.x.tar.gz -O tblock.tar.gz
$ tar -xvf tblock.tar.gz
$ cd tblock

Build the package

$ make

Install the package (systemd)

$ sudo make install install-config

Install the package (OpenRC)

$ sudo make install-openrc install-config

Install the package (runit)

$ sudo make install-runit install-config

Install the package (dinit)

$ sudo make install-dinit install-config

Build and install `tblock-gui`

🟢 Tip
The package tblock-gui depends on tblock. You should build and install tblock before trying to build tblock-gui.

Download and extract the latest stable tarball

$ wget https://codeberg.org/tblock/tblock-gui/archive/x.x.x.tar.gz -O tblock-gui.tar.gz
$ tar -xvf tblock-gui.tar.gz
$ cd tblock-gui

Remove dependency on polkit (expert only)

$ patch -p1 -i data/patch/no-polkit.patch

⚠️ Warning
If you remove the dependency on polkit, you'll need to call tblockg from command-line with root access every time you want to start the GUI.

Build the package

$ make

Install the package

$ sudo make install

Post-installation instructions

Set up the protection

Once TBlock is installed, we need to configure it so that is suits our needs. The first thing to do is to choose the level of protection to use.

If you use the GUI, a wizard will guide us through the process of setting everything up when launched for the first time. If we want to use the command-line, we have to run:

$ sudo tblock -1
$ sudo tblock --init

Next we should see the following prompt on our screen:

> Welcome to TBlock!


:: Please choose the level that suits your needs the best:

[0] None: lets you configure everything yourself
[1] Light: light protection, some ads and trackers won't be blocked
[2] Balanced: perfect solution for regular users
[3] Aggressive: powerful, yet it may break some web pages

Your choice [default=2]:

Once our choice is made, we just have to type the number corresponding to the profile we want to use. Then we need to select which additional components to block. Once this is done, the program will set everything up for you.

Enable automatic updates

One of TBlock's great features is its ability to automatically update blocklists. This can be achieved by using the built-in daemon, tblockd. To enable automatic updates, we need to enable and activate the system service called tblockd.

ℹ️ Info
This feature is still work-in-progress for Windows and macOS. Manual updates are required for both of these platforms. More information is available here.

❓ How to tell if I'm using systemd?
If you have no idea what systemd is, you're probably using it.

With systemd

$ sudo systemctl enable tblockd --now

With OpenRC

$ sudo rc-update add tblockd
$ sudo rc-service tblockd start

Manually

$ sudo tblockd --daemon

Manage protection

Introduction

TBlock is able to block unwanted websites by using something called the hosts file. When connecting to a website (for example example.org), our system queries a DNS server, which then responds by sending the IP address of the website (in that case, 93.184.216.34), allowing us to connect to it. This process is called resolving.

The hosts file is part of every operating system and allows us to resolve a domain name without having to use DNS. When blocking a website, TBlock simply adds an entry to this file, telling it to resolve the domain name with the IP address 0.0.0.0, which is a local address (it is not available through the internet). That way, when an application or a website is trying to connect to a blocked domain, it connects to the local host and can't fetch the requested resource (ad, tracking script, etc.).

Disable protection

Sometimes, we need to disable protection for a few minutes. When we do that, TBlock restores the stock hosts file (the one that we had before using TBlock). In order to do that, we need to execute:

$ sudo tblock -D
$ sudo tblock --disable

Enable protection

If you followed the post-installation steps correctly, the protection should already be enabled by default. However, when we disable the protection, we need to enable it again after. It is possible to do so by running:

$ sudo tblock -E
$ sudo tblock --enable

❌ Failed to enable protection?
It is possible that you get an error similar to this one while trying to enable the protection:
==> Applying built hosts file
[x] Checking checksum
[i] Run tblock -B to build the hosts file
This can easily be fixed by rebuilding the hosts file.

Get status information

At any time, you can check the status (i.e. whether the TBlock is active or not, the number of filter lists subscribtions, the number of rules, whether automatic updates are enabled, etc.) by using this command:

$ tblock -s
$ tblock --status

Build the hosts file

Sometimes we need to completely re-build the hosts file with all the blocked entries. This is usually not needed (because done automatically), but it can be useful to do it manually in some cases (i.e. when errors are encountered while trying to enable the protection). We can build a fresh hosts file with:

$ sudo tblock -B
$ sudo tblock --build

Filter lists

Chapters in this section

Introduction

One of the greatest features of TBlock is its filter list repository. It contains over 100+ popular filter lists that are widely used accross the web. It allows users to subscribe to blocklists easily.

Update the repository

Of course, to have access to the latest filter lists, we need to keep this repository updated. It can be done automatically if you have automatic updates enabled. Otherwise, you have to update manually.

To update the filter list repository, we have to execute:

$ sudo tblock -Y
$ sudo tblock --sync

With the GUI, the repository can be updated by clicking on the Manage filter lists button in the main window, and then clicking on the button labeled Sync index.

Explore the repository

List all filter lists available in the repository

$ tblock -Lw
$ tblock --list --on-repo

Find matches across the filter lists available in the repository

$ tblock -Qw "query"
$ tblock --search --on-repo "query"

Getting more information about a specific filter list

$ tblock -I some-filter-list
$ tblock --info some-filter-list

Manage filter lists

Filter lists are text files that contain a list of domain and the information of what to do with these domains. While most filter lists contain blocking rules, some of them also contain allowing rules.

Domains that are blocked are mapped to 0.0.0.0 in the hosts file.
Domains that are allowed cannot be blocked by any other filter list.

To use filter lists, we need to subscribe to them. When we subscribe to a list, TBlock will apply its rules to the hosts file.

If you followed the post-installation instructions, you should already be subscribing to a bunch of filter lists. You can list the filter lists you are subscribing to by executing:

$ tblock -Lk
$ tblock --list --subscribing

When subscribing to a filter list that is available in the filter list repository, we need to indicate its ID (or name). A common example is to subscribe to tblock-base, which is the base filter list for effective ads and trackers blocking:

$ tblock -S tblock-base
$ tblock --subscribe tblock-base

We can also subscribe to several filter lists at the same time (here easylist, easyprivacy and stevenblack-hosts):

$ tblock -S easylist easyprivacy stevenblack-hosts
$ tblock --subscribe easylist easyprivacy stevenblack-hosts

Unsubscribe

If we are subscribing to a filter list that we no longer need, we can easily remove it from our subscriptions. Here, with tblock-base:

$ tblock -R tblock-base
$ tblock --remove tblock-base

Update

ℹ️ Info
If we have automatic updates enabled, we usually don't need to update filter lists manually.

It is common that some filter lists contain some false positives, or that new ads/tracking servers are created. That's why it is very important to regularly update your filter lists. It is really simple to do, but it can take some time, depending on how many filter lists you are subscribing to.

$ tblock -U
$ tblock --update

It is also possible to update both the filter list repository and the filter lists subscriptions in one operation:

$ tblock -Uy
$ tblock --update --with-sync

Custom filter lists

Even though there is a large variety of filter lists in the filter list repository, it is possible that we want to subscribe to a filter list that isn't included in it.

⛔ DANGER
If you decide to add a local file, it file must be owned by root. Since tblock 2.7.3, it is no longer possible to add files that aren't owned by root. By convention, it is best to store local filter lists under /usr/share/tblock/.

To subscribe to a custom filter list, we need to assign an ID (or name) to it. To ensure that no filter list has the same ID, it is recommended to use one that begins with custom-.

Here, we'll add a custom filter list from an URL and name it custom-example:

$ tblock -C custom-example https://example.org/list.txt
$ tblock --add-custom custom-example https://example.org/list.txt

Here, we'll add a custom filter list from a local file and name it custom-local:

$ tblock -C custom-local /usr/share/tblock/list.txt
$ tblock --add-custom custom-example /usr/share/tblock/list.txt

⚠️ Warning
If you later delete the local file, TBlock will no longer be able to update this filter list. If you move this file to a new location, you'll need to remove the filter list and to add another one with the new access path, since it is currently not possible to change the source of a filter list.

TBlock supports most filter lists formats. You can list all supported formats with:

$ tblockc -l
$ tblockc --list-syntax

When subscribing to a custom filter list, TBlock will try to detect its format. However, this method has the following disadvantages:

It slows down the process of subscribing.
It can incorrectly detect the format, causing all rules to be skipped.

If we know the format of the filter list that we are adding, it is usually better to specify it:

$ tblock -C custom-example https://example.org/list.txt -x adblockplus
$ tblock --add-custom custom-example https://example.org/list.txt --custom-syntax=adblockplus

Custom filter lists can be removed in the same way other filter lists are removed. Note that a custom filter list will also have its ID (or name) deleted when it is removed. It means that if we remove custom-example and want to subscribe to it again, we'll have to execute again the steps written in the chapter about subscribing to custom filter lists.

We can list all custom filter lists with this command:

$ tblock -Lc
$ tblock --list --custom

To remove a custom filter list:

$ tblock -R custom-example
$ tblock --remove custom-example

Sometimes, we need to rename a custom filter list (for example if it conflicts with a filter list included in the repository).

We can easily to that:

$ tblock -N custom-example custom-example-new
$ tblock --rename custom-example custom-example-new

User rules

Another great feature available with TBlock is the ability to define user rules. These rules are almost identical to rules that are found in filter lists. The only difference is that they have a higher priority than other rules.

A user rule will overwrite any existing rule.

Allow a domain

Allowing a domain means preventing it from being blocked by filter lists. A domain can be allowed using:

$ tblock -a example.org
$ tblock --allow example.org

Block a domain

Blocking a domain means adding an entry to the hosts file that will cause it to resolve as 0.0.0.0. When a domain is blocked, it is impossible to connect to it. To block a domain:

$ tblock -b example.org
$ tblock --block example.org

Redirect a domain

⛔ DANGER
Proceed with great caution when redirecting a domain, since it has the potential to compromise your network traffic. You should only use this feature if you know exactly what you are doing.

It is also possible to add a custom entry to the hosts file that will cause a domain to resolve as an IP address different than the one it should normally. We can do this using this command (here we want example.org to resolve as 127.0.0.1):

$ tblock -r example.org -i 127.0.0.1
$ tblock --redirect example.org --ip=127.0.0.1

Delete a user rule

📝 Note
It is only possible to delete user rules using this operation.

When a user rule is no longer needed, it can be deleted with:

$ tblock -d example.org
$ tblock --delete-rule example.org

It means that filter lists will be able to define rules for example.org again.

List user rules

We can list all user rules with:

$ tblock -le
$ tblock --list-rules --user

Convert filter lists

TBlock comes with a built-in filter list converter. If you followed this documentation step-by-step, we have already used this utility once, when listing all the available filter list formats.

This tool is particularly helpful if you maintain filter lists and want them to be compatible with different ad blockers.

Convert a filter list (autodetect input format)

$ tblockc -C input.txt -o output.txt -s output_format
$ tblockc --convert input.txt --output=output.txt --syntax=output_format

Convert a filter list (specify input format)

$ tblockc -C input.txt -i input_format -o output.txt -s output_format
$ tblockc --convert input.txt --input-syntax=input_format --output=output.txt --syntax=output_format

Convert a filter list (with comments)

$ tblockc -C input.txt -o output.txt -s output_format -c
$ tblockc --convert input.txt --output=output.txt --syntax=output_format --comments

Convert a filter list (strip blank lines)

$ tblockc -C input.txt -o output.txt -s output_format -z
$ tblockc --convert input.txt --output=output.txt --syntax=output_format --optimize

$ tblockc -g list.txt
$ tblockc --get-syntax list.txt

List available formats

$ tblockc -l
$ tblockc --list-syntax

Common issues

TBlock was flagged as malware on Windows

Windows or other antivirus software often flag TBlock as a malware. They're wrong. TBlock is open source, so you can check by yourself if you don't believe us. The two main reasons Windows and antivirus don't like TBlock is that:

The binaries are not signed (because it costs money and we currently do not own enough for this). However, if you verified the signature of your download, this should not be a problem.
TBlock needs to modify a system file (the hosts file) in order to work. Some malwares have used the hosts file in the past for phishing purposes, which explains the stress caused to Windows and antivirus software.

If your antivirus flagged TBlock as malware, you'll have to add an exception for it in order to use it.

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 we try to run an operation with TBlock, we may 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 automatic updates that are being made. 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, we can delete /var/lib/tblock/.db_lock to fix this issue.

TBlock Documentation