Migrate all text filter parameters to regex matching

[markuslf]

Goal

Replace all simple string/substring/startswith filter parameters with Python regular expression matching across all plugins. This gives admins more flexibility without requiring separate --ignore-pattern and --ignore-regex parameters.

Background

Some plugins offer both --ignore-pattern (substring match) and --ignore-regex (regex match) for the same purpose, or use substring/startswith matching for filters like --ignore, --command, --username, etc. Regular expressions are a superset of simple strings: httpd as a regex still matches "httpd". Admins who need more power can use httpd|nginx, ^web\d+, or (?i)example without needing a separate parameter.

The procs plugin has already been migrated to regex matching for --argument, --command, and --username (documented as a Breaking Change in the current CHANGELOG).

What needs to change

For each affected plugin:

1. Replace substring/startswith matching with re.search() (or re.match() where startswith semantics are needed).
2. Remove duplicate parameters where both --ignore-pattern and --ignore-regex exist for the same purpose. Keep the regex variant.
3. Update the help text to mention "Uses Python regular expressions." and case-sensitivity.
4. Document as a Breaking Change: simple filters like --ignore=httpd still work, but special regex characters (., *, (, [, \) in filter values are now interpreted as regex. Use --ignore='server\.local' to match a literal dot.

Backward compatibility

• Simple strings are valid regexes and match identically: httpd matches "httpd" in both modes.
• Startswith behavior can be expressed as ^httpd.
• Exact match can be expressed as ^httpd$.
• The only breakage is when existing filter values contain regex-special characters that were previously treated as literals (e.g. C:\Windows, server.local, file(1)).

Scope

All plugins that currently use substring, startswith, or in matching for filter parameters. The procs plugin is already done and serves as a reference implementation.

Classification

Breaking Change (next major version).

[markuslf]

Folding in the decisions from #1079, which I am closing as a duplicate of this ticket. The goal there was narrower (unify just --ignore*), but the staging and the guard mechanism apply to the broader filter-migration scope described here.

Reference implementation

• Template: check-plugins/example (skeleton plugin) shows the canonical implementation and help text format. All new plugins derive from this template.
• Real-life example: check-plugins/haproxy-status (from haproxy-status: Ignore specified backends / server names #835, v2026041403 onwards) applies the convention to a non-trivial filter with plugin-specific semantics (match on the combined <proxy>/<svname> identifier).

Breaking-change pitfalls

These must be called out explicitly in the release notes and in the migration blog post:

1. --ignore changes from literal string to regex. Admins who currently write --ignore=my.service as a literal substring will get a regex match where . is "any char" after the upgrade, silently producing false-positive ignores on things like myXservice. Migration: every existing --ignore value must be audited for regex metacharacters (. * + ? ( ) [ ] ^ $ \ |) and, where the admin meant a literal, rewritten with re.escape() equivalents.

2. --ignore-pattern changes from case-insensitive to case-sensitive. Admins who currently write --ignore-pattern=Backend expecting it to match backend need to rewrite it as --ignore='(?i)backend'.

3. The five plugins with hardcoded re.IGNORECASE become case-sensitive. --service=myapp currently matches MyApp; after the change it will not. Affected plugins do not rename their parameters, but they do drop re.IGNORECASE in the same release for consistency.

Convention for the unified --ignore

• a Python regular expression (regex metacharacters are significant)
• case-sensitive by default; admins opt into case-insensitive matching via the inline (?i) flag
• appending (action='append'), so the list UX works both on the command line and in the Icinga Director basket
• documented in the help text with two examples: one case-sensitive, one with (?i)

--ignore-pattern and --ignore-regex are removed.

Staging

One-cycle clean break, no alias shims in code.

Release N+1 (the release before the breaking one):

• --ignore is introduced with the new semantics (Python regex, case-sensitive, appending) in every affected plugin.
• --ignore-pattern and --ignore-regex stay unchanged: the old plugins continue to accept them with their existing semantics for this one release. No alias, no translation layer, no deprecation warning. The sole purpose of N+1 is to give admins a release in which both parameter forms are valid so they can migrate their configs at their own pace.
• Release notes, blog post and CHANGELOG explain what is coming in N+2.

Release N+2 (the breaking release):

• --ignore-pattern and --ignore-regex stay registered in argparse (this is important because parser.parse_known_args() silently eats unknown flags otherwise), but main() actively checks for them and calls lib.base.cu(...) with a clear migration pointer message that causes the check to exit UNKNOWN. This is the only reliable way to tell the admin their config needs updating: Icinga/Nagios surface UNKNOWN immediately in the service view, whereas a stderr deprecation warning would be invisible in the default Icinga layout.
• The old parameter-handling code is removed entirely, so the codebase ends up with one ignore convention, not two overlapping ones.
• The five plugins with hardcoded re.IGNORECASE drop the flag and become case-sensitive.

Scope — affected plugins

--ignore* rename to the new --ignore (regex, case-sensitive, appending)

• by-ssh — --warning-regex / --critical-regex stay as-is (threshold matching, not filtering); help text updated to document case-sensitivity.
• by-winrm — same as by-ssh.
• example — new template for the convention, including the UNKNOWN guard for the old parameters.
• haproxy-status — already conformant after haproxy-status: Ignore specified backends / server names #835, used as real-life reference.
• infomaniak-events — currently --ignore-regex.
• infomaniak-swiss-backup-devices — currently --ignore-customer / --ignore-name / --ignore-tag / --ignore-user (string). Open question: keep four separate parameters or merge into a single --ignore matching on a joined identifier.
• infomaniak-swiss-backup-products — currently --ignore-customer / --ignore-tag (string). Same open question as infomaniak-swiss-backup-devices.
• ipmi-sel — currently --ignore (string), switch to regex.
• journald-query — currently --ignore-regex.
• logfile — currently --ignore-regex. --warning-regex / --critical-regex stay (threshold matching, not filtering).
• mysql-logfile — currently --ignore-regex.
• sensors-temperatures — currently --ignore (string), switch to regex.

Case-sensitivity consistency (no rename, but same sweep)

• disk-usage — drop re.IGNORECASE from the compile_patterns helper.
• grassfish-players — drop re.IGNORECASE from --box-id / --custom-id.
• grassfish-screens — drop re.IGNORECASE from --box-id / --custom-id.
• procs — already migrated for --argument / --command / --username, but still uses re.IGNORECASE; drop it for consistency with the rest.
• service — drop re.IGNORECASE from --service.

Cross-cutting changes

• CONTRIBUTING.md: new section "Filter parameter convention" pointing at example (template) and haproxy-status (real-life reference), explaining regex + case-sensitivity + appending + two-example help text.
• check-plugins/example: the reference implementation, including the UNKNOWN guard for the old flags.
• lib/args.py: redefine --ignore as a regex parameter; remove --ignore-pattern and --ignore-regex after the N+2 break. Two-example format (case-sensitive + (?i)), "Case-sensitive by default" explicit. This needs a linuxfabrik-lib release and a repin in monitoring-plugins/tox.ini and requirements.txt.
• All affected plugins: regenerate the Icinga Director basket (datafield rename), update unit tests, regenerate READMEs via tools/update-readmes, bump __version__, CHANGELOG under "Breaking Changes".
• Migration blog post on linuxfabrik.ch with a checklist of the affected parameters.

Open questions

• Infomaniak parameter shape: do infomaniak-swiss-backup-devices and infomaniak-swiss-backup-products keep their current --ignore-customer / --ignore-name / --ignore-tag / --ignore-user split (with the new regex semantics), or do they collapse into a single --ignore matching on a joined identifier like customer/name/tag/user?