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:
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 /var/lib/picosnitch, /var/log/picosnitch,
group = "root" # and /var/cache/picosnitch
mode = "0644" # mode applied to those files (directories add execute bits)
# config.toml stays root:root 0600 because it can contain credentials
[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 pages for the exec and dns perf buffers
# network traffic is aggregated in-kernel, it does not use these
# only change this if you are seeing missed-event errors
conn_map_max_entries = 65536 # size of the in-kernel per-connection aggregation map
# only raise this if you see near-capacity eviction warnings
# 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 localhost). |
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:
Picosnitch never updates or deletes remote rows (no retention, no
garbage collection), so it is intended as an
off-system copy of your logs.
The remote writer runs in an unprivileged subprocess ([desktop].user
if set, otherwise nobody), so the database driver is never imported
by a root process.
Grant the daemon's database user only CREATE (first run), INSERT,
and SELECT (id lookups) so an adversary on the monitored host cannot
rewrite or delete picosnitch's off-system logs.
The remote schema mirrors the local SQLite layout
(see schema), except the executables table dedups on an
added key_hash column rather than the raw text columns. 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.
If an existing remote executables table lacks key_hash, picosnitch
detects the outdated schema and does not alter or drop it; back up and
recreate the remote tables to enable remote logging.
Example, ship logs to a MariaDB server with a per-host table: