minsec-sync(1)
report local minsec bans and maintain the crowd blocklist
Synopsis
minsec-sync [options] command
Description
minsec-sync is the opt-in multiplayer client for minsec(1). It is a short-lived program intended to run periodically from a systemd timer. It enrolls the host, reports new automatic bans from the daemon event log, and loads a selected crowd blocklist into the dedicated nftables crowd4 and crowd6 sets.
The resident daemon contains no HTTP or TLS client. Network activity and private signing-key management are isolated in this helper. Creating /etc/minsec/sync.toml is the opt-in switch used by the packaged timer.
Options
- -c file, --config file
Read configuration from file instead of /etc/minsec/sync.toml.
- --dry-run
Print nftables scripts instead of passing them to nft(8). This option only suppresses nftables changes. It does not suppress HTTP requests, enrollment, reporting, key creation, or state-file updates; a successful pull also advances its saved feed cursor.
- -h, --help
Show help and exit.
- -V, --version
Show the program version and exit.
enroll
Create an Ed25519 signing key if necessary, solve the server's enrollment proof-of-work challenge, and save the assigned host ID. If this state is already present, print the existing host ID and return.
If the local host ID was lost but the server already knows the signing key, the key is moved to key.old and enrollment is retried once with a new key.
report
Read new automatic ban events from the configured minsec event log and submit signed report batches. The saved file cursor advances only after all batches succeed. Manual bans are never reported. Old or malformed events and networks broader than the reporting limits are skipped.
Reports contain the attacker network, event time, filter name, hit count, ban lifetime, and repeat-offender depth. The filter name identifies the detection rule that matched, never the traffic that matched it; the server maps it to an abuse category. They do not contain log lines, usernames, or local user information. IPv6 host addresses and prefixes narrower than /64 are aggregated to /64.
pull
Fetch enabled IPv4 and IPv6 feeds for the configured tier, using saved ETags and snapshot cursors when possible. Full feeds atomically replace the corresponding set; delta feeds add and remove individual entries. If a delta cannot be applied, a full feed is fetched and installed.
Crowd set elements are given a 24 hour kernel timeout. A full replace re-adds every element and so restarts that clock, and pull forces one, unconditionally, whenever the last full replace for a family is more than 12 hours old. Under normal operation the list is therefore refreshed long before anything expires; if pulls stop reaching the server, the crowd sets drain within a day instead of enforcing their last snapshot until the machine reboots. Local bans in ban4 and ban6 are unaffected.
This command manages only crowd4 and crowd6 in table inet minsec. It creates that table and those two sets idempotently, so a pull works before the daemon has been restarted onto a crowd-aware version; the sets are simply unreferenced until then. The daemon owns the chains and rules that reference those sets.
run
Perform the timer workflow. Enroll first if necessary, then report and/or pull according to configuration. If the configuration file does not exist, exit successfully without output or side effects. This absent-file behavior is specific to run; the other commands report an error.
status
Print the configured server, public key, enrollment host ID, next report sequence number, event-log cursor, the age of the last pull that reached the server, and saved feed state including how long ago each family was last replaced in full. A private key is generated if one does not already exist.
Operation
The packaged minsec-sync.timer runs minsec-sync run approximately once an hour: two minutes after boot, then an hour after each run, with up to five minutes of randomized delay. The free feed is refreshed on that cadence and is not intended to be real-time; a site that wants faster propagation can shorten OnUnitActiveSec with a drop-in, subject to the min_report_interval advertised at enrollment. The service normally runs as the same minsec user as the daemon so it can read the event log and persistent state. Pulling requires permission to execute nft(8) and administer nftables, normally CAP_NET_ADMIN. Enrollment, reporting, and pulling require HTTPS access to the configured server and a usable CA trust store.
Disabling reporting or pulling does not remove existing crowd set entries. To opt out completely, remove the sync configuration, stop or disable the timer, and flush both crowd sets if immediate removal is desired:
nft flush set inet minsec crowd4
nft flush set inet minsec crowd6
Files
- /etc/minsec/sync.toml
Multiplayer configuration and opt-in marker.
- /var/lib/minsec/events.jsonl
Default source of automatic ban events.
- /var/lib/minsec/sync/key
Ed25519 private signing seed, created with mode 0600.
- /var/lib/minsec/sync/key.old
Previous key retained after automatic recovery from lost enrollment state.
- /var/lib/minsec/sync/state.json
Enrollment ID, report sequence and event cursor, and feed cursors.
- /usr/share/doc/minsec/sync.toml.example
Packaged example configuration.
- /usr/lib/systemd/system/minsec-sync.service
Packaged one-shot service (/lib/systemd/system in the Debian package).
- /usr/lib/systemd/system/minsec-sync.timer
Packaged periodic timer.
Exit status
Returns 0 when the requested operation succeeds. run also returns 0 when its configuration file is absent. Configuration, state, network, server, feed, and nftables failures return 1.
Examples
Opt in using the package example and test feed application visibly:
install -m 0644 /usr/share/doc/minsec/sync.toml.example /etc/minsec/sync.toml
minsec-sync enroll
minsec-sync --dry-run pull
systemctl enable --now minsec-sync.timer
Inspect client state:
minsec-sync status
See also
minsec(1), minsec-sync.toml(5), minsec.toml(5), nft(8), systemd.timer(5)