Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Phoebus Save-and-restore NixOS module #33

Merged
merged 3 commits into from
Oct 27, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/_quarto.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
50 changes: 50 additions & 0 deletions doc/nixos/guides/phoebus-save-and-restore.md
Original file line number Diff line number Diff line change
@@ -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`
:::
1 change: 1 addition & 0 deletions nixos/module-list.nix
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,5 @@
./modules/phoebus/alarm-server.nix
./modules/phoebus/local-kafka.nix
./modules/phoebus/olog.nix
./modules/phoebus/save-and-restore.nix
]
2 changes: 1 addition & 1 deletion nixos/modules/phoebus/alarm-logger.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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;
};

Expand Down
2 changes: 1 addition & 1 deletion nixos/modules/phoebus/olog.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
155 changes: 155 additions & 0 deletions nixos/modules/phoebus/save-and-restore.nix
Original file line number Diff line number Diff line change
@@ -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;
minijackson marked this conversation as resolved.
Show resolved Hide resolved
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];
}
1 change: 1 addition & 0 deletions nixos/tests/all-tests.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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 {};
}
32 changes: 32 additions & 0 deletions nixos/tests/phoebus/save-and-restore.nix
Original file line number Diff line number Diff line change
@@ -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;
}
Loading