Merge pull request #33 from epics-extensions/phoebus-save-and-restore…

…-nixos-module

Phoebus Save-and-restore NixOS module

doc/_quarto.yml

@@ -76,6 +76,7 @@ website:
           contents:
             - ./nixos/guides/ca-gateway.md
             - ./nixos/guides/phoebus-alarm.md
+            - ./nixos/guides/phoebus-save-and-restore.md
         - section: Explanations
         - section: References
           contents:

doc/nixos/guides/phoebus-save-and-restore.md

@@ -0,0 +1,50 @@
+---
+title: Phoebus Save-and-restore setup
+---
+
+The Phoebus Save-and-restore service is used by clients
+to manage configuration and snapshots of PV values.
+These snapshots can then be used by clients for comparison or for restoring PVs.
+
+This guide focuses on installing and configuring the Save-and-Restore service on a single server.
+
+For more details and documentation about Phoebus Save-and-Restore,
+you can examine the [Save-and-restore official documentation].
+
+  [Save-and-restore official documentation]: https://control-system-studio.readthedocs.io/en/latest/services/save-and-restore/doc/index.html
+
+{{< include _pre-requisites.md >}}
+
+# Enabling the Phoebus Save-and-restore service
+
+To enable the Phoebus Save-and-restore service,
+add this to your configuration:
+
+``` nix
+{lib, ...}: {
+  services.phoebus-save-and-restore = {
+    enable = true;
+    openFirewall = true;
+  };
+
+  # Elasticsearch, needed by Phoebus Save-and-restore, is not free software (SSPL | Elastic License).
+  # To accept the license, add the code below:
+  nixpkgs.config.allowUnfreePredicate = pkg:
+    builtins.elem (lib.getName pkg) [
+      "elasticsearch"
+    ];
+}
+```
+
+From the Phoebus graphical client side,
+add this configuration
+
+``` ini
+# Replace the IP address with your server's IP address or domain name
+org.phoebus.applications.saveandrestore/jmasar.service.url=http://192.168.1.42:8080
+```
+
+::: callout-warning
+URLs for future versions of Phoebus Save-and-restore will need to change to:
+`http://192.168.1.42:8080/save-restore`
+:::

nixos/module-list.nix

@@ -5,4 +5,5 @@
   ./modules/phoebus/alarm-server.nix
   ./modules/phoebus/local-kafka.nix
   ./modules/phoebus/olog.nix
+  ./modules/phoebus/save-and-restore.nix
 ]

nixos/modules/phoebus/alarm-logger.nix

