minsec-filter.toml(5)

minsec log-source and matching-filter definition format

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

Synopsis

/etc/minsec/filters/name.toml

Description

A filter definition selects log sources and describes lines that count as failures for minsec(1). Definitions are TOML files with top-level keys. Unknown keys are errors.

Custom files are discovered by filename stem. A custom filters/name.toml completely replaces the embedded filter named name; filter definitions are not merged. The [filters.name] table in minsec.toml(5) can then enable the filter and replace its files, journal selector, ports, or retry policy.

Keys

name = string: Filter name recorded in status and event records. This key is required. For predictable lookup and reporting, it should match the filename stem and contain only lowercase letters, digits, ., _, and -.
description = string: Short description displayed by minsec filters. Default: empty.
files = [path-pattern, ...]: Log files to follow when this filter does not use the journal. Shell-style glob patterns are accepted. Existing files are normally opened at end of file; missing paths are watched for creation. Default: empty.
journal = { units = [...], identifiers = [...], comm = [...] }: Journal selectors. units match _SYSTEMD_UNIT, identifiers match SYSLOG_IDENTIFIER, and comm matches _COMM. Every array entry is an alternative: a record matching any configured entry is routed to the filter. All arrays default to empty.
prefilter = [literal, ...]: Case-sensitive literal substrings used as a cheap check before regular expression matching. A file line proceeds if any literal is present. Prefilters are skipped for journal records, whose metadata already routes them and whose message omits a traditional syslog prefix. Default: empty, which disables the check.
patterns = [regex, ...]: Required list of regular expressions describing failure lines. Each expression must contain an address token such as <HOST>. Patterns are tried as one ordered alternation; the first matching pattern with a parseable address supplies the result and its zero-based pattern number.
ignore = [regex, ...]: Regular expressions for lines that must not count even when a main pattern matches. The same token expansion applies, so <HOST> may be used here as well. Default: empty.
ports = [integer, ...]: Service-port metadata carried into effective policy and inspection output. Default: empty. The current nft backend drops banned sources on all ports, so this list does not restrict its rules.

Pattern language

Patterns use the Rust regex syntax. They are case-sensitive unless the expression changes flags and are searched anywhere in the line unless explicitly anchored with ^ or $. Look-around and backreferences are not supported.

TOML literal strings in single quotes are convenient for patterns because a backslash is preserved without TOML escaping:

patterns = ['failed from <HOST> port \d+']

The following fail2ban-style tokens are expanded before compilation:

<HOST>, <ADDR>, <IP>: Capture an IPv4 or IPv6 address.
<IP4>: Capture an IPv4 address only.
<IP6>: Capture an IPv6 address only.
<F-NAME>...</F-NAME>: Create a named capture; the name is lowercased. <F-USER>...</F-USER> is returned as the optional username by the matcher. Other named captures may be used for expression structure but are not otherwise consumed by the current engine. The Perl-style classes \d, \D, \s, \S, \w, and \W are rewritten to ASCII-only classes. Captured addresses are parsed after matching, so syntactically matching but invalid addresses such as an IPv4 octet over 255 are rejected.

Source behavior

For each enabled filter, minsec chooses the journal when all of these are true: global journal use is enabled, journal support is available, and the definition has at least one journal selector. Otherwise minsec follows the filter's files. It does not consume both source types for the same filter.

Journal unit metadata is trusted directly. Identifier and command selectors are honored only for records whose sender UID is a system account (UID 0 through 999), preventing unprivileged use of logger(1) from spoofing service messages.

Built-in filters

The binary embeds these definitions:

apache-auth    dovecot       nginx-auth     postfix
postfix-sasl   proftpd       roundcube      sshd
webmin         wordpress

Use minsec filters for descriptions and the installed binary's authoritative list.

Example

name = "myapp"
description = "My application login failures"
files = ["/var/log/myapp.log"]
journal = { identifiers = ["myapp"] }
prefilter = ["login failed"]
ports = [8443]
patterns = [
  'login failed for <F-USER>\S+</F-USER> from <HOST>',
]
ignore = [
  'health-check account',
]

Enable and test it with:

minsec enable myapp
minsec check --all
minsec test myapp /var/log/myapp.log

Files

/etc/minsec/filters/*.toml: Custom definitions and built-in replacements.
/etc/minsec/minsec.toml: Policy and enablement configuration.
/etc/minsec/conf.d/*.toml: Policy and enablement drop-ins.