Configuration

Config is stored at /etc/picosnitch/config.toml and is created with sensible defaults on first run. Restart picosnitch for changes to take effect:

sudo systemctl restart picosnitch

config.toml

The block below is included verbatim from the project README.

[database]
enabled = true                # write connection logs to /var/lib/picosnitch/picosnitch.db (SQLite)
retention_days = 30           # how many days to keep connection logs in the local database
                              # (the remote database is append-only; see [database.remote])
write_limit_seconds = 10      # minimum time between connection log entries
                              # increasing it groups traffic into larger time windows, decreasing
                              # disk writes, time precision, and database size
text_log = false              # also write a CSV connection log to /var/log/picosnitch/conn.log

[database.remote]             # optional: also write connection logs to an external SQL server
                              # used for off-system / tamper-evident logs (see Logging below).
                              # mirrors the local SQLite schema (connections, executables,
                              # domains, addresses).
                              # set `client` to "mariadb", "psycopg", "psycopg2", or "pymysql";
                              # add the rest of the connection parameters as key/value pairs and
                              # optionally `connections_table` to override the default; this lets
                              # multiple hosts share one server with a `connections` table each
                              # while reusing the shared `executables`/`domains`/`addresses`

[data]
owner = "root"                # owner for files in /etc/picosnitch, /var/lib/picosnitch,
group = "root"                # /var/log/picosnitch, and /var/cache/picosnitch
mode = "0644"                 # mode applied to those files (directories add execute bits)

[log]
addresses = true              # log remote addresses for each connection
commands = true               # log command line args for each executable
ports = true                  # log local and remote ports for each connection
ignore_ports = []             # list of ints; matching connections are omitted from the log
ignore_domains = []           # list of strings in reverse-dns notation (matches all subdomains)
ignore_ips = []               # list of IPs/CIDRs (e.g. "192.168.0.0/16")
ignore_sha256 = []            # list of executable sha256 hashes
                              # the process name, executable, and hash are still recorded

[desktop]
user = ""                     # username to send notifications to; defaults to $SUDO_UID
notifications = true          # show desktop notifications via notify-send (libnotify)
geoip_lookup = true           # annotate remote addresses with a country code in the TUI/webui
                              # uses the DB-IP Country Lite CSV cached under /var/cache/picosnitch

[monitoring]
every_exe = false             # check every running executable, not just ones that open sockets
                              # these are treated as "connections" with a port of -1
                              # experimental; expect occasional errors for short-lived processes
                              # if you only want process logs (no hashes), see execsnoop / forkstat
perf_ring_buffer_pages = 256  # power of two number of pages per BPF perf buffer
                              # only change this if you are seeing missed-event errors
# rlimit_nofile = 65536       # optional int; raises RLIMIT_NOFILE for the daemon
                              # picosnitch caches one file descriptor per (device, inode);
                              # set this if you see "Too many open files" errors
# st_dev_mask = 0             # optional int; masks the device number reported for opened fds
                              # auto-detected at startup; only set this to override the default
                              # for filesystems that reuse inodes across subvolumes (e.g. btrfs)

[virustotal]
api_key = ""                  # VirusTotal API key, leave blank to disable
file_upload = false           # upload the executable when its hash isn't already known
                              # leave false to only submit hashes
request_limit_seconds = 15    # seconds between requests (free-tier quota)

Environment variables

Variable	Used by	Purpose
PICOSNITCH_HOST	picosnitch webui	Override the web UI bind address (default 127.0.0.1).
PICOSNITCH_PORT	picosnitch webui	Override the web UI port (default 5100).
SUDO_UID	daemon	Used as the default [desktop].user for notifications.

Remote logging

[database.remote] ships every connection to a MariaDB, MySQL, or PostgreSQL server in addition to the local SQLite log. Install the optional drivers with the [sql] extra:

sudo pipx install 'picosnitch[sql]' --global

Picosnitch only ever issues INSERT against the remote (no retention, no garbage collection), so it is intended as an off-system copy of your logs. Grant the daemon's database user INSERT only to prevent an adversary on the monitored host from deleting picosnitch's off-system logs.

The remote schema mirrors the local SQLite layout (see schema). Only the connections table name is configurable (via connections_table), which lets multiple hosts share one server with their own connections_<host> table each while reusing the shared executables / domains / addresses reference tables.

Example, ship logs to a MariaDB server with a per-host table:

[database.remote]
client = "mariadb"
host = "logs.example.internal"
port = 3306
user = "picosnitch"
password = "..."
database = "picosnitch"
connections_table = "connections_workstation1"