minsec(1)

minimalist log-driven intrusion prevention daemon and control utility

minsec(1) · User Commands · 2026-08-24 — generated verbatim from minsec.1. Run man 1 minsec on a server with minsec installed for the same text.

Synopsis

minsec [options] command [command-options]

Description

minsec watches selected log files or the systemd journal for authentication failures and other abuse. It tracks failures by filter and source network, then asks a configured backend to ban sources that reach the retry threshold within the configured time window.

The default nft backend maintains the inet minsec nftables table. Ban expiration is implemented by nftables set timeouts, so active bans survive daemon restarts and expire without daemon intervention.

The same binary provides the foreground daemon, offline configuration and filter inspection commands, and commands that communicate with the running daemon through a Unix-domain control socket.

Global options

-c directory, --config-dir directory: Use directory as the configuration directory instead of /etc/minsec. The directory contains minsec.toml, conf.d/, and filters/.
--json: Request machine-readable JSON from commands that support it. For test without --quiet, one JSON object is written per matching line; with --quiet, a single summary object with line, match, and per-address counts is written instead. events always emits its stored JSON Lines records.
-h, --help: Show help and exit.
-V, --version: Show the program version and exit.

daemon [--backend backend] [--replay]

Run the daemon in the foreground. The backend override may be nft, null, or exec. It changes the loaded configuration only for this process. The null backend records what the engine would do without changing the firewall.

File sources normally start at end of file. --replay starts existing file sources at the beginning. Journal input continues from the journal follower's normal starting point.

check [--all]

Load and validate the merged configuration and compile filters. By default only enabled filters are compiled. --all also compiles every discovered built-in and custom filter, including disabled custom filters. This command is offline and is suitable for checking changes before a restart.

inspect

Inspect the merged configuration, discovered files and filters, and effective per-filter policy. Human-readable output is a short summary; use --json for the complete, versioned inspection document. This command is offline.

test filter [file] [--quiet]

Compile filter and run it against file. If file is omitted or is -, read standard input. By default each match shows the extracted address, pattern number, and input line, followed by a summary on standard error. -q or --quiet suppresses individual matches and prints per-address totals instead.

This command tests textual matching only. It does not apply retry thresholds, allow lists, IPv6 prefix aggregation, escalation, or firewall actions.

status

Ask the running daemon for its version, backend, uptime, counters, and effective policy and source type for every enabled filter.

list

Ask the running daemon for active local bans and their remaining lifetimes. The nft backend is asked for kernel truth. The exec backend cannot enumerate bans, so the daemon answers from its own in-memory mirror, which only covers bans issued since it started.

ban net [--ttl duration]

Manually ban an IP address or CIDR network. Host addresses are normalized to a /32 or /128 and CIDRs are truncated to their network address. Without --ttl, the configured default bantime is used. The daemon refuses networks that overlap its effective allow list. Manual bans are not used as multiplayer reports.

unban net

Remove an address or network from the local ban backend and forget its current per-filter retry state.

filters

List embedded filters and custom filters/*.toml definitions. An asterisk marks an enabled filter.

enable name

Validate that the filter exists and set enabled = true in conf.d/name.toml. Existing settings in that drop-in are preserved. Restart the service to apply the change; the daemon does not live-reload configuration.

disable name

Set enabled = false in conf.d/name.toml. The same restart requirement as enable applies.

events [-n count]

Print the last count records from the event log, oldest first. The default is 50. The log is events.jsonl in the state directory together with the single rotated generation events.jsonl.1, which the daemon creates when the current file passes 8 MiB; both are read and older records are gone. Records are emitted as JSON Lines and include daemon start/stop, automatic and manual ban, and unban events.

Duration syntax

Durations may be bare seconds or one or more integer/unit pairs. Units are s, m, h, d, and w. Examples are 30, 10m, 1h30m, and 2d.

Firewall backends

nft

Owns only table inet minsec. It creates local ban sets ban4/ban6, allow sets allow4/allow6, crowd-feed sets crowd4/crowd6, and input and forward base chains at priority -10. Allow rules precede drop rules. The daemon requires permission to execute nft(8) and administer nftables, normally CAP_NET_ADMIN.

null

Performs no firewall changes and is useful for evaluation and filter tuning.

exec

Runs the shell command configured by defaults.exec_command with one of these argument sequences:

setup
ban net ttl-seconds
unban net

The configured string is evaluated by /bin/sh -c, and the arguments above are appended as positional parameters instead of being substituted into the text. The child process is equivalent to:

/bin/sh -c 'exec_command "$@"' minsec setup

A command may therefore be a script or program path, or a shell fragment that reads $1, $2, and $3. It must be trusted configuration. This backend does not enumerate active bans or install an allow set; the daemon still refuses to issue a ban for a network overlapping its allow list.

Control socket

Online commands use the socket configured by paths.socket. The daemon creates it with mode 0660 owned by the user and group it runs as, so online commands must run as root or as a member of that group. The protocol is newline-delimited JSON: one request and one response per line. Supported request command names include ping, status, list, filters, ban, and unban. Use the CLI or minsec inspect --json instead of depending on human-readable output.

Environment

MINSEC_LOG: Logging filter for daemon mode. The default is info. Values use the tracing-subscriber environment-filter syntax; for example, minsec=debug enables debug logging for minsec targets.

Files

/etc/minsec/minsec.toml: Main daemon configuration.
/etc/minsec/conf.d/*.toml: Lexically ordered configuration drop-ins.
/etc/minsec/filters/*.toml: Custom filters and overrides for embedded filters.
/run/minsec/minsec.sock: Default control socket.
/var/lib/minsec/events.jsonl: Persistent event log.
/var/lib/minsec/events.jsonl.1: Previous generation of the event log.
/usr/lib/systemd/system/minsec.service: Packaged systemd service unit (/lib/systemd/system/minsec.service in the Debian package).

Exit status

Returns 0 when the requested operation succeeds and 1 for configuration, filter, control-socket, backend, or other operational errors.

Examples

Validate all known filters before restarting the daemon:

minsec check --all
systemctl restart minsec

Test the sshd filter without changing the firewall:

minsec test sshd /var/log/secure

Observe the full effective configuration:

minsec --json inspect

Create a one-day manual ban:

minsec ban 198.51.100.7 --ttl 1d