linuxfabrik-lib 6.0.0__tar.gz → 7.0.0__tar.gz

{linuxfabrik_lib-6.0.0/linuxfabrik_lib.egg-info → linuxfabrik_lib-7.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linuxfabrik-lib
-Version: 6.0.0
+Version: 7.0.0
 Summary: Python libraries used in various Linuxfabrik projects, including the 'Linuxfabrik Monitoring Plugins' project.
 Author-email: "Linuxfabrik GmbH, Zurich, Switzerland" <info@linuxfabrik.ch>
 License: This is free and unencumbered software released into the public domain.
@@ -79,7 +79,6 @@ Dynamic: license-file
 <div align="center">
 
 ![GitHub Stars](https://img.shields.io/github/stars/linuxfabrik/lib)
-[![Star History Chart](https://api.star-history.com/svg?repos=Linuxfabrik/lib&type=Date)](https://star-history.com/#Linuxfabrik/lib&Date)
 ![License](https://img.shields.io/github/license/linuxfabrik/lib)
 ![Version](https://img.shields.io/github/v/release/linuxfabrik/lib?sort=semver)
 [![PyPI](https://img.shields.io/pypi/v/linuxfabrik-lib)](https://pypi.org/project/linuxfabrik-lib/)
@@ -137,13 +136,14 @@ These libraries are built with a clear set of priorities:
 
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
-| **args.py** | Extends `argparse` with custom input types for monitoring thresholds and a registry of reusable `--help` texts. | `csv()`, `float_or_none()`, `help()`, `int_or_none()`, `number_unit_method()` |
+| **args.py** | Extends `argparse` with custom input types for monitoring thresholds, a registry of reusable `--help` texts, and reading a secret from a file instead of the command line. | `csv()`, `float_or_none()`, `help()`, `int_or_none()`, `load_secret()`, `number_unit_method()` |
 | **base.py** | The central library for plugin development. Provides state evaluation, threshold comparison, performance data formatting, ASCII table output, and the `coe()` error-handling pattern. | `coe()`, `cu()`, `get_perfdata()`, `get_state()`, `get_table()`, `get_worst()`, `oao()`, `state2str()` |
 | **globals.py** | Defines the four Nagios/Icinga plugin states: `STATE_OK` (0), `STATE_WARN` (1), `STATE_CRIT` (2), `STATE_UNKNOWN` (3). | -- |
 | **human.py** | Converts raw numbers, byte sizes, bit rates, and durations to human-readable representations and back. Supports binary/SI prefixes and Nagios range syntax with units. | `bits2human()`, `bps2human()`, `bytes2human()`, `human2bytes()`, `human2seconds()`, `humanrange2bytes()`, `number2human()`, `seconds2human()` |
-| **lftest.py** | Test harness for data-driven plugin unit tests, spinning up throwaway containers (including MySQL/MariaDB) as fixtures. | `attach_each()`, `attach_tests()`, `run()`, `run_container()`, `run_mysql_compatible_from_containerfile()`, `test()` |
+| **lftest.py** | Test harness for data-driven plugin unit tests, spinning up throwaway containers (including MySQL/MariaDB) as fixtures. | `attach_each()`, `attach_tests()`, `run()`, `run_container()`, `run_mysql_compatible_from_containerfile()`, `test()`, `test_json()` |
+| **openmetrics.py** | Reads the OpenMetrics and Prometheus text exposition formats served by a `/metrics` endpoint into plain samples, and selects a metric by name and labels. | `get_samples()`, `get_value()`, `parse()` |
 | **time.py** | Date/time conversions between UNIX epochs, ISO strings, and datetime objects, plus time-macro expansion and time differences. Timezone-aware. | `epoch2iso()`, `now()`, `timestr2datetime()`, `timestrdiff()` |
-| **txt.py** | Text processing: regex compilation, substring extraction, multi-line parsing, sensitive data redaction, pluralization, and byte/text encoding conversion. | `compile_regex()`, `extract_str()`, `match_regex()`, `mltext2array()`, `pluralize()`, `to_bytes()`, `to_text()` |
+| **txt.py** | Text processing: regex compilation, substring extraction, multi-line parsing, sensitive data redaction, pluralization, shortening for display, HTML character reference resolution, and byte/text encoding conversion. | `compile_regex()`, `extract_str()`, `match_regex()`, `mltext2array()`, `pluralize()`, `shorten()`, `to_bytes()`, `to_text()`, `unescape()` |
 | **version.py** | Software version parsing, comparison, and End-of-Life checking against [endoflife.date](https://endoflife.date). | `check_eol()`, `version()`, `version2float()` |
 
 
@@ -173,6 +173,7 @@ These libraries are built with a clear set of priorities:
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
 | **feedparser.py** | Parses Atom and RSS feeds from URLs using BeautifulSoup. | `parse()` |
+| **mail.py** | Sends email over SMTP, with an optional HTML body alongside the plain-text one and inline images referenced by Content-ID. Authenticates when a password is given. | `send()` |
 | **net.py** | Low-level networking: TCP/UDP/TLS and Unix domain sockets, public IP lookup, subnet enumeration, netmask conversion, and hostname validation. | `cidr_to_hosts()`, `fetch()`, `fetch_socket()`, `get_public_ip()`, `get_subnet_hosts()`, `ip_to_cidr()` |
 | **ssh.py** | Runs commands and copies files over SSH by building shell-free `ssh`/`scp`/`rsync` argument lists. | `build_options()`, `rsync()`, `run()`, `scp()`, `target()` |
 | **url.py** | HTTP/1.x and HTTP/2 client (httpx) for HTML, JSON, or raw data. Supports GET/POST, Basic/Digest authentication, TLS version pinning, proxy control, and connection telemetry. | `fetch()`, `fetch_json()`, `get_latest_version_from_github()`, `split_basic_auth()`, `strip_tags()` |
@@ -193,7 +194,8 @@ These libraries are built with a clear set of priorities:
 |--------|-------------|---------------|
 | **bexio.py** | [Bexio](https://www.bexio.com/) business software REST API (contacts, invoices, projects, items, timesheets, and more). | `call_api()`, `fetch_accounts()`, `fetch_contacts()`, `fetch_invoices()`, `fetch_projects()`, `get_all()` |
 | **grassfish.py** | [Grassfish](https://www.grassfish.com/) digital signage REST API. | `fetch_json()`, `set_player_defaults()`, `set_screen_defaults()` |
-| **huawei.py** | Huawei [OceanStor/Dorado](https://www.huawei.com/) storage REST API, decoding its numeric status, model, and hardware codes. | `get_data()`, `get_health_status()`, `get_running_status()`, `get_uuid()` |
+| **huawei_dorado.py** | Huawei [OceanStor Dorado](https://www.huawei.com/) storage DeviceManager REST API: session handling with device ID discovery, paged list walks, current performance counters, sector-to-byte capacity conversion, and the numeric status, model and hardware codes it reports. | `as_code()`, `assert_ok()`, `field()`, `get_all_data()`, `get_data()`, `get_health_status()`, `get_health_status_state()`, `get_performance()`, `get_running_status()`, `get_running_status_state()`, `get_uuid()`, `sectors2bytes()` |
+| **huawei_pacific.py** | Huawei [OceanStor Pacific](https://www.huawei.com/) storage REST API, including the older endpoint generation below `/dsware/service/`, the batch performance interface, and the status codes it reports as numbers and as strings. | `as_code()`, `assert_ok()`, `get_all_data()`, `get_data()`, `get_disk_status()`, `get_disk_status_state()`, `get_management_ips()`, `get_performance()`, `get_pool_status()`, `get_pool_status_state()`, `get_result_code()` |
 | **icinga.py** | [Icinga2](https://icinga.com/) REST API client for querying services and managing acknowledgements and downtimes. | `get_service()`, `remove_ack()`, `remove_downtime()`, `set_ack()`, `set_downtime()` |
 | **infomaniak.py** | [Infomaniak](https://www.infomaniak.com/) Swiss Backup REST API for events, backup products, and slots. | `get_events()`, `get_swiss_backup_products()`, `get_swiss_backup_slots()` |
 | **jitsi.py** | [Jitsi Meet](https://jitsi.org/) server statistics endpoint, with optional HTTP Basic auth. | `get_data()` |
@@ -207,6 +209,7 @@ These libraries are built with a clear set of priorities:
 | **uptimerobot.py** | [UptimeRobot](https://uptimerobot.com/) API for monitors, alert contacts, maintenance windows, and status pages. | `delete_monitor()`, `edit_monitor()`, `get_account_details()`, `get_alert_contacts()`, `get_monitors()`, `get_mwindows()`, `get_psps()`, `new_monitor()` |
 | **veeam.py** | [Veeam](https://www.veeam.com/) Backup & Replication Enterprise Manager REST API. | `get_token()` |
 | **wildfly.py** | [WildFly/JBoss](https://www.wildfly.org/) management API with digest auth (standalone and domain mode). | `get_data()` |
+| **wordpress.py** | [WordPress](https://wordpress.org/) installation read straight from the filesystem: core version, installed plugins and themes, the configured site URL, and any file header field. Needs no database, no HTTP request and no `wp-cli`. | `get_header_value()`, `get_plugins()`, `get_site_url()`, `get_themes()`, `get_version()`, `is_installation()` |
 
 
 ## Usage Example

{linuxfabrik_lib-6.0.0 → linuxfabrik_lib-7.0.0}/README.md

@@ -9,7 +9,6 @@
 <div align="center">
 
 ![GitHub Stars](https://img.shields.io/github/stars/linuxfabrik/lib)
-[![Star History Chart](https://api.star-history.com/svg?repos=Linuxfabrik/lib&type=Date)](https://star-history.com/#Linuxfabrik/lib&Date)
 ![License](https://img.shields.io/github/license/linuxfabrik/lib)
 ![Version](https://img.shields.io/github/v/release/linuxfabrik/lib?sort=semver)
 [![PyPI](https://img.shields.io/pypi/v/linuxfabrik-lib)](https://pypi.org/project/linuxfabrik-lib/)
@@ -67,13 +66,14 @@ These libraries are built with a clear set of priorities:
 
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
-| **args.py** | Extends `argparse` with custom input types for monitoring thresholds and a registry of reusable `--help` texts. | `csv()`, `float_or_none()`, `help()`, `int_or_none()`, `number_unit_method()` |
+| **args.py** | Extends `argparse` with custom input types for monitoring thresholds, a registry of reusable `--help` texts, and reading a secret from a file instead of the command line. | `csv()`, `float_or_none()`, `help()`, `int_or_none()`, `load_secret()`, `number_unit_method()` |
 | **base.py** | The central library for plugin development. Provides state evaluation, threshold comparison, performance data formatting, ASCII table output, and the `coe()` error-handling pattern. | `coe()`, `cu()`, `get_perfdata()`, `get_state()`, `get_table()`, `get_worst()`, `oao()`, `state2str()` |
 | **globals.py** | Defines the four Nagios/Icinga plugin states: `STATE_OK` (0), `STATE_WARN` (1), `STATE_CRIT` (2), `STATE_UNKNOWN` (3). | -- |
 | **human.py** | Converts raw numbers, byte sizes, bit rates, and durations to human-readable representations and back. Supports binary/SI prefixes and Nagios range syntax with units. | `bits2human()`, `bps2human()`, `bytes2human()`, `human2bytes()`, `human2seconds()`, `humanrange2bytes()`, `number2human()`, `seconds2human()` |
-| **lftest.py** | Test harness for data-driven plugin unit tests, spinning up throwaway containers (including MySQL/MariaDB) as fixtures. | `attach_each()`, `attach_tests()`, `run()`, `run_container()`, `run_mysql_compatible_from_containerfile()`, `test()` |
+| **lftest.py** | Test harness for data-driven plugin unit tests, spinning up throwaway containers (including MySQL/MariaDB) as fixtures. | `attach_each()`, `attach_tests()`, `run()`, `run_container()`, `run_mysql_compatible_from_containerfile()`, `test()`, `test_json()` |
+| **openmetrics.py** | Reads the OpenMetrics and Prometheus text exposition formats served by a `/metrics` endpoint into plain samples, and selects a metric by name and labels. | `get_samples()`, `get_value()`, `parse()` |
 | **time.py** | Date/time conversions between UNIX epochs, ISO strings, and datetime objects, plus time-macro expansion and time differences. Timezone-aware. | `epoch2iso()`, `now()`, `timestr2datetime()`, `timestrdiff()` |
-| **txt.py** | Text processing: regex compilation, substring extraction, multi-line parsing, sensitive data redaction, pluralization, and byte/text encoding conversion. | `compile_regex()`, `extract_str()`, `match_regex()`, `mltext2array()`, `pluralize()`, `to_bytes()`, `to_text()` |
+| **txt.py** | Text processing: regex compilation, substring extraction, multi-line parsing, sensitive data redaction, pluralization, shortening for display, HTML character reference resolution, and byte/text encoding conversion. | `compile_regex()`, `extract_str()`, `match_regex()`, `mltext2array()`, `pluralize()`, `shorten()`, `to_bytes()`, `to_text()`, `unescape()` |
 | **version.py** | Software version parsing, comparison, and End-of-Life checking against [endoflife.date](https://endoflife.date). | `check_eol()`, `version()`, `version2float()` |
 
 
@@ -103,6 +103,7 @@ These libraries are built with a clear set of priorities:
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
 | **feedparser.py** | Parses Atom and RSS feeds from URLs using BeautifulSoup. | `parse()` |
+| **mail.py** | Sends email over SMTP, with an optional HTML body alongside the plain-text one and inline images referenced by Content-ID. Authenticates when a password is given. | `send()` |
 | **net.py** | Low-level networking: TCP/UDP/TLS and Unix domain sockets, public IP lookup, subnet enumeration, netmask conversion, and hostname validation. | `cidr_to_hosts()`, `fetch()`, `fetch_socket()`, `get_public_ip()`, `get_subnet_hosts()`, `ip_to_cidr()` |
 | **ssh.py** | Runs commands and copies files over SSH by building shell-free `ssh`/`scp`/`rsync` argument lists. | `build_options()`, `rsync()`, `run()`, `scp()`, `target()` |
 | **url.py** | HTTP/1.x and HTTP/2 client (httpx) for HTML, JSON, or raw data. Supports GET/POST, Basic/Digest authentication, TLS version pinning, proxy control, and connection telemetry. | `fetch()`, `fetch_json()`, `get_latest_version_from_github()`, `split_basic_auth()`, `strip_tags()` |
@@ -123,7 +124,8 @@ These libraries are built with a clear set of priorities:
 |--------|-------------|---------------|
 | **bexio.py** | [Bexio](https://www.bexio.com/) business software REST API (contacts, invoices, projects, items, timesheets, and more). | `call_api()`, `fetch_accounts()`, `fetch_contacts()`, `fetch_invoices()`, `fetch_projects()`, `get_all()` |
 | **grassfish.py** | [Grassfish](https://www.grassfish.com/) digital signage REST API. | `fetch_json()`, `set_player_defaults()`, `set_screen_defaults()` |
-| **huawei.py** | Huawei [OceanStor/Dorado](https://www.huawei.com/) storage REST API, decoding its numeric status, model, and hardware codes. | `get_data()`, `get_health_status()`, `get_running_status()`, `get_uuid()` |
+| **huawei_dorado.py** | Huawei [OceanStor Dorado](https://www.huawei.com/) storage DeviceManager REST API: session handling with device ID discovery, paged list walks, current performance counters, sector-to-byte capacity conversion, and the numeric status, model and hardware codes it reports. | `as_code()`, `assert_ok()`, `field()`, `get_all_data()`, `get_data()`, `get_health_status()`, `get_health_status_state()`, `get_performance()`, `get_running_status()`, `get_running_status_state()`, `get_uuid()`, `sectors2bytes()` |
+| **huawei_pacific.py** | Huawei [OceanStor Pacific](https://www.huawei.com/) storage REST API, including the older endpoint generation below `/dsware/service/`, the batch performance interface, and the status codes it reports as numbers and as strings. | `as_code()`, `assert_ok()`, `get_all_data()`, `get_data()`, `get_disk_status()`, `get_disk_status_state()`, `get_management_ips()`, `get_performance()`, `get_pool_status()`, `get_pool_status_state()`, `get_result_code()` |
 | **icinga.py** | [Icinga2](https://icinga.com/) REST API client for querying services and managing acknowledgements and downtimes. | `get_service()`, `remove_ack()`, `remove_downtime()`, `set_ack()`, `set_downtime()` |
 | **infomaniak.py** | [Infomaniak](https://www.infomaniak.com/) Swiss Backup REST API for events, backup products, and slots. | `get_events()`, `get_swiss_backup_products()`, `get_swiss_backup_slots()` |
 | **jitsi.py** | [Jitsi Meet](https://jitsi.org/) server statistics endpoint, with optional HTTP Basic auth. | `get_data()` |
@@ -137,6 +139,7 @@ These libraries are built with a clear set of priorities:
 | **uptimerobot.py** | [UptimeRobot](https://uptimerobot.com/) API for monitors, alert contacts, maintenance windows, and status pages. | `delete_monitor()`, `edit_monitor()`, `get_account_details()`, `get_alert_contacts()`, `get_monitors()`, `get_mwindows()`, `get_psps()`, `new_monitor()` |
 | **veeam.py** | [Veeam](https://www.veeam.com/) Backup & Replication Enterprise Manager REST API. | `get_token()` |
 | **wildfly.py** | [WildFly/JBoss](https://www.wildfly.org/) management API with digest auth (standalone and domain mode). | `get_data()` |
+| **wordpress.py** | [WordPress](https://wordpress.org/) installation read straight from the filesystem: core version, installed plugins and themes, the configured site URL, and any file header field. Needs no database, no HTTP request and no `wp-cli`. | `get_header_value()`, `get_plugins()`, `get_site_url()`, `get_themes()`, `get_version()`, `is_installation()` |
 
 
 ## Usage Example

{linuxfabrik_lib-6.0.0 → linuxfabrik_lib-7.0.0}/args.py

@@ -11,9 +11,28 @@
 """Extends argparse by new input argument data types on demand."""
 
 import argparse
+import os
+import re
+import textwrap
+
+from . import base, disk
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026070201'
+__version__ = '2026081003'
+
+# Base URL of the rendered online documentation.
+DOCS_BASE_URL = 'https://linuxfabrik.github.io/monitoring-plugins'
+
+# How an include filter and an exclude filter combine, for the consumers that offer both.
+# Kept out of the two help texts themselves and appended by the consumer, because the
+# purpose sentence in front of it names whatever the consumer filters - items, mount
+# points, disks, findings - while this sentence is the same everywhere. It belongs on the
+# include filter alone: it describes the pair, and saying it twice only makes both entries
+# longer.
+MATCH_IGNORE_PRECEDENCE = (
+    'If both `--match` and `--ignore` are given, an item must match `--match` AND not '
+    'match `--ignore` to be reported (include first, exclude second).'
+)
 
 
 # Help text descriptions only - no "Default:" here.
@@ -22,6 +41,12 @@ __version__ = '2026070201'
 # Switches (store_true/store_false) don't need a default.
 HELP_TEXTS = {
     '--always-ok': 'Always returns OK.',
+    '--brief': (
+        'Hide the rows that are within the thresholds and show only those in a WARN or '
+        'CRIT state. '
+        'Perfdata and alerting are unaffected: every item still emits performance data '
+        'and still drives the overall check state, so this is safe to leave on.'
+    ),
     '--cache-expire': (
         'The amount of time after which the credential/data cache expires, in minutes.'
     ),
@@ -53,11 +78,19 @@ HELP_TEXTS = {
     '--critical': 'CRIT threshold in percent.',
     '--critical-count': 'CRIT threshold for the number of matching items.',
     '--critical-seconds': 'CRIT threshold in seconds.',
+    '--critical-temperature': 'CRIT threshold in degrees Celsius.',
+    '--critical-voltage': 'CRIT threshold in volts.',
     '--defaults-file': (
         'Specifies a cnf file to read parameters like user, host and password from '
         '(for MySQL/MariaDB cnf-style files).'
     ),
     '--defaults-group': 'Group/section to read from in the cnf file.',
+    '--fail-severity': (
+        'State to report for an item the monitored system itself marks as failed. '
+        'A failed item means the installation is broken in a way that stops it from '
+        'working correctly, which is worth acting on but rarely worth waking somebody '
+        'up for.'
+    ),
     '--hostname': 'Hostname or IP address.',
     '--ipv6': 'Use IPv6.',
     '--ignore': (
@@ -78,22 +111,60 @@ HELP_TEXTS = {
     ),
     '--insecure': 'This option explicitly allows insecure SSL connections.',
     '--lengthy': 'Extended reporting.',
+    '--link-down-severity': (
+        'State to report for a port whose link is down. '
+        'A port that is simply not cabled reports the same thing, which is why this '
+        'defaults to not alerting.'
+    ),
     '--match': (
         'Filter by this Python regular expression. '
         'Case-sensitive by default; use `(?i)` for case-insensitive matching. '
         'Can be specified multiple times. '
+        f'{MATCH_IGNORE_PRECEDENCE} '
         'Examples: '
         '`(?i)example` to match "example" regardless of case. '
         '`^(?!.*example).*$` to match any string except "example" (negative lookahead).'
     ),
+    '--no-checksum-data-severity': (
+        'State to report when no published checksums are available for a component and it '
+        'could not be verified. '
+        'The check still verifies everything it has checksums for, but a clean result then '
+        'only covers those components, not the ones it had to skip.'
+    ),
+    '--no-insecure': (
+        'Verify the TLS certificate against the system trust store, overriding the '
+        'insecure default of this check. '
+        'Use it once the endpoint presents a publicly trusted certificate, or once its '
+        'CA has been added to the system trust store.'
+    ),
     '--no-match-severity': (
         'State to report when no item matches the filters and nothing is checked.'
     ),
+    '--no-perfdata': (
+        'Suppress the performance data section from the output. '
+        'The status message and the exit code are unaffected, so alerting keeps working '
+        'while trending data is dropped.'
+    ),
     '--no-proxy': 'Do not use a proxy.',
+    '--no-vuln-data-severity': (
+        'State to report when the vulnerability database could not be queried and no '
+        'vulnerability data is available. '
+        'The check still reports everything it can determine without that data, but a '
+        'clean result then only means nothing else was found, not that the target is '
+        'free of known vulnerabilities.'
+    ),
     '--offset-eol': (
         'Alert n days before ("-30") or after an EOL date ("30" or "+30").'
     ),
     '--password': 'Password.',
+    '--password-file': (
+        'Path to a file holding the password, read from its first line. '
+        'Keeps the password out of the process list, where a command-line argument is '
+        'visible to every user on the host. '
+        'Takes precedence over `--password`. '
+        'Keep the file readable only by the monitoring user. '
+        'Example: `--password-file=/etc/icinga2/secrets/storage`.'
+    ),
     '--path': 'Local path to the installation.',
     '--port': 'Port number.',
     '--severity': 'Severity for alerting.',
@@ -112,8 +183,16 @@ HELP_TEXTS = {
     '--test': argparse.SUPPRESS,
     '--timeout': 'Network timeout in seconds.',
     '--unreachable-severity': (
-        'State to report when the online end-of-life source is unreachable and the check falls '
-        'back to the bundled offline data.'
+        'State to report when the online source is unreachable. '
+        'What is used instead - bundled offline data, a cached copy, or nothing at all - '
+        'is named in the output, and a clean result then only covers what that fallback '
+        'could confirm.'
+    ),
+    '--unscored-severity': (
+        'State to report for a finding that carries no severity score of its own. '
+        'A source that scores its findings rarely scores all of them, and the unrated '
+        'ones need a state of their own rather than the one a score would have earned '
+        'them.'
     ),
     '--url': 'URL to the endpoint.',
     '--username': 'Username.',
@@ -124,6 +203,8 @@ HELP_TEXTS = {
     '--warning': 'WARN threshold in percent.',
     '--warning-count': 'WARN threshold for the number of matching items.',
     '--warning-seconds': 'WARN threshold in seconds.',
+    '--warning-temperature': 'WARN threshold in degrees Celsius.',
+    '--warning-voltage': 'WARN threshold in volts.',
 }
 
 
@@ -132,6 +213,25 @@ _UNITS = {'%', 'K', 'M', 'G', 'T', 'P'}
 _METHODS = {'USED', 'FREE'}
 
 
+class HelpFormatter(argparse.HelpFormatter):
+    """Formats the help output like argparse does, but never splits long words.
+
+    argparse's default formatter breaks words at hyphens to fit the terminal width,
+    which turns a URL like `https://example.com/a-b/c/` into two unusable fragments.
+    Here, a word that does not fit is kept intact and overflows instead.
+    """
+
+    def _fill_text(self, text, width, indent):
+        return textwrap.fill(
+            re.sub(r'\s+', ' ', text).strip(),
+            width,
+            initial_indent=indent,
+            subsequent_indent=indent,
+            break_long_words=False,
+            break_on_hyphens=False,
+        )
+
+
 def csv(arg):
     """Converts a CSV string into a list of values.
 
@@ -148,6 +248,34 @@ def csv(arg):
     return [x.strip() for x in arg.split(',')]
 
 
+def epilog(path, section='check-plugins'):
+    """Builds a pointer to the online documentation, to be used as an argparse epilog.
+
+    The document name is derived from the file name of the calling script, so pass
+    `__file__`. A trailing `.exe` or `.py` extension is stripped.
+
+    Use together with `HelpFormatter`, otherwise argparse breaks the URL at its hyphens.
+
+    ### Parameters
+    - **path** (`str`): Path of the calling script, normally `__file__`.
+    - **section** (`str`, optional): Section the document lives in.
+      Defaults to `check-plugins`.
+
+    ### Returns
+    - **str**: A single line pointing to the documentation URL.
+
+    ### Example
+    >>> epilog('/usr/lib64/nagios/plugins/example')
+    'Documentation: https://linuxfabrik.github.io/monitoring-plugins/check-plugins/example/'
+    """
+    name = os.path.basename(path)
+    for suffix in ('.exe', '.py'):
+        if name.lower().endswith(suffix):
+            name = name[: -len(suffix)]
+            break
+    return f'Documentation: {DOCS_BASE_URL}/{section}/{name}/'
+
+
 def float_or_none(arg):
     """Converts an input to a float, or returns None if the input is 'none' or None.
 
@@ -214,6 +342,47 @@ def int_or_none(arg):
     return int(arg)
 
 
+def load_secret(path, param='--password-file'):
+    """
+    Read a secret out of a file, so it does not have to be passed on the command line.
+
+    A command-line argument is visible to every user on the host for as long as the
+    process runs, and a monitoring plugin runs on a schedule. Reading the secret from a
+    file that only the monitoring user can read keeps it out of the process list.
+
+    ### Parameters
+    - **path** (`str`): The file to read.
+    - **param** (`str`, optional): The parameter name to use in an error message.
+
+    ### Returns
+    - **str**: The secret, without the trailing newline a text editor appends.
+
+    ### Notes
+    - Aborts the calling process (UNKNOWN) when the file cannot be read or holds nothing.
+      A secret that silently comes out empty would be sent to the remote end as an empty
+      password, which drives the account towards its lockout threshold.
+    - Only the first line is used, and only its trailing newline is stripped. Leading and
+      trailing spaces are part of a password, and stripping them would make a valid
+      password fail with no way to tell why.
+    - The file permissions are deliberately not enforced here. Which user a check runs as
+      differs per deployment, and refusing to start over a permission bit would take a
+      working check down; keeping the file readable only by the monitoring user is the
+      documented operator's job.
+
+    ### Example
+    >>> load_secret('/etc/icinga2/secrets/storage')
+    'linuxfabrik'
+    """
+    success, content = disk.read_file(path)
+    if not success:
+        base.cu(f'Cannot read the file given in {param}: {content}')
+
+    secret = content.split('\n', 1)[0].rstrip('\r')
+    if not secret:
+        base.cu(f'The file given in {param} is empty.')
+    return secret
+
+
 def number_unit_method(arg, unit='%', method='USED'):
     """Parses a string in the format `<number>[unit][method]` for threshold arguments.