Blocker is a GNOME Shell Extension that allows users to easily toggle system-wide content blocking. It uses a program named hBlock to change your computer's DNS settings, so it does not to connect to domains that are known for serving adverts, trackers, and malware. This strategy of content blocking has its limitations, and you can read more about them here.

Contents

• Getting started
  • Installation
  • Usage
• FAQ
  • How does it work?
  • What are its limitations?
  • How do I know it's working?
  • Can I customize the denylist?
  • Where should I report problems?
• Contributing
  • Translating
  • Programming
    • Understanding the codebase
    • Building and installing from source
• Attribution
  • Code
  • Assets
  • Build system
  • Documentation
• Gratitude
• License

Getting started

Installation

First, you need to install hBlock. Follow the instructions here to install it.

Important

Blocker depends on hBlock and won't work if you haven't installed it on your computer.

After installing hBlock, you can install Blocker itself through the GNOME Extensions website.

Usage

Caution

Blocker replaces your system's /etc/hosts file. Consider making a backup of it!

Click the Quick Settings toggle and input your user's password to activate Blocker (it will take a while to download all its denylists). Once Blocker is active, it will display a system indicator of a shield. To turn it off, simply click the toggle and input your password again.

FAQ

How does it work?

This GNOME Shell extension is just a convenient frontend for hBlock, which does all the heavy lifting. Here's what happens when you toggle Blocker:

First, Blocker uses pkexec (the program that prompts you for your password) to gain super user privilege, which is required to run hBlock. Then, if you enabled Blocker, it enables hBlock by running hblock. If you disabled Blocker, it disables hBlock by running hblock -S none -D none. I couldn't resist a flowchart...

flowchart TD

A["Blocker toggled"] --> B["Gain privilege with pkexec"]
B -- If Blocker is disabled, enable it --> C["Execute  'hblock -S none -D none'"]
B -- If Blocker is enabled, disable it --> D["Execute  'hblock'"]

Loading

What are its limitations?

Blocker is powered by hBlock, so its limitations are Blocker's limitations.

The content blocking strategy used by hBlock is DNS blocking. That means that any connections that do not depend on name resolution cannot be blocked using this approach, such as accessing an IP address directly. Additionally, certain applications may set their own DNS settings (e.g. Firefox, when it uses DNS over HTTPS) instead of adhering to the system's configuration. Finally, your DNS settings may be affected if you are using a VPN, which tipically route your DNS queries to its own resolvers.

How do I know it's working?

Visit https://hblock.molinero.dev, it tells you whether hBlock is active or not. This is does that by checking if connections to https://hblock-check.molinero.dev are blocked, which is the case for hBlock's default configuration.

Can I customize the denylist?

Blocker does not provide, nor plans to provide, that kind of customization. However, you can do that if you use hBlock directly in the terminal, using -A, -D, and -S flags. Run hblock --help for more details.

Where should I report problems?

For false positives (i.e. a legimate site is being mistakenly blocked), report in hBlock's issue tracker. For everything else, report in Blocker's issue tracker.

Contributing

Translating

Blocker can be translated using Weblate. Here's our progress so far:

Programming

Understanding the codebase

Blocker's code is documented using JSDoc. You can read the documentation directly in the source code, or head to the Developer Documentation page.

Building and installing from source

If you wish to make changes to the Blocker codebase, you will likely want to build it and install it from source. Blocker's source code on hosted on GitHub. Your first step is cloning Blocker's repository with:

git clone https://github.com/pesader/gnome-shell-extension-blocker.git

You can then build and install the extension with:

cd gnome-shell-extension-blocker
make build && make install

You can run a nested session of GNOME Shell to test the extension out with:

make run

Before submitting a pull request, make sure you install and run the linter with:

make lint-install # install the linter
make lint         # run the linter

You can also have the linter attempt to fix the errors it found with:

make lint-fix

Attribution

Code

• Assign a custom icon to a Quick Settings toggle: based on the codebase from Caffeine.
• Run shell commands asynchronously: heavily inspired by the GJS docs and GSConnect.
• Send customized notifications: reused from Gravatar and Picture of the day extensions.

Assets

• Blocker's logo: derived from the shield-safe-symbolic icon, by the GNOME Project.
• Blocker's banner: inspired by the banners at Flathub's home page
• Extension logo in banner: is the symbolic icon from Matthew Jakeman's Extension Manager
• EGO banner: modified from Just Perfection's work.

Build system

• Makefile: inspired by the Makefile of Caffeine
• GitHub Actions workflow for linting: again, inspired Caffeine

Documentation

• How to install hBlock: copied and pasted staright from hBlock's README and docs

Gratitude

This project would not exist if it weren't for hBlock, so I thank its maintainer and all its contributors. I'm also grateful to everyone in the GNOME Extensions matrix room, who kindly answered the many questions that came up while I was writing this program.

License

This project is licensed under the terms of the GPLv3.