minsec-sync.toml(5)

minsec multiplayer client configuration

minsec-sync.toml(5) · File Formats · 2026-08-24 — generated verbatim from minsec-sync.toml.5. Run man 5 minsec-sync.toml on a server with minsec installed for the same text.

Synopsis

/etc/minsec/sync.toml

Description

This TOML file configures minsec-sync(1). Its existence is the packaged service's multiplayer opt-in switch. When it is absent, minsec-sync run exits successfully without enrollment, network access, key creation, reporting, or firewall changes. Other subcommands treat an absent file as an error.

Every key is optional and has a default. An empty file therefore opts in with all standard behavior enabled. Unknown keys are errors. Unlike the daemon configuration, this file has no drop-in directory and no table sections.

Keys

server = URL: Base URL for enrollment, report, and feed endpoints. The value must begin with http:// or https://. Production deployments should use HTTPS. Trailing slashes are ignored. Default: https://api.minsec.io.
tier = "basic" | "high": Crowd-feed tier. basic uses the basic feed policy; high selects the stricter high-confidence feed. Default: basic.
report = boolean: When true, minsec-sync run submits new automatic local bans. This flag does not disable an explicitly invoked minsec-sync report command. Default: true.
pull = boolean: When true, minsec-sync run fetches and applies crowd feeds. This flag does not disable an explicitly invoked minsec-sync pull command. Default: true.
ipv4 = boolean: Fetch and maintain the IPv4 crowd4 set during a pull. Default: true.
ipv6 = boolean: Fetch and maintain the IPv6 crowd6 set during a pull. Default: true.
state_dir = path: Directory containing the private signing key and client state. It is created when needed. Default: /var/lib/minsec/sync.
events = path: Daemon JSON Lines event log read by the report operation. Only automatic ban records are submitted. Default: /var/lib/minsec/events.jsonl.
nft = path-or-command: nftables executable used to manage crowd sets. The value is executed directly, not through a shell. Default: nft.

Reporting and privacy

Reporting reads complete, newline-terminated automatic ban events beyond the saved inode and byte-offset cursor. It submits the attacker network, event timestamp, filter/category, hit count, and ban lifetime. It does not submit log text, usernames, or local user data. Manual bans are skipped.

IPv4 reports must be /24 or narrower. IPv6 reports must be /48 or narrower; networks narrower than /64, including host /128s, are aggregated to /64. Events older than approximately 23 hours, implausibly future events, malformed networks, and invalid filter names are skipped.

State and firewall

The state directory contains key (a 32-byte Ed25519 signing seed created with mode 0600) and state.json (enrollment, event, sequence, and feed cursors). State updates use a temporary file followed by rename. Protect this directory and preserve it across upgrades.

Pull operations manage only the crowd4 and crowd6 sets in table inet minsec, creating the table and the sets themselves if they do not yet exist. Setting ipv4 or ipv6 to false stops updates for that family but does not flush existing elements. Setting pull to false has the same persistence property.

Example

server = "https://api.minsec.io"
tier = "basic"
report = true
pull = true
ipv4 = true
ipv6 = true
state_dir = "/var/lib/minsec/sync"
events = "/var/lib/minsec/events.jsonl"
nft = "nft"

Files

/etc/minsec/sync.toml: Configuration and opt-in marker.
/usr/share/doc/minsec/sync.toml.example: Packaged example with default values and opt-out guidance.
/var/lib/minsec/sync/key: Default private signing-key path.
/var/lib/minsec/sync/state.json: Default client-state path.
/var/lib/minsec/events.jsonl: Default event-log input.