System behaviour

• log_level - This is just to set the logging level of glocker. “info” is usually sufficient for personal use. “debug” if you’re doing feature development.
• user - This tells Glocker who you are. Glocker runs as root so it needs to be told this explicitly. Several things below use it so make sure you set it correctly.

Blocking

Glocker essentially does two things. One - It blocks certain domains, keywords and applications. Two - It gathers statistics about usage so that behaviour patterns can be identified and acted upon.

Let’s talk about blocking first.

list: 
  - name: "twitter.com"
  

list: 
  - name: "twitter.com"
    unblockable: true
    

unblocking:
  reasons: ["work", "research", "emergency", "entertainment", "education", "relax"]
  log_file: "/var/log/glocker/unblocks.log"
  temp_unblock_time: 20        # minutes a domain stays unblocked
  max_per_day: 3               # max unblocks per calendar day (0 = unlimited)

- name: "twitter.com"
  unblockable: false
  block_windows:
    # Blocked during work hours on weekdays
    - start: "09:00"
      end: "17:00"
      days: ["Mon", "Tue", "Wed", "Thu", "Fri"]
    # Also blocked in the evening (to encourage sleep)
    - start: "21:00"
      end: "2:00"
      days: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
      

list:
     - !include conf.d/domains-social-media.yaml
     

list:
  - name: "brave"
  

- name: "brave"
  kill_windows:
    - start: "20:00"
      end: "05:00"
      days: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]

john ALL=(ALL) NOPASSWD: /usr/bin/apt, /usr/bin/dmesg, /sbin/service docker *, /sbin/service networking *

john ALL=(ALL) NOPASSWD:ALL

Uninstallation

Software should be uninstallable and glocker is no different. However, it makes changes in many parts of the system so it’s hard to uninstall manually. The right way to do it is to run glocker -uninstall {reason} as root. The valid reasons are in lifecycle.reasons and lifecycle.log_file has the name of the file which holds the information on uninstallations.

However, even in the sudo window, if you just uninstall it, it’s not very useful so we have something called mindful_uninstall. This is something to battle what Nir Eyal calls a liminal moment in his book. Imagine you’re tired or stressed and want a quick break. Now, the comfort of the habit that you want to break becomes appealing and you have to make a decision - Do you fight it and stay away or do you give in, uninstall glocker and indulge? Well, if you turn on mindful_uninstall, it will force you type a sentence with a slow deliberate cadence that will give you the time to let the urge die out. Remember, any resistance to the easiness of the habit means that it won’t form or amplify.

The enabled key is all you need — the timings ship with sensible built-in defaults. If you want to tune it, there are a few knobs. interval_ms is how fast the characters of the sentence are revealed, one at a time; deadline_ms is how long you have after a character appears to type it before it counts as a miss; grace_ms is the pause before the first character shows up; and lines is how many sentences you have to get through. If you type a wrong key, fall behind the cadence, or the terminal loses focus, it resets with a fresh sentence. recency_hours and recent_lines handle repeats: if you’ve already uninstalled within the last recency_hours, you have to type recent_lines sentences instead of lines. You can also set sentences to your own pool instead of the built-in one.

Lifecycle events

Uninstalls will be recorded in the file specified in lifecycle.log_file. lifecycle.reasons is a list of strings which you can provide as reasons for the -uninstall command. This is recorded so that you know why you’re uninstalling for analysis after the fact.

Violation tracking

Anytime you visit a blocked site or a page with blocked content or launch a forbidden program, glocker records it as a violation. If you have more than violation_tracking.max_violations within violation_tracking.time_window_minutes, it will execute violation_tracking.command. glocklock is a helper program that can lock the screen for a given amount of time like a screen saver but which you cannot unlock. You have to wait for the time specified in violation_tracking.lock_duration. Glocklock will pick up violation_tracking.background to display on the screen when it locks (this is X11 only. On Gnome/Wayland, you simply get a lock screen). The violation_tracking.command is what will run when you cross the violation threshold. My own is

sudo -u john DISPLAY=:1 /usr/local/bin/glocklock

glocker runs as root so just running glocklock won’t work.

Usage monitor

Glocker can also track what window (Application/title) you’re currently focused in. It will then save this information to a file. These can then be tagged (e.g. you could say that all time spent inside VSCode is work and all time spent inside discord is entertainment). Glocker’s dashboards will give you insights about where you spend your time during the day. Over a long period, this will be useful to understand what applications or domains to block at what times.

This is controlled by the usage_monitor stanza. You turn it on the usual way and it logs information to log_file every interval_seconds seconds. The display and xauthority are necessary parameters for the X window system to gather the statistics. On GNOME/Wayland it works a little differently. display and xauthority are ignored. Instead, glocker talks to your session over D-Bus. It also needs a small GNOME Shell extension to read the focused window, which the installer sets up for you. glocker automatically detects X11 or Wayland and uses whichever keys apply. There are a few systems (KDE Plasma, etc.) which we don’t support yet.

The log_file will contain usage statistics. Each entry in this file contains a timestamp and then a list of windows. Each window entry has keys indicating whether it’s active (ie. focused), the class, the instance and the title. class is usually the application binary name. These things are available to run filters on. We will discuss that later.

I was a long time user of a really nice program called Arbtt. Glocker’s system is modelled on Arbtt.

We will discuss how to use this later.

Heartbeat

The heartbeat stanza is best left enabled. It is used by the glockdoc program to check whether glocker is running at regular intervals. This information is used when we create statistics about usage. The interval_minutes is how frequently this runs and timeout_seconds is how long it waits for a response from glocker to decide whether it’s up or not. The defaults are reasonable here.

Panic

We’ll skip to the last stanza - panic mode. This is something that’s important. If you enable it, then doing a glocker -panic will make glocker run panic.command and will hold it for panic.duration. Typically, you set the command to something like pm-suspend and the delay to something like 30. This forces you off the computer for that much time. When you trigger -panic, glocker records a deadline (now plus panic.duration). It will then check every second and, if the machine is awake before the deadline has passed, runs panic.command again. Suspending the machine doesn’t stop the countdown and waking up early just gets you suspended again until the deadline is genuinely in the past.

People typically bind this to a key so that you can hit it when you’re losing control over your habits and the system becomes unusable for a while so that you can recover your senses.

Sync

Glocker records statistics like violations, usage information etc. into plain text files. A companion (web) application called glockpeek is available which can be given this information. Enabling the sync feature will enable this. The glockpeek_url is the location of the glockpeek instance. If you’re using the hosted version of glocker, you will need an ingest bearer token for authentication. This is specified in token. You will also need to set encrypt to true so that the data will be encrypted before going to glockpeek. The sync frequency is specified in interval_seconds.

glockpeek has a separate config file in conf/glockpeek.yaml which we’ll briefly talk about here

Accountability

This is where you configure your accountability buddy (or buddies). He or she will receive emails when you violate one of your rules. Their emails can be specified in buddy_emails. A summary of activity will be sent every digest_every_hours - usually set to 24 (daily) or 168 (weekly). digest_when_quiet will suppress the message when there’s no activity. alerts.went_dark will enable an alert if glocker gets uninstalled. Setting high_violations to a non-zero number will send emails if you’ve had more than these many violations.

Changing restrictions

1. -add-keyword - Will add a new word to the url and content keyword lists for blocking. So if you do glocker -add-keyword linux, then your browser will block all sites that mention linux.
2. -block - Will add the supplied host to the blocklist
3. -block-app - Will add the supplied program to the blocklist
4. -lock - Will immediately lock sudo (even if you’re in an available window).
5. -panic - We discussed this above. Will prevent you from using your machine for a while.
6. -unblock - We discussed this above. This allows you to temporarily unblock a domain.
7. -extend - Allows temporary usage of a program outside of it’s actual allowed window. Details are discussed above.

Restrictions made using the above commands don’t survive a reinstall. If you want to make them permanent, you need to edit the config file and restart glocker.

Lifecycle

1. -install - Install glocker and helper programs. Will also start it. The provided Makefile runs this when you request installation
2. -uninstall - Removes glocker and reverts the system. You can also provide a -note which can be added to give more information on why you’re uninstalling it for your records (E.g. “client presentation in the evening. Requires tools otherwise restricted”)
3. -purge - When you uninstall, The glockdoc program will still log and tell the system that glocker has been uninstalled. IF you want to get of it completely, use the -purge option along with -uninstall. ### Informational
4. -status - Shows the current status (blocked sites, violations, extension grants etc.). This is dynamic and changes. This is the default if you just type glocker and hit enter when the glocker daemon is actually running.
5. -info - Shows configuration information which is static.
6. -version - Shows what version of Glocker is running
7. -check - Runs an audit of your system to see if it is configured to allow bypasses. It needs to be run as root. It reports two things: the capabilities glocker needs to run (systemd, visudo, an immutable filesystem, a watchdog scheduler), and the bypass and recovery routes on the machine — extra sudo grants, wheel/sudo group membership, an unlocked root account, root SSH login, autologin. It also runs automatically at the end of install, so that you get this information upfront.

Cloud sync

1. -connect - This is used to connect with the glocker cloud platform so that your usage information can be saved for you to look at later. We’ll discuss this below.
2. -force - With -connect: replace an existing key even if it differs from your vault
3. -resync is used to send all the data locally again to the server. This is not something that most users will need. It was added to facilitate pushing data during development. You can ignore it.

History

First, you get a History Calendar with statistics per calendar day - clean days, violations (more you have, the darker the day). The day gets hatch filled to indicate the time that the system was unmanaged (glocker uninstalled). The legend gives you these for quick reference.

If you click on a day, you’ll get the Day Detail. This gives you at what time you make the violation and which hours were not managed. Violations are listed too. Some times, there might be false positives (e.g. you’re visiting site to help you with techniques to kick your gambling habit but glocker blocks them for the “gambling” tag). You can ignore these by hitting the [x]. You can “unignore” them by removing from the “Ignored violations” list below.

The Vulnerability map gives you a hour x day view of when you’re most vulnerable. You get insights like you mostly mess up on weekend nights etc.

Unblocks gives you a list of the times you used the -unblock or -extend commands.

Ignored violations shows the list of false positives. You can later whitelist these domains or something else to make it reflect your behaviour.

Usage

This is used to give you insights on what applications you’re using, when you’re using them and why. The usage tracker feature is very useful to understand what’s sucking up your time and how to adjust glocker to prevent you from doing that.

The first thing we need to understand is the tagging system. Glocker maintains the Program (e.g. firefox-esr) and Title (e.g. Google Docs) in its usage tracking tables. Glocker allows you to tag these entries by matching either of these fields using regular expressions.

For example, you could say something like

Tag all firefox-esr windows where the title matches YouTube with the tag entertainment).

Then, you can figure out how much time you spend on “entertainment” and make config changes to optimize how you work.

Tags themselves have some configurability too. Tags are of the form namespace:name. The namespace part lets you tag the same time along several independent axes. An entry gets at most one tag per namespace, and the Usage tab shows a separate breakdown for each namespace. So the same hours can be sliced by category, by project, by tool, and so on.

Glocker is the built-in namespace (entertainment, social, games, dev, work, …). You can add your own. Here are a few examples.

Any tag in any namespace can be flagged a distraction, which is used by the the work-hours which we’ll describe later.

Because matching is on the Program or the Title, the same app splits by what it’s doing. For example, consider a firefox-esr window titled YouTube. This can be classified on activity by assigning it a Glocker:entertainment tag. You can also classify it on a focus axis calling by tagging it Focus:shallow. Similarly, firefox-esr with a Google Docs title can be tagged using Glocker:work and Focus:deep. Now, you can find out independently how many hours you spend on deep work and how many hours you spend on entertainment by looking at the breakdowns on separate axes.

Tags

You can create and edit the available tags in the Tags tab which gives you the Tab registry. The Glocker namespace is fixed if you’re using the hosted setup and you get a few pre configured rules so that you can get value immediately.

You can create new namespaces using the + Add namespace button and inside a namespace, you can use the + Add tag button to add a tag. Clicking on the tag colour allows you to configure the colour.