linuxfabrik-lib 8.2.0__tar.gz → 8.3.0__tar.gz

{linuxfabrik_lib-8.2.0 → linuxfabrik_lib-8.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: linuxfabrik-lib
-Version: 8.2.0
-Summary: Python libraries used in various Linuxfabrik projects, including the 'Linuxfabrik Monitoring Plugins' project.
+Version: 8.3.0
+Summary: Python 3.9+ utility library: argument parsing, output formatting, HTTP, shell, disk, SQLite/MySQL, caching, version checks, plus API clients.
 Author-email: "Linuxfabrik GmbH, Zurich, Switzerland" <info@linuxfabrik.ch>
 License: This is free and unencumbered software released into the public domain.
         
@@ -63,7 +63,6 @@ Requires-Dist: lxml
 Requires-Dist: psutil
 Requires-Dist: pymysql
 Requires-Dist: pypsrp
-Requires-Dist: PySmbClient
 Requires-Dist: pywinrm
 Requires-Dist: smbprotocol
 Requires-Dist: xmltodict
@@ -73,7 +72,7 @@ Dynamic: license-file
   Linuxfabrik Python Libraries
 </h1>
 <p align="center">
-  Python 3.9+ modules for Linuxfabrik projects: DB access, SQLite KVS caching, WinRM, SMB, shell execution, 15+ API integrations (Icinga2, Veeam, Nextcloud, ...). Available on PyPI.
+  Python 3.9+ utility library: argument parsing, output formatting, HTTP, shell, disk, SQLite/MySQL, caching, version checks, plus API clients. Available on PyPI.
   <span>&#8226;</span>
   <b>made by <a href="https://linuxfabrik.ch/">Linuxfabrik</a></b>
 </p>
@@ -95,7 +94,7 @@ Dynamic: license-file
 
 # Linuxfabrik Python Libraries
 
-A mature, production-grade Python library collection providing 40 modules with 300+ functions for system administration, monitoring, and infrastructure automation. These libraries are used across several Linuxfabrik projects -- most prominently the [Linuxfabrik Monitoring Plugins](https://github.com/Linuxfabrik/monitoring-plugins) (Nagios/Icinga check plugins), but also in [ChecklistFabrik](https://github.com/Linuxfabrik/checklistfabrik) and other tools.
+A mature, production-grade Python library collection for system administration, monitoring, and infrastructure automation. It does not assume a particular consumer: any Python tool can use it, from check plugins to deployment scripts.
 
 > If these libraries help you developing your own monitoring plugins, system tools or infrastructure automation, please give it a star.
 
@@ -120,14 +119,14 @@ pip install --user linuxfabrik-lib
 
 These libraries are built with a clear set of priorities:
 
-* **Procedural by design.** The libraries deliberately use a procedural/functional style rather than object-oriented programming. Pure functions with explicit inputs and outputs are easier to read, test, and reason about. This is especially true for the most prominent use case -- monitoring plugins -- which are short-lived, linear processes with no complex state to manage over time, where unnecessary abstraction layers would add overhead without tangible benefit.
+* **Procedural by design.** The libraries deliberately use a procedural/functional style rather than object-oriented programming. Pure functions with explicit inputs and outputs are easier to read, test, and reason about. Most consumers are short-lived, linear processes with no complex state to manage over time, where unnecessary abstraction layers would add overhead without tangible benefit.
 * **Broad compatibility.** Python 3.9+ is the minimum, ensuring the libraries work on RHEL 8 and every major distribution without requiring newer runtimes.
 * **Cross-platform.** Core functions behave identically on Linux, Windows, and macOS. Platform-specific code (WinRM, PowerShell, SMB) is cleanly separated.
 * **Minimal dependencies.** We avoid pulling in large dependency trees. External packages are used only when the alternative would be unreliable or significantly more complex.
-* **Consistent error handling.** Most functions return `(success, result)` tuples. The caller decides whether to continue or exit -- the library never exits on its own. The `base.coe()` ("Continue or Exit") helper makes this pattern concise.
+* **Consistent error handling.** Most functions return `(success, result)` tuples. The caller decides whether to continue or exit, the library never exits on its own. The `base.coe()` ("Continue or Exit") helper makes this pattern concise.
 * **Automatic redaction.** Sensitive data (passwords, tokens, API keys) in error messages is automatically sanitized before output.
 * **Nagios/Icinga conventions.** State constants, threshold evaluation, performance data formatting, and range parsing follow the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
-* **Defensive defaults.** Functions use sensible timeouts, safe SSL settings, and locked-down defaults so that plugins work out of the box without extensive configuration.
+* **Defensive defaults.** Functions use sensible timeouts, safe SSL settings, and locked-down defaults so that consumers work out of the box without extensive configuration.
 
 
 ## Library Index
@@ -138,7 +137,7 @@ 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, a registry of reusable `--help` texts, and reading a secret from a file instead of the command line. | `csv()`, `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()` |
+| **base.py** | The central module for check-style tools. 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()`, `test_json()` |
@@ -146,28 +145,38 @@ These libraries are built with a clear set of priorities:
 | **task.py** | Runs callables under a deadline that holds even where the work cannot be interrupted, each in a process of its own and all of them sharing one deadline. | `run()`, `run_each()` |
 | **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, 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()` |
+| **version.py** | Software version parsing, comparison, and End-of-Life checking against [endoflife.date](https://endoflife.date), or against the life cycle RHEL, Debian and Ubuntu give the software they ship. | `check_eol()`, `version()`, `version2float()` |
 
 
 ### Data Access & Caching
 
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
-| **cache.py** | A simple SQLite-based key-value store with optional key expiration. Used for persisting state between plugin runs. | `get()`, `set()` |
+| **cache.py** | A simple SQLite-based key-value store with optional key expiration. Used for persisting state between runs. | `get()`, `set()` |
 | **db_mysql.py** | MySQL/MariaDB client with connection management, query execution, privilege checking, and server flavor/status/variable/replication inspection. | `check_privileges()`, `connect()`, `get_all_variables()`, `get_engines()`, `get_replica_status()`, `lod2dict()`, `select()` |
 | **db_sqlite.py** | Full SQLite interface: table/index creation, CRUD operations, CSV import, regex support, and per-second counter deltas for time-series data. | `connect()`, `create_index()`, `create_table()`, `cut()`, `delete()`, `insert()`, `per_second_deltas()`, `select()` |
+| **logmatch.py** | Keeps log findings in an SQLite state database across runs until they age out or are acknowledged on the monitoring server, together with the read position of the log. | `acknowledge()`, `connect()`, `key()`, `pending()`, `record()`, `service_acknowledged()` |
 
 
 ### System & OS
 
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
+| **container.py** | Runs a container engine command-line client (Docker, Podman) under a deadline and tells a missing permission apart from an engine that is down or does not answer. | `get_engine_error()`, `run()` |
 | **disk.py** | File I/O, directory walking, CSV/environment file parsing, block device and partition listing, and temp directory management. | `dir_exists()`, `file_exists()`, `get_real_disks()`, `get_tmpdir()`, `grep_file()`, `read_file()` |
 | **distro.py** | Linux distribution detection. Returns normalized facts including distribution name, version, and Ansible-compatible `os_family`. | `get_distribution_facts()` |
 | **dmidecode.py** | Parses `dmidecode` output into structured data. Extracts CPU, RAM, firmware, serial number, manufacturer, and model information. | `cpu_speed()`, `cpu_type()`, `firmware()`, `get_data()`, `manufacturer()`, `model()`, `ram()`, `serno()` |
 | **endoflifedate.py** | Bundled End-of-Life data from [endoflife.date](https://endoflife.date) for offline version checks when internet access is unavailable. | -- |
+| **kvm.py** | libvirt domains, storage pools and volumes via `virsh` on a read-only connection, which needs neither root nor sudo. | `get_domains()`, `get_domstats()`, `get_pool_info()`, `get_pools()`, `get_volumes()`, `virsh()` |
+| **logsource.py** | Reads a log incrementally from a file, a systemd unit in the journal, or a container, and hands back a position that survives rotation and truncation. | `parse()`, `read()`, `read_many()`, `timestamp()` |
+| **lvm.py** | LVM logical volumes and volume groups via `lvs` and `vgs`, including thin pools, snapshots, health status and the thin pool metadata limit. | `get_logical_volumes()`, `get_volume_groups()`, `health()`, `is_snapshot_invalid()`, `is_thin_pool()`, `metadata_limit()` |
+| **lynis.py** | The machine-readable report of a Lynis security audit (`/var/log/lynis-report.dat`): hardening index, findings and suggestions, and the list of them for the plugin output. | `get_findings_msg()`, `parse_findings()`, `parse_report()` |
+| **psi.py** | Linux pressure stall information (PSI) from `/proc/pressure` for CPU, I/O, IRQ and memory, with state evaluation and report output. | `get_perfdata()`, `get_states()`, `get_summary()`, `get_table()`, `is_enabled()`, `read()` |
 | **psutil.py** | Wrapper around `psutil` for retrieving mounted disk partitions with device, mount point, filesystem type and mount options. Lists them from the mount table alone, so a network filesystem whose server is gone cannot hold the listing up. | `get_partitions()` |
+| **restic.py** | Builds the repository and password arguments for the `restic` backup client so a privileged caller cannot make it read an arbitrary file or run an external program. | `password_file_arg()`, `repo_args()` |
+| **rhelappstreams.py** | Bundled life cycle of the RHEL Application Streams, generated weekly from the data Red Hat publishes in [digital-roadmap-backend](https://github.com/RedHatInsights/digital-roadmap-backend). | -- |
 | **shell.py** | Runs external commands from an argv list without a shell, guards option-style CLI values, and locates executables in `PATH`. | `safe_cli_value()`, `shell_exec()`, `which()` |
+| **user.py** | Local Unix accounts: UID/GID names, the system/regular account boundary, interactive shells and the state of the shadow password. | `get_gid_name()`, `get_interactive_shells()`, `get_shadow_password()`, `get_uid_min()`, `get_uid_name()`, `password_state()` |
 
 
 ### Networking & HTTP
@@ -205,6 +214,7 @@ These libraries are built with a clear set of priorities:
 | **librenms.py** | [LibreNMS](https://www.librenms.org/) monitoring API, mapping its alert states to Nagios states. | `get_data()`, `get_state()` |
 | **nextcloud.py** | [Nextcloud](https://nextcloud.com/) `occ` command execution as the `config.php` owner, parsing JSON or text output. | `run_occ()` |
 | **nodebb.py** | [NodeBB](https://nodebb.org/) forum API, using a Bearer user token. | `get_data()` |
+| **openstack.py** | [OpenStack](https://www.openstack.org/) Identity v3 authentication from an rc file, with the token reused across runs, and access to the service REST APIs. | `connect()`, `fetch()`, `fetch_json()` |
 | **qts.py** | QNAP [QTS](https://www.qnap.com/) NAS API with session authentication. | `get_auth_sid()` |
 | **redfish.py** | [Redfish](https://www.dmtf.org/standards/redfish) BMC API for chassis, systems, storage, managers, and sensors, deriving Nagios states and perfdata. | `get_auth_header()`, `get_perfdata()`, `get_state()`, `get_systems()` |
 | **rocket.py** | [Rocket.Chat](https://www.rocket.chat/) REST API for login, room/group history, statistics, and incoming webhooks. | `get_groups_history()`, `get_rooms_get()`, `get_stats()`, `get_token()`, `send2webhook()` |
@@ -216,21 +226,31 @@ These libraries are built with a clear set of priorities:
 
 ## Usage Example
 
-A typical monitoring plugin using these libraries:
+A typical check-style tool using these libraries:
 
 ```python
+import argparse
+
 import lib.args
 import lib.base
 import lib.url
-from lib.globals import STATE_CRIT, STATE_OK, STATE_UNKNOWN, STATE_WARN
 
 
 def main():
-    # Parse arguments with custom threshold types
-    parser = lib.args.ArgumentParser()
-    parser.add_argument('--url', required=True)
-    parser.add_argument('--warning', type=lib.args.float_or_none, default=80)
-    parser.add_argument('--critical', type=lib.args.float_or_none, default=90)
+    parser = argparse.ArgumentParser(description='Checks the usage reported by an API.')
+    parser.add_argument('--url', required=True, help=lib.args.help('--url'))
+    parser.add_argument(
+        '--warning',
+        type=float,
+        default=80,
+        help=lib.args.help('--warning') + ' Default: %(default)s',
+    )
+    parser.add_argument(
+        '--critical',
+        type=float,
+        default=90,
+        help=lib.args.help('--critical') + ' Default: %(default)s',
+    )
     args = parser.parse_args()
 
     # Fetch data (coe = "Continue or Exit")
@@ -243,7 +263,7 @@ def main():
     )
 
     # Output and exit
-    lib.base.oao('Usage is {}%'.format(result['usage']), state, perfdata)
+    lib.base.oao(f'Usage is {result["usage"]}%', state, perfdata)
 
 
 if __name__ == '__main__':

{linuxfabrik_lib-8.2.0 → linuxfabrik_lib-8.3.0}/README.md

@@ -2,7 +2,7 @@
   Linuxfabrik Python Libraries
 </h1>
 <p align="center">
-  Python 3.9+ modules for Linuxfabrik projects: DB access, SQLite KVS caching, WinRM, SMB, shell execution, 15+ API integrations (Icinga2, Veeam, Nextcloud, ...). Available on PyPI.
+  Python 3.9+ utility library: argument parsing, output formatting, HTTP, shell, disk, SQLite/MySQL, caching, version checks, plus API clients. Available on PyPI.
   <span>&#8226;</span>
   <b>made by <a href="https://linuxfabrik.ch/">Linuxfabrik</a></b>
 </p>
@@ -24,7 +24,7 @@
 
 # Linuxfabrik Python Libraries
 
-A mature, production-grade Python library collection providing 40 modules with 300+ functions for system administration, monitoring, and infrastructure automation. These libraries are used across several Linuxfabrik projects -- most prominently the [Linuxfabrik Monitoring Plugins](https://github.com/Linuxfabrik/monitoring-plugins) (Nagios/Icinga check plugins), but also in [ChecklistFabrik](https://github.com/Linuxfabrik/checklistfabrik) and other tools.
+A mature, production-grade Python library collection for system administration, monitoring, and infrastructure automation. It does not assume a particular consumer: any Python tool can use it, from check plugins to deployment scripts.
 
 > If these libraries help you developing your own monitoring plugins, system tools or infrastructure automation, please give it a star.
 
@@ -49,14 +49,14 @@ pip install --user linuxfabrik-lib
 
 These libraries are built with a clear set of priorities:
 
-* **Procedural by design.** The libraries deliberately use a procedural/functional style rather than object-oriented programming. Pure functions with explicit inputs and outputs are easier to read, test, and reason about. This is especially true for the most prominent use case -- monitoring plugins -- which are short-lived, linear processes with no complex state to manage over time, where unnecessary abstraction layers would add overhead without tangible benefit.
+* **Procedural by design.** The libraries deliberately use a procedural/functional style rather than object-oriented programming. Pure functions with explicit inputs and outputs are easier to read, test, and reason about. Most consumers are short-lived, linear processes with no complex state to manage over time, where unnecessary abstraction layers would add overhead without tangible benefit.
 * **Broad compatibility.** Python 3.9+ is the minimum, ensuring the libraries work on RHEL 8 and every major distribution without requiring newer runtimes.
 * **Cross-platform.** Core functions behave identically on Linux, Windows, and macOS. Platform-specific code (WinRM, PowerShell, SMB) is cleanly separated.
 * **Minimal dependencies.** We avoid pulling in large dependency trees. External packages are used only when the alternative would be unreliable or significantly more complex.
-* **Consistent error handling.** Most functions return `(success, result)` tuples. The caller decides whether to continue or exit -- the library never exits on its own. The `base.coe()` ("Continue or Exit") helper makes this pattern concise.
+* **Consistent error handling.** Most functions return `(success, result)` tuples. The caller decides whether to continue or exit, the library never exits on its own. The `base.coe()` ("Continue or Exit") helper makes this pattern concise.
 * **Automatic redaction.** Sensitive data (passwords, tokens, API keys) in error messages is automatically sanitized before output.
 * **Nagios/Icinga conventions.** State constants, threshold evaluation, performance data formatting, and range parsing follow the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
-* **Defensive defaults.** Functions use sensible timeouts, safe SSL settings, and locked-down defaults so that plugins work out of the box without extensive configuration.
+* **Defensive defaults.** Functions use sensible timeouts, safe SSL settings, and locked-down defaults so that consumers work out of the box without extensive configuration.
 
 
 ## Library Index
@@ -67,7 +67,7 @@ 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, a registry of reusable `--help` texts, and reading a secret from a file instead of the command line. | `csv()`, `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()` |
+| **base.py** | The central module for check-style tools. 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()`, `test_json()` |
@@ -75,28 +75,38 @@ These libraries are built with a clear set of priorities:
 | **task.py** | Runs callables under a deadline that holds even where the work cannot be interrupted, each in a process of its own and all of them sharing one deadline. | `run()`, `run_each()` |
 | **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, 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()` |
+| **version.py** | Software version parsing, comparison, and End-of-Life checking against [endoflife.date](https://endoflife.date), or against the life cycle RHEL, Debian and Ubuntu give the software they ship. | `check_eol()`, `version()`, `version2float()` |
 
 
 ### Data Access & Caching
 
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
-| **cache.py** | A simple SQLite-based key-value store with optional key expiration. Used for persisting state between plugin runs. | `get()`, `set()` |
+| **cache.py** | A simple SQLite-based key-value store with optional key expiration. Used for persisting state between runs. | `get()`, `set()` |
 | **db_mysql.py** | MySQL/MariaDB client with connection management, query execution, privilege checking, and server flavor/status/variable/replication inspection. | `check_privileges()`, `connect()`, `get_all_variables()`, `get_engines()`, `get_replica_status()`, `lod2dict()`, `select()` |
 | **db_sqlite.py** | Full SQLite interface: table/index creation, CRUD operations, CSV import, regex support, and per-second counter deltas for time-series data. | `connect()`, `create_index()`, `create_table()`, `cut()`, `delete()`, `insert()`, `per_second_deltas()`, `select()` |
+| **logmatch.py** | Keeps log findings in an SQLite state database across runs until they age out or are acknowledged on the monitoring server, together with the read position of the log. | `acknowledge()`, `connect()`, `key()`, `pending()`, `record()`, `service_acknowledged()` |
 
 
 ### System & OS
 
 | Module | Description | Key Functions |
 |--------|-------------|---------------|
+| **container.py** | Runs a container engine command-line client (Docker, Podman) under a deadline and tells a missing permission apart from an engine that is down or does not answer. | `get_engine_error()`, `run()` |
 | **disk.py** | File I/O, directory walking, CSV/environment file parsing, block device and partition listing, and temp directory management. | `dir_exists()`, `file_exists()`, `get_real_disks()`, `get_tmpdir()`, `grep_file()`, `read_file()` |
 | **distro.py** | Linux distribution detection. Returns normalized facts including distribution name, version, and Ansible-compatible `os_family`. | `get_distribution_facts()` |
 | **dmidecode.py** | Parses `dmidecode` output into structured data. Extracts CPU, RAM, firmware, serial number, manufacturer, and model information. | `cpu_speed()`, `cpu_type()`, `firmware()`, `get_data()`, `manufacturer()`, `model()`, `ram()`, `serno()` |
 | **endoflifedate.py** | Bundled End-of-Life data from [endoflife.date](https://endoflife.date) for offline version checks when internet access is unavailable. | -- |
+| **kvm.py** | libvirt domains, storage pools and volumes via `virsh` on a read-only connection, which needs neither root nor sudo. | `get_domains()`, `get_domstats()`, `get_pool_info()`, `get_pools()`, `get_volumes()`, `virsh()` |
+| **logsource.py** | Reads a log incrementally from a file, a systemd unit in the journal, or a container, and hands back a position that survives rotation and truncation. | `parse()`, `read()`, `read_many()`, `timestamp()` |
+| **lvm.py** | LVM logical volumes and volume groups via `lvs` and `vgs`, including thin pools, snapshots, health status and the thin pool metadata limit. | `get_logical_volumes()`, `get_volume_groups()`, `health()`, `is_snapshot_invalid()`, `is_thin_pool()`, `metadata_limit()` |
+| **lynis.py** | The machine-readable report of a Lynis security audit (`/var/log/lynis-report.dat`): hardening index, findings and suggestions, and the list of them for the plugin output. | `get_findings_msg()`, `parse_findings()`, `parse_report()` |
+| **psi.py** | Linux pressure stall information (PSI) from `/proc/pressure` for CPU, I/O, IRQ and memory, with state evaluation and report output. | `get_perfdata()`, `get_states()`, `get_summary()`, `get_table()`, `is_enabled()`, `read()` |
 | **psutil.py** | Wrapper around `psutil` for retrieving mounted disk partitions with device, mount point, filesystem type and mount options. Lists them from the mount table alone, so a network filesystem whose server is gone cannot hold the listing up. | `get_partitions()` |
+| **restic.py** | Builds the repository and password arguments for the `restic` backup client so a privileged caller cannot make it read an arbitrary file or run an external program. | `password_file_arg()`, `repo_args()` |
+| **rhelappstreams.py** | Bundled life cycle of the RHEL Application Streams, generated weekly from the data Red Hat publishes in [digital-roadmap-backend](https://github.com/RedHatInsights/digital-roadmap-backend). | -- |
 | **shell.py** | Runs external commands from an argv list without a shell, guards option-style CLI values, and locates executables in `PATH`. | `safe_cli_value()`, `shell_exec()`, `which()` |
+| **user.py** | Local Unix accounts: UID/GID names, the system/regular account boundary, interactive shells and the state of the shadow password. | `get_gid_name()`, `get_interactive_shells()`, `get_shadow_password()`, `get_uid_min()`, `get_uid_name()`, `password_state()` |
 
 
 ### Networking & HTTP
@@ -134,6 +144,7 @@ These libraries are built with a clear set of priorities:
 | **librenms.py** | [LibreNMS](https://www.librenms.org/) monitoring API, mapping its alert states to Nagios states. | `get_data()`, `get_state()` |
 | **nextcloud.py** | [Nextcloud](https://nextcloud.com/) `occ` command execution as the `config.php` owner, parsing JSON or text output. | `run_occ()` |
 | **nodebb.py** | [NodeBB](https://nodebb.org/) forum API, using a Bearer user token. | `get_data()` |
+| **openstack.py** | [OpenStack](https://www.openstack.org/) Identity v3 authentication from an rc file, with the token reused across runs, and access to the service REST APIs. | `connect()`, `fetch()`, `fetch_json()` |
 | **qts.py** | QNAP [QTS](https://www.qnap.com/) NAS API with session authentication. | `get_auth_sid()` |
 | **redfish.py** | [Redfish](https://www.dmtf.org/standards/redfish) BMC API for chassis, systems, storage, managers, and sensors, deriving Nagios states and perfdata. | `get_auth_header()`, `get_perfdata()`, `get_state()`, `get_systems()` |
 | **rocket.py** | [Rocket.Chat](https://www.rocket.chat/) REST API for login, room/group history, statistics, and incoming webhooks. | `get_groups_history()`, `get_rooms_get()`, `get_stats()`, `get_token()`, `send2webhook()` |
@@ -145,21 +156,31 @@ These libraries are built with a clear set of priorities:
 
 ## Usage Example
 
-A typical monitoring plugin using these libraries:
+A typical check-style tool using these libraries:
 
 ```python
+import argparse
+
 import lib.args
 import lib.base
 import lib.url
-from lib.globals import STATE_CRIT, STATE_OK, STATE_UNKNOWN, STATE_WARN
 
 
 def main():
-    # Parse arguments with custom threshold types
-    parser = lib.args.ArgumentParser()
-    parser.add_argument('--url', required=True)
-    parser.add_argument('--warning', type=lib.args.float_or_none, default=80)
-    parser.add_argument('--critical', type=lib.args.float_or_none, default=90)
+    parser = argparse.ArgumentParser(description='Checks the usage reported by an API.')
+    parser.add_argument('--url', required=True, help=lib.args.help('--url'))
+    parser.add_argument(
+        '--warning',
+        type=float,
+        default=80,
+        help=lib.args.help('--warning') + ' Default: %(default)s',
+    )
+    parser.add_argument(
+        '--critical',
+        type=float,
+        default=90,
+        help=lib.args.help('--critical') + ' Default: %(default)s',
+    )
     args = parser.parse_args()
 
     # Fetch data (coe = "Continue or Exit")
@@ -172,7 +193,7 @@ def main():
     )
 
     # Output and exit
-    lib.base.oao('Usage is {}%'.format(result['usage']), state, perfdata)
+    lib.base.oao(f'Usage is {result["usage"]}%', state, perfdata)
 
 
 if __name__ == '__main__':

{linuxfabrik_lib-8.2.0 → linuxfabrik_lib-8.3.0}/args.py

@@ -13,12 +13,13 @@
 import argparse
 import os
 import re
+import sys
 import textwrap
 
-from . import base, disk, human
+from . import base, human, txt
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026092101'
+__version__ = '2026102401'
 
 # Base URL of the rendered online documentation.
 DOCS_BASE_URL = 'https://linuxfabrik.github.io/monitoring-plugins'
@@ -289,8 +290,7 @@ HELP_TEXTS = {
         'Send a short message. This can be useful when using an SMS relay, for example.'
     ),
     '--stratum': (
-        'Warns if the determined stratum of the time server is greater than or equal '
-        'to this value. '
+        'Warns if the stratum of this host is greater than or equal to this value. '
         'Stratum 1 indicates a computer with a locally attached reference clock. '
         'A computer that is synchronised to a stratum 1 computer is at stratum 2. '
         'A computer that is synchronised to a stratum 2 computer is at stratum 3, '
@@ -325,14 +325,23 @@ HELP_TEXTS = {
     '--warning-seconds': 'WARN threshold in seconds.',
     '--warning-temperature': 'WARN threshold in degrees Celsius.',
     '--warning-voltage': 'WARN threshold in volts.',
+    '--winrm-domain': (
+        'AD domain name for NTLM authentication. '
+        'When set, the username is sent as user@DOMAIN. '
+        'Not needed for Kerberos or local accounts.'
+    ),
+    '--winrm-password': (
+        'WinRM account password. '
+        'Optional for Kerberos (uses the credential cache from kinit).'
+    ),
+    '--winrm-transport': 'WinRM transport type.',
+    '--winrm-username': (
+        'WinRM account name. '
+        'Optional for Kerberos (uses the credential cache from kinit).'
+    ),
 }
 
 
-# Predefined sets for checking units and methods
-_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.
 
@@ -568,6 +577,11 @@ def load_secret(path, param='--password-file'):
     >>> load_secret('/etc/icinga2/secrets/storage')
     'linuxfabrik'
     """
+    # Imported here, not at module level: this is the only consumer of lib.disk in this
+    # module, and loading it (with lib.shell and subprocess behind it) would slow down
+    # the startup of everything that only wants the argparse helpers.
+    from . import disk
+
     success, content = disk.read_file(path)
     if not success:
         base.cu(f'Cannot read the file given in {param}: {content}')
@@ -578,13 +592,27 @@ def load_secret(path, param='--password-file'):
     return secret
 
 
+# `<number>[unit][method]`, blanks allowed between the parts. A unit may carry a
+# trailing `B` or `iB` (`10GiB`, `10MB`): the unit is binary either way, and these
+# were always accepted. The blanks after the unit belong to the unit's group: two
+# `\s*` in a row with only an optional group between them split a run of blanks in
+# quadratically many ways, and a threshold of `1`, 30000 blanks and `x` took 21 s to
+# refuse (Python 3.14).
+_NUMBER_UNIT_METHOD = re.compile(
+    r'(?P<number>\d+(?:\.\d+)?|\.\d+)\s*'
+    r'(?:(?P<unit>[%KMGTP])(?:I?B)?\s*)?'
+    r'(?P<method>USED|FREE)?',
+    re.IGNORECASE,
+)
+
+
 def number_unit_method(arg, unit='%', method='USED'):
     """Parses a string in the format `<number>[unit][method]` for threshold arguments.
 
     Parameters
     ----------
     arg : str
-        The input string.
+        The input string. Blanks between number, unit and method are allowed.
     unit : str, optional
         Default unit. Defaults to `%`.
     method : str, optional
@@ -593,9 +621,10 @@ def number_unit_method(arg, unit='%', method='USED'):
     Returns
     -------
     tuple (str, str, str)
-        The number as it was written, the unit and the method, both upper case.
-        An argument carrying no digits yields `('0.0', unit, method)`, and a unit
-        or method the parser does not know falls back to the default.
+        The number as it was written, the unit and the method, both upper case. An
+        argument that does not have this form, a negative number or `5.5.5G` among
+        them, yields an empty number, so that the caller's `float()` rejects it
+        instead of working with a threshold nobody gave.
 
     Examples
     --------
@@ -604,32 +633,120 @@ def number_unit_method(arg, unit='%', method='USED'):
 
     >>> number_unit_method('9.5GFREE')
     ('9.5', 'G', 'FREE')
+
+    >>> number_unit_method('10 G')
+    ('10', 'G', 'USED')
+
+    >>> number_unit_method('-5')
+    ('', '%', 'USED')
     """
     arg = arg.strip()
-    number_part = []
-    unit_part = ''
-    method_part = ''
-
-    i = 0
-    while i < len(arg) and (arg[i].isdigit() or arg[i] == '.'):
-        number_part.append(arg[i])
-        i += 1
+    match = _NUMBER_UNIT_METHOD.fullmatch(arg)
+    if not match:
+        return '', unit.upper(), method.upper()
+    return (
+        match.group('number'),
+        (match.group('unit') or unit).upper(),
+        (match.group('method') or method).upper(),
+    )
 
-    if i < len(arg) and arg[i].upper() in _UNITS:
-        unit_part = arg[i]
-        i += 1
 
-    if i < len(arg):
-        method_part = arg[i:].upper()
+def _repair_ansi_argument(arg, codec):
+    """
+    Undo the damage the ANSI process API does to a UTF-8 argument on Windows.
+
+    A program that starts another one through `CreateProcessA` hands it a byte string,
+    and Windows turns every byte of it into a character of the ANSI code page. When
+    those bytes were UTF-8, a "ü" (`C3 BC`) arrives as "ü". Encoding the argument
+    back into the code page recovers the original bytes. Windows maps a byte the code
+    page leaves undefined (`0x81`, `0x8D`, `0x8F`, `0x90`, `0x9D` in cp1252) to the code
+    point of the same value, which Python's codec does not know, so those are taken
+    over one to one.
+
+    The repair only applies when the recovered bytes are valid UTF-8. An argument that
+    arrived intact does not qualify: "Prüfung" becomes `50 72 FC ...` in cp1252, which
+    is not UTF-8, and characters outside the code page ("ő", "日本") cannot be encoded
+    at all. What remains ambiguous is text that already looks like mojibake: a literal
+    "ü" is indistinguishable from a damaged "ü" and is read as the latter.
+
+    The repair never produces a character below U+0080 that was not there before: only
+    characters that encode to a single byte are taken back, ASCII bytes map to
+    themselves, and a strict UTF-8 decoder turns bytes from `0x80` up into characters
+    from U+0080 up only, overlong encodings of ASCII included. So it cannot
+    introduce a `-`, a `/`, a quote or a `..` into an argument.
 
-    number = ''.join(number_part)
-    if not number:
-        return '0.0', unit.upper(), method.upper()
+    Parameters
+    ----------
+    arg : str
+        One command-line argument.
+    codec : str
+        The Python codec of the ANSI code page, for example `'cp1252'`.
 
-    if unit_part:
-        unit = unit_part
+    Returns
+    -------
+    str
+        The repaired argument, or `arg` unchanged.
 
-    if method_part in _METHODS:
-        method = method_part
+    Examples
+    --------
+    >>> _repair_ansi_argument('Pr\u00c3\u00bcfung', 'cp1252')
+    'Prüfung'
 
-    return number, unit.upper(), method.upper()
+    >>> _repair_ansi_argument('Prüfung', 'cp1252')
+    'Prüfung'
+    """
+    raw = bytearray()
+    for char in arg:
+        try:
+            encoded = txt.to_bytes(char, encoding=codec, errors='strict')
+        except UnicodeEncodeError:
+            if ord(char) > 0xFF:
+                return arg
+            encoded = bytes([ord(char)])
+        # The damage maps one byte to one character. A character that takes two
+        # bytes (the double-byte code pages 932, 936, 949 and 950) was not produced
+        # by it, and its trail byte can be ASCII: cp932 encodes "―" as `81 5C`.
+        if len(encoded) != 1:
+            return arg
+        raw += encoded
+    try:
+        return txt.to_text(bytes(raw), encoding='utf-8', errors='strict')
+    except UnicodeDecodeError:
+        return arg
+
+
+def _repair_windows_argv():
+    """
+    Repair the command-line arguments the Icinga 2 agent for Windows hands over.
+
+    The agent keeps its strings in UTF-8 and starts a check through `CreateProcessA`
+    (`Process::Run()` in lib/base/process.cpp), so every argument with a character
+    outside of ASCII arrives in the ANSI code page: "Prüfung" as "Prüfung"
+    (Icinga/icinga2#8962). A caller that passes the arguments intact, such as a shell,
+    NSClient++ or any other program using the Unicode API, is left alone, see
+    `_repair_ansi_argument()`. Verified with Icinga 2 v2.16.5 on Windows Server 2025,
+    ANSI code page 1252.
+
+    Icinga for Windows repairs its plugins the same way, back to the ANSI bytes and on
+    to UTF-8 (`ConvertTo-IcingaUTF8Value` in icinga-powershell-framework), but skips only
+    values that contain a German umlaut. Measured on the same host, that turns an intact
+    "café" into "caf�", "ő" into "o" and "€" into "�". Requiring the result
+    to be valid UTF-8 repairs the same damaged values and leaves every intact one alone.
+    """
+    try:
+        import ctypes  # Windows-only API below
+
+        codec = f'cp{ctypes.windll.kernel32.GetACP()}'
+        txt.to_bytes('', encoding=codec, errors='strict')
+    except (AttributeError, LookupError, OSError):
+        return
+    sys.argv[:] = [_repair_ansi_argument(arg, codec) for arg in sys.argv]
+
+
+# Done on import, before any consumer parses its arguments, for the same reason
+# `base.py` reconfigures stdout on import: it covers every consumer without each of them
+# having to ask for it. It touches nothing but arguments that decode as the damage the
+# ANSI API does, so on Linux, with an intact caller or with plain ASCII it changes
+# nothing.
+if base.WINDOWS:
+    _repair_windows_argv()