packages2install add docs

docs/20_Checks/_index.md

@@ -31,7 +31,7 @@ There is one include script used by all checks:
 * [check_onehost](check_onehost.md)
 * [check_onevm](check_onevm.md)
 * [check_opencpu](check_opencpu.md)
-* check_packages2install
+* [check_packages2install](check_packages2install)
 * check_php-fpm-status
 * check_proc_mem
 * check_proc_ressources

docs/20_Checks/check_packages2install.md

+# check_packages2install
+
+## Introduction
+
+Check available package updates.
+Found updates will be shown in groups.
+
+### Requirements
+
+* none
+
+## Syntax
+
+```text
+> ./check_packages2install -h
+______________________________________________________________________
+
+CHECK_PACKAGES2INSTALL
+v1.12
+
+(c) Institute for Medical Education - University of Bern
+Licence: GNU GPL 3
+
+https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_packages2install.html
+______________________________________________________________________
+
+Get packages that must be updated on this system and show found 
+packages in groups.
+
+RELATED FILES:
+1) For groups and their search filters see files in subdir 
+   check_packages2install-data.
+2) In the subdir check_packages2install-pkgmanager are scripts
+   for supported package managers (with aded ".sh").
+
+OUTPUT:
+It returns UNKNOWN if package manager is not supported.
+
+It returns OK if the system is up to date.
+It returns WARNING or ERROR if count of found pakackes is greater than
+given warn level.
+
+On CentOS it switches to ERROR if a critcal update was found.
+
+Tested operating systems:
+- Centos
+- Debian
+- Manjaro
+- Ubuntu
+
+SYNTAX:
+check_packages2install [options]
+
+OPTIONS:
+
+    -w   custom warning level; default: 1
+    -c   custom critical level; default: 200
+
+PARAMETERS:
+
+    -h   show this help
+
+```
+
+## Additional files
+
+### Package manager support
+
+In the subfolder `check_packages2install-pkgmanager/` are scripts to read and parse data of different package managers.
+
+* apt.sh - for Debian like systems
+* pamac.sh - for Arch linux like systems
+* yum.sh - for RedHat like systems
+
+Each file MUST contain minumum the functions
+
+* [packager].getUpdates() - command to list updates
+* [packager].getPackageList() - extract list of packages 2 install
+
+These functions are optional:
+
+* [packager].getStatusLine - get custom status line (1st line in output)
+* [packager].getCriticalList - extract count of critical packages
+
+### Define groups
+
+To group the packages there are file in subfolder `check_packages2install-data/`:
+
+```txt
+check_packages2install-data
+├── 01_OS_base.txt
+├── 02_System.txt
+├── 10_Programming_languages.txt
+├── 10_Webservices.txt
+├── 20_Database.txt
+└── 50_Custom.txt
+```
+
+The filenames here are the groups. The prefix of number is used to define a sortorder. The number and underscore will be removed in the output.
+
+### Define packages per group
+
+The files are simple text files. The rules:
+
+* Each file contains a list of search strings starting in the 1st column.
+* Only entrys starting with a letter `[a-zA-Z]` will be used - you can add empty lines or use comments eg. by using a starting `#` character.
+* the search string will be applied starting with the 1st character of the package (like `grep -E "^(line1|line2)"``)
+
+```txt
+$ cat check_packages2install-data/01_OS_base.txt 
+basesystem
+centos
+kernel
+linux
+ubuntu                                                          
+
+$ cat check_packages2install-data/10_Programming_languages.txt 
+java
+python
+php
+ruby
+node
+r-
+```
+
+## Examples
+
+### Simple output
+
+On Manjaro with a single package (group not detected). Pamac has no function `pamac.getStatusLine()` - the first line in the output is the default status line.
+
+```txt
+check_packages2install
+WARNING: [pamac] 1 updates
+
+Autoupdate OFF
+
+--- All packages (No package matched a group filter):
+     1  ventoy  1.0.94-1 -> 1.0.95-1  extra
+
+Total packages to install: 1
+ |updates-available=1;1;200 
+ ```
+
+### Grouped output
+
+Here is a longer example: 
+You see the count of packages per group. Matching search strings of a group will be added in a group section.
+At the end you get the total and the performace data.
+
+```txt
+WARNING: [yum] (...)
+
+--- OS_base: 6
+     1	kernel.x86_64                        5.14.0-284.25.1.el9_2             baseos   
+     2	kernel-core.x86_64                   5.14.0-284.25.1.el9_2             baseos   
+     3	kernel-modules.x86_64                5.14.0-284.25.1.el9_2             baseos   
+     4	kernel-modules-core.x86_64           5.14.0-284.25.1.el9_2             baseos   
+     5	kernel-tools.x86_64                  5.14.0-284.25.1.el9_2             baseos   
+     6	kernel-tools-libs.x86_64             5.14.0-284.25.1.el9_2             baseos   
+
+--- System: 8
+     1	openssh.x86_64                       8.7p1-30.el9_2                    baseos   
+     2	openssh-clients.x86_64               8.7p1-30.el9_2                    baseos   
+     3	openssh-server.x86_64                8.7p1-30.el9_2                    baseos   
+     4	openssl.x86_64                       1:3.0.7-17.el9_2                  baseos   
+     5	openssl-libs.x86_64                  1:3.0.7-17.el9_2                  baseos   
+     6	sssd-client.x86_64                   2.8.2-3.el9_2.alma                baseos   
+     7	sssd-common.x86_64                   2.8.2-3.el9_2.alma                baseos   
+     8	sssd-kcm.x86_64                      2.8.2-3.el9_2.alma                baseos   
+
+--- Other packages: 35
+     1	NetworkManager.x86_64                1:1.42.2-6.el9_2                  baseos   
+     2	NetworkManager-libnm.x86_64          1:1.42.2-6.el9_2                  baseos   
+     3	NetworkManager-team.x86_64           1:1.42.2-6.el9_2                  baseos   
+     4	NetworkManager-tui.x86_64            1:1.42.2-6.el9_2                  baseos   
+     5	bind-libs.x86_64                     32:9.16.23-11.el9_2.1             appstream
+     6	bind-license.noarch                  32:9.16.23-11.el9_2.1             appstream
+     7	bind-utils.x86_64                    32:9.16.23-11.el9_2.1             appstream
+     8	curl.x86_64                          7.76.1-23.el9_2.2                 baseos   
+   ...
+    33	systemd-pam.x86_64                   252-14.el9_2.3                    baseos   
+    34	systemd-rpm-macros.noarch            252-14.el9_2.3                    baseos   
+    35	systemd-udev.x86_64                  252-14.el9_2.3                    baseos   
+
+Total packages to install: 49
+ |updates-security=0;1;1 updates-available=49;1;200
+ ```