Advanced Configuration

The user interface deliberately exposes only the most common settings. Everything more technical is configured through plain text files in TOML format. Changes take effect after restarting the littlesnitch daemon:

sudo systemctl restart littlesnitch

The override mechanism

The factory configuration lives in:

/var/lib/littlesnitch/config/

Do not edit these files directly. They are replaced whenever the daemon restarts and your changes would be lost. Instead:

Copy the file you want to change into the override directory:

sudo cp /var/lib/littlesnitch/config/web_ui.toml \
       /var/lib/littlesnitch/override/config/

Edit the copy in the override directory.
Restart the daemon.

Little Snitch always prefers a file found in the override directory over the factory version.

Every factory configuration file contains its own documentation as comments, describing each option, its allowed values, and its default. That in-file documentation is authoritative for the version you are running. This manual describes only what each file is for.

The configuration files

web_ui.toml

Network address and port of the web interface, TLS, and authentication. This file matters whenever more than one user can reach the interface. See Securing the Web Interface for guidance. The port can also be set to values in the privileged range below 1024.

main.toml

Among other things, this file sets the default action: what happens when a connection matches no rule at all. The factory default is to allow such connections. You can flip this to deny, turning Little Snitch into an allowlist based filter.

Be careful with a deny default. It is easy to lock yourself out of network access, or even out of the computer if you administer it remotely. Before switching, make sure you have allow rules for everything essential, including name resolution and the connection you use to reach the machine.

executables.toml

A set of heuristics for grouping applications sensibly. This file drives two mechanisms described in Watching Your Connections and, in depth, in Advanced Topics:

Executable path normalization: patterns that strip version numbers and other volatile parts from executable paths, so that different releases of an application do not appear as separate entries and rules survive updates.
Process attribution: the lists of shells and app managers that determine which parent process is shown in "parent via process" entries.

Typical reasons to override this file:

An application appears as a new entry after every update. Add a normalization pattern for its path.
You see "system-helper via your-app" but want your-app to be the top level entry without the helper being displayed. Add the helper to the app manager section.

The pattern syntax and the exact section names are documented in the file itself. If you write a pattern or configuration that might be useful for others, please consider dropping us a note.

software_update.toml

Controls the software update check. See Software Updates.

Replacing entire components

Both the eBPF kernel program and the web UI can be swapped out for your own builds. The source code for both is available on GitHub under the GPLv2. As with configuration files, Little Snitch prefers the versions found in the override directory.