From fdaf68b8b57e26b3afb11e87ad6ca34ec6ada82e Mon Sep 17 00:00:00 2001 From: Alex Tau Date: Sat, 10 May 2025 16:14:44 +0300 Subject: [PATCH] autogenerated docs --- docs/nixos-options.md | 368 ++++++++++++++++++ flake.nix | 5 +- mkdocs.nix | 15 + modules/default.nix | 79 +--- modules/options.nix | 81 ++++ .../tempSensorOptions.nix | 0 .../vulnixWhitelistRule.nix | 0 7 files changed, 472 insertions(+), 76 deletions(-) create mode 100644 docs/nixos-options.md create mode 100644 mkdocs.nix create mode 100644 modules/options.nix rename modules/{submodules => suboptions}/tempSensorOptions.nix (100%) rename modules/{submodules => suboptions}/vulnixWhitelistRule.nix (100%) diff --git a/docs/nixos-options.md b/docs/nixos-options.md new file mode 100644 index 0000000..8c53dc7 --- /dev/null +++ b/docs/nixos-options.md @@ -0,0 +1,368 @@ +## services\.lego-monitoring\.enable + + + +Whether to enable lego-monitoring service… + + + +*Type:* +boolean + + + +*Default:* +` false ` + + + +*Example:* +` true ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.enabledCheckSets + + + +List of enabled check sets\. Each check set is a module which checks something and generates alerts based on check results\. + + + +*Type:* +list of (one of “start”, “stop”, “temp”, “vulnix”) + + + +*Default:* +` [ ] ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors + +Temp sensor override definitions\. Sensors not defined here, or missing options in definitions, will be read with default parameters\. + +To get list of sensors and their default configurations, run ` lego-monitoring --print-temp `\. + + + +*Type:* +attribute set of (submodule) + + + +*Default:* +` { } ` + + + +*Example:* + +``` +{ + amdgpu.readings.edge.label = "Integrated GPU"; + k10temp.readings = { + Tctl = { + label = "AMD CPU"; + criticalTemp = 95.0; + }; + Tccd1.enabled = false; + Tccd2.enabled = false; + }; + nvme.readings = { + "Sensor 1".enabled = false; + "Sensor 2".enabled = false; + }; +} +``` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors\.\\.enabled + + + +Whether sensor is enabled\. + + + +*Type:* +boolean + + + +*Default:* +` true ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors\.\\.name + + + +Friendly name of the sensor\. + + + +*Type:* +null or string + + + +*Default:* +` null ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors\.\\.readings + + + +Overrides for specific readings of the sensor, by label\. + + + +*Type:* +attribute set of (submodule) + + + +*Default:* +` { } ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors\.\\.readings\.\\.enabled + + + +Whether this reading is enabled\. + + + +*Type:* +boolean + + + +*Default:* +` true ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors\.\\.readings\.\\.criticalTemp + + + +Critical temperature threshold\. + + + +*Type:* +null or floating point number + + + +*Default:* +` null ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors\.\\.readings\.\\.label + + + +Friendly label of the reading\. + + + +*Type:* +null or string + + + +*Default:* +` null ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.temp\.sensors\.\\.readings\.\\.warningTemp + + + +Warning temperature threshold\. + + + +*Type:* +null or floating point number + + + +*Default:* +` null ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.vulnix\.whitelist + + + +Whitelist rules for vulnix\. Attr name is package with version, package name, or ` * `\. + + + +*Type:* +attribute set of (submodule) + + + +*Default:* +` { } ` + + + +*Example:* + +``` +{ + "ffmpeg-3.4.2" = { + cve = [ "CVE-2018-6912" "CVE-2018-7557" ]; + until = "2018-05-01"; + issueUrl = "https://issues.example.com/29952"; + }; +} +``` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.vulnix\.whitelist\.\\.cve + + + +List of CVE identifiers to match\. The whitelist rule is valid as long as the detected CVEs are a subset of the CVEs listed here\. +If additional CVEs are detected, this whitelist rule is not effective anymore\. If null, all CVEs are matched\. + + + +*Type:* +null or (list of string) + + + +*Default:* +` null ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.vulnix\.whitelist\.\\.issueUrl + + + +URL or list of URLs that point to any issue tracker\. Informational only\. + + + +*Type:* +null or string + + + +*Default:* +` null ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.checks\.vulnix\.whitelist\.\\.until + + + +Date in the form “YYYY-MM-DD” which confines this rule’s lifetime\. Null means forever\. +On the specified date and later, this whitelist rule is not effective anymore\. + + + +*Type:* +null or string + + + +*Default:* +` null ` + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.telegram\.credsSecretPath + + + +Path to a file containing Telegram api_id, api_hash, and bot token, separated by the ` , ` character\. + + + +*Type:* +string + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + + +## services\.lego-monitoring\.telegram\.roomId + + + +ID of chat where to send alerts\. + + + +*Type:* +signed integer + +*Declared by:* + - [/nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options\.nix](file:///nix/store/32aaw5svwp38dh1wqby10d9bx0vjvv33-source/modules/options.nix) + + diff --git a/flake.nix b/flake.nix index 1d9ea40..6bced14 100644 --- a/flake.nix +++ b/flake.nix @@ -103,7 +103,10 @@ # Package a virtual environment as our main application. # # Enable no optional dependencies for production build. - packages.x86_64-linux.default = pythonSet.mkVirtualEnv "lego-monitoring-env" workspace.deps.default; + packages.x86_64-linux = { + default = pythonSet.mkVirtualEnv "lego-monitoring-env" workspace.deps.default; + docs = pkgs.callPackage ./mkdocs.nix {}; + }; # Make service runnable with `nix run` apps.x86_64-linux = { diff --git a/mkdocs.nix b/mkdocs.nix new file mode 100644 index 0000000..6a38c55 --- /dev/null +++ b/mkdocs.nix @@ -0,0 +1,15 @@ +{ + lib, + pkgs, + ... +}: + +let + optEval = lib.evalModules { modules = [ + ./modules/options.nix + ]; }; + optionsDoc = pkgs.nixosOptionsDoc { + options = builtins.removeAttrs optEval.options [ "_module" ]; + }; +in + pkgs.runCommand "options-doc.md" {} "cat ${optionsDoc.optionsCommonMark} >> $out" diff --git a/modules/default.nix b/modules/default.nix index 5c34d7f..d48361c 100644 --- a/modules/default.nix +++ b/modules/default.nix @@ -7,82 +7,11 @@ package: ... }: -let - tempSensorOptions = (import ./submodules/tempSensorOptions.nix) { inherit lib; }; - vulnixWhitelistRule = (import ./submodules/vulnixWhitelistRule.nix) { inherit lib; }; -in { - options.services.lego-monitoring = { - enable = lib.mkEnableOption "lego-monitoring service."; - - enabledCheckSets = lib.mkOption { - type = lib.types.listOf (lib.types.enum [ - "start" - "stop" - "temp" - "vulnix" - ]); - default = [ ]; - description = "List of enabled check sets. Each check set is a module which checks something and generates alerts based on check results."; - }; - - telegram = { - credsSecretPath = lib.mkOption { - type = lib.types.str; - description = "Path to a file containing Telegram api_id, api_hash, and bot token, separated by the `,` character."; - }; - roomId = lib.mkOption { - type = lib.types.int; - description = "ID of chat where to send alerts."; - }; - }; - - checks = { - temp = { - sensors = lib.mkOption { - type = lib.types.attrsOf (lib.types.submodule tempSensorOptions); - default = { }; - description = '' - Temp sensor override definitions. Sensors not defined here, or missing options in definitions, will be read with default parameters. - - To get list of sensors and their default configurations, run `lego-monitoring --print-temp`.''; - example = lib.literalExpression '' - { - amdgpu.readings.edge.label = "Integrated GPU"; - k10temp.readings = { - Tctl = { - label = "AMD CPU"; - criticalTemp = 95.0; - }; - Tccd1.enabled = false; - Tccd2.enabled = false; - }; - nvme.readings = { - "Sensor 1".enabled = false; - "Sensor 2".enabled = false; - }; - } - ''; - }; - }; - - vulnix = { - whitelist = lib.mkOption { - type = lib.types.attrsOf (lib.types.submodule vulnixWhitelistRule); - default = { }; - description = "Whitelist rules for vulnix. Attr name is package with version, package name, or `*`."; - example = lib.literalExpression ''{ - "ffmpeg-3.4.2" = { - cve = [ "CVE-2018-6912" "CVE-2018-7557" ]; - until = "2018-05-01"; - issueUrl = "https://issues.example.com/29952"; - }; - }''; - }; - }; - }; - }; - + imports = [ + ./options.nix + ]; + config = let cfg = config.services.lego-monitoring; json = pkgs.formats.json {}; diff --git a/modules/options.nix b/modules/options.nix new file mode 100644 index 0000000..c692366 --- /dev/null +++ b/modules/options.nix @@ -0,0 +1,81 @@ +{ + lib, + ... +}: + +let + tempSensorOptions = (import ./suboptions/tempSensorOptions.nix) { inherit lib; }; + vulnixWhitelistRule = (import ./suboptions/vulnixWhitelistRule.nix) { inherit lib; }; +in +{ + options.services.lego-monitoring = { + enable = lib.mkEnableOption "lego-monitoring service."; + + enabledCheckSets = lib.mkOption { + type = lib.types.listOf (lib.types.enum [ + "start" + "stop" + "temp" + "vulnix" + ]); + default = [ ]; + description = "List of enabled check sets. Each check set is a module which checks something and generates alerts based on check results."; + }; + + telegram = { + credsSecretPath = lib.mkOption { + type = lib.types.str; + description = "Path to a file containing Telegram api_id, api_hash, and bot token, separated by the `,` character."; + }; + roomId = lib.mkOption { + type = lib.types.int; + description = "ID of chat where to send alerts."; + }; + }; + + checks = { + temp = { + sensors = lib.mkOption { + type = lib.types.attrsOf (lib.types.submodule tempSensorOptions); + default = { }; + description = '' + Temp sensor override definitions. Sensors not defined here, or missing options in definitions, will be read with default parameters. + + To get list of sensors and their default configurations, run `lego-monitoring --print-temp`.''; + example = lib.literalExpression '' + { + amdgpu.readings.edge.label = "Integrated GPU"; + k10temp.readings = { + Tctl = { + label = "AMD CPU"; + criticalTemp = 95.0; + }; + Tccd1.enabled = false; + Tccd2.enabled = false; + }; + nvme.readings = { + "Sensor 1".enabled = false; + "Sensor 2".enabled = false; + }; + }''; + }; + }; + + vulnix = { + whitelist = lib.mkOption { + type = lib.types.attrsOf (lib.types.submodule vulnixWhitelistRule); + default = { }; + description = "Whitelist rules for vulnix. Attr name is package with version, package name, or `*`."; + example = lib.literalExpression '' + { + "ffmpeg-3.4.2" = { + cve = [ "CVE-2018-6912" "CVE-2018-7557" ]; + until = "2018-05-01"; + issueUrl = "https://issues.example.com/29952"; + }; + }''; + }; + }; + }; + }; +} diff --git a/modules/submodules/tempSensorOptions.nix b/modules/suboptions/tempSensorOptions.nix similarity index 100% rename from modules/submodules/tempSensorOptions.nix rename to modules/suboptions/tempSensorOptions.nix diff --git a/modules/submodules/vulnixWhitelistRule.nix b/modules/suboptions/vulnixWhitelistRule.nix similarity index 100% rename from modules/submodules/vulnixWhitelistRule.nix rename to modules/suboptions/vulnixWhitelistRule.nix