====== SAPControl Certificates Validity Monitoring ======
  This monitor supervises certificate expiration in SAP PSE files
  using SAPControl `OSExecute` and `sapgenpse`,
  with threshold-based alarms per surveillance line.

===== What Can Be Monitored =====

You can detect and alert on:
  * Imminent expiration of the main certificate in a PSE file (`VALIDITY` check)
  * Imminent expiration of certificates inside a PSE PK list (`MAINTAIN_PK` check), filtered by subject pattern
  * Already expired certificates (negative remaining days)

This supports proactive renewal planning and reduction of certificate-related outages.

===== Monitored Data =====

The monitor collects:
  * Certificate expiration timestamp from `sapgenpse` command output
  * Remaining validity in days (`expirationDate - now`)
  * Subject-based expiration dates when `MAINTAIN_PK` is used

===== Configuration Hints =====

  * One surveillance row targets one check definition (check type + PSE file + thresholds).
  * `Check type = VALIDITY` checks one expiration date for the target PSE.
  * `Check type = MAINTAIN_PK` checks all matching certificate subjects in the PSE PK list.
  * `Subject` supports wildcard matching and is mainly useful with `MAINTAIN_PK`.
  * If `sapgenpse path` is empty, the monitor tries to auto-detect it with `which sapgenpse`.
  * If **Detect PSE path** is enabled and a PSE file is provided without absolute path, discovery is attempted automatically.
  * Disable alarm generation for a row with `Alarm = false`.

===== Configuration =====

==== Monitoring Parameters ====

^ Parameter ^ Type ^ Required ^ Default ^ Description ^
| sapgenpse path | String | No | (auto-detected) | Absolute path (or directory) to `sapgenpse`. If empty, auto-detection is attempted. |
| Detect PSE path | Boolean | Yes | `false` | When enabled, attempts to discover `.pse` files and resolve non-absolute PSE file names. |

==== Surveillance Table ====

^ Field ^ Required ^ Default ^ Description ^
| Active | Yes | ''true''| Enables/disables this surveillance row. |
| Check type | Yes | `MAINTAIN_PK` | Certificate extraction mode: `MAINTAIN_PK` (PK list entries) or `VALIDITY` (main certificate validity). |
| PSE files | Yes | (empty) | PSE file path or file name pattern target to inspect. |
| Subject | Yes | `*` | Subject selector for certificate entries (wildcard supported), mainly used with `MAINTAIN_PK`. |
| Max expiration days | Yes | `G2W:90 W2M:30 M2C:10` | Threshold profile applied to remaining days before expiration. |
| Severity | Yes | WARNING | Alarm severity applied when threshold is breached. |
| Auto clear | Yes | `true` | Generated alarms are clearable when condition is no longer true. |
| Alarm tag | No | (empty) | Optional custom alarm tag. |
| Alarm | No | `true` | Enables/disables alarm generation for this row. |

===== Alarm Conditions =====

For each active surveillance row:
  * `VALIDITY`: alarm when remaining days for the PSE main certificate breach configured threshold
  * `MAINTAIN_PK`: alarm when remaining days for any subject matching `Subject` breach configured threshold
  * If remaining days are below `0`, certificate is considered expired

===== Generated Alarms =====

Alarm messages include PSE file and, for `MAINTAIN_PK`, certificate subject context, for example:
  * `X days to expiration for <file> (<yyyy-MM-dd>)`
  * `Certificate expired for <file> (<yyyy-MM-dd>)`
  * `X days to expiration for <subject> in <file> (<yyyy-MM-dd>)`
  * `Certificate expired for <subject> in <file> (<yyyy-MM-dd>)`

===== Example =====

^ Active ^ Check type ^ PSE files ^ Subject ^ Max expiration days ^ Severity ^ Auto clear ^ Alarm tag ^ Alarm ^
| true | `VALIDITY` | `/usr/sap/SID/DVEBMGS00/sec/SAPSSLS.pse` | `*` | `G2W:60 W2M:30 M2C:10` | 4 | true | `SAPCTL,CERT` | true |
| true | `MAINTAIN_PK` | `SAPSSLC.pse` | `CN=*.mycompany.com*` | `G2W:45 W2M:20 M2C:7` | 5 | true | `SAPCTL,PKLIST` | true |