@@ -173,7 +173,7 @@ in {
 
     services.elasticsearch = lib.mkIf localElasticsearch {
       enable = true;
-      # Should be kept in sync with the phoebus-olog service
+      # Should be kept in sync with the phoebus-olog and phoebus-save-and-restore services
       package = pkgs.elasticsearch7;
     };
 

nixos/modules/phoebus/olog.nix

@@ -116,7 +116,7 @@ in {
 
     services.elasticsearch = {
       enable = true;
-      # Should be kept in sync with the phoebus-alarm-logger service
+      # Should be kept in sync with the phoebus-alarm-logger and phoebus-save-and-restore services
       package = pkgs.elasticsearch7;
     };
     services.mongodb.enable = true;

nixos/modules/phoebus/save-and-restore.nix

@@ -0,0 +1,155 @@
+{
+  config,
+  epnixLib,
+  lib,
+  pkgs,
+  ...
+}: let
+  cfg = config.services.phoebus-save-and-restore;
+  settingsFormat = pkgs.formats.javaProperties {};
+  configFile = settingsFormat.generate "phoebus-save-and-restore.properties" cfg.settings;
+
+  localElasticsearch = cfg.settings."elasticsearch.network.host" == "localhost";
+in {
+  options.services.phoebus-save-and-restore = {
+    enable = lib.mkEnableOption ''
+      the Phoebus Save-and-restore service.
+
+      This service is used by clients
+      to manage configurations (aka save sets) and snapshots,
+      to compare snapshots,
+      and to restore PV values from snapshots.
+    '';
+
+    openFirewall = lib.mkOption {
+      description = ''
+        Open the firewall for the Phoebus Save-and-restore service.
+
+        Warning: this opens the firewall on all network interfaces.
+      '';
+      type = lib.types.bool;
+      default = false;
+    };
+
+    settings = lib.mkOption {
+      description = ''
+        Configuration for the Phoebus Save-and-restore service.
+
+        These options will be put into a `.properties` file.
+
+        Note that options containing a "." must be quoted.
+
+        Available options can be seen here:
+        <https://github.com/ControlSystemStudio/phoebus/blob/master/services/save-and-restore/src/main/resources/application.properties>
+      '';
+      default = {};
+      type = lib.types.submodule {
+        freeformType = settingsFormat.type;
+        options = {
+          "server.port" = lib.mkOption {
+            description = "Port for the Save-and-restore service";
+            type = lib.types.port;
+            default = 8080;
+            apply = toString;
+          };
+
+          "elasticsearch.network.host" = lib.mkOption {
+            description = ''
+              Elasticsearch server host
+
+              If `localhost` (the default),
+              the Elasticsearch service will be automatically set up.
+            '';
+            type = lib.types.str;
+            default = "localhost";
+          };
+
+          "elasticsearch.http.port" = lib.mkOption {
+            description = "Elasticsearch server port";
+            type = lib.types.port;
+            default = config.services.elasticsearch.port;
+            defaultText = lib.literalExpression "config.services.elasticsearch.port";
+            apply = toString;
+          };
+        };
+      };
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    systemd.services.phoebus-save-and-restore = {
+      description = "Phoebus Save-and-restore";
+
+      wantedBy = ["multi-user.target"];
+      after = lib.mkIf localElasticsearch ["elasticsearch.service"];
+
+      serviceConfig = {
+        ExecStart = "${pkgs.epnix.phoebus-save-and-restore}/bin/phoebus-save-and-restore --spring.config.location=file://${configFile}";
+        Restart = "on-failure";
+        DynamicUser = true;
+
+        # Security options:
+        # ---
+
+        # NETLINK needed to enumerate available interfaces
+        RestrictAddressFamilies = ["AF_INET" "AF_INET6"];
+        # Service may not create new namespaces
+        RestrictNamespaces = true;
+
+        # Service does not have access to other users
+        PrivateUsers = true;
+        # Service has no access to hardware devices
+        PrivateDevices = true;
+
+        # Service cannot write to the hardware clock or system clock
+        ProtectClock = true;
+        # Service cannot modify the control group file system
+        ProtectControlGroups = true;
+        # Service has no access to home directories
+        ProtectHome = true;
+        # Service cannot change system host/domainname
+        ProtectHostname = true;
+        # Service cannot read from or write to the kernel log ring buffer
+        ProtectKernelLogs = true;
+        # Service cannot load or read kernel modules
+        ProtectKernelModules = true;
+        # Service cannot alter kernel tunables (/proc/sys, …)
+        ProtectKernelTunables = true;
+        # Service has restricted access to process tree (/proc hidepid=)
+        ProtectProc = "invisible";
+
+        # Service may not acquire new capabilities
+        CapabilityBoundingSet = "";
+        # Service cannot change ABI personality
+        LockPersonality = true;
+        # Service has no access to non-process /proc files (/proc subset=)
+        ProcSubset = "pid";
+        # Service may execute system calls only with native ABI
+        SystemCallArchitectures = "native";
+        # Access write directories
+        UMask = "0077";
+        # Service may create writable executable memory mappings
+        # This option isn't set due to the JVM marking some memory pages as executable
+        #MemoryDenyWriteExecute = true;
+
+        # Service can only use a reasonable set of system calls,
+        # used by common system services
+        SystemCallFilter = ["@system-service"];
+        # Disallowed system calls return EPERM instead of terminating the service
+        SystemCallErrorNumber = "EPERM";
+      };
+    };
+
+    services.elasticsearch = lib.mkIf localElasticsearch {
+      enable = true;
+      # Should be kept in sync with the phoebus-alarm-logger and phoebus-olog services
+      package = pkgs.elasticsearch7;
+    };
+
+    networking.firewall.allowedTCPPorts = lib.mkIf cfg.openFirewall [
+      (lib.toInt cfg.settings."server.port")
+    ];
+  };
+
+  meta.maintainers = with epnixLib.maintainers; [minijackson];
+}

nixos/tests/all-tests.nix

@@ -19,4 +19,5 @@ in {
   ca-gateway = handleTest ./ca-gateway.nix {};
   phoebus-alarm = handleTest ./phoebus/alarm.nix {};
   phoebus-olog = handleTest ./phoebus/olog.nix {};
+  phoebus-save-and-restore = handleTest ./phoebus/save-and-restore.nix {};
 }

nixos/tests/phoebus/save-and-restore.nix

@@ -0,0 +1,32 @@
+{
+  lib,
+  epnixLib,
+  ...
+}: {
+  name = "phoebus-save-and-restore-simple-check";
+  meta.maintainers = with epnixLib.maintainers; [minijackson];
+
+  nodes = {
+    server = {
+      services.phoebus-save-and-restore = {
+        enable = true;
+        openFirewall = true;
+      };
+
+      nixpkgs.config.allowUnfreePredicate = pkg:
+        builtins.elem (lib.getName pkg) [
+          # Elasticsearch can be used as an SSPL-licensed software, which is
+          # not open-source. But as we're using it run tests, not exposing
+          # any service, this should be fine.
+          "elasticsearch"
+        ];
+
+      # Else OOM
+      virtualisation.memorySize = 2047;
+    };
+
+    client = {};
+  };
+
+  testScript = builtins.readFile ./save-and-restore.py;
+}