diff --git a/doc/_quarto.yml b/doc/_quarto.yml index fb69e66a..f48ea486 100644 --- a/doc/_quarto.yml +++ b/doc/_quarto.yml @@ -73,6 +73,8 @@ website: contents: - ./nixos/tutorials/archiver-appliance.md - section: User Guides + contents: + - ./nixos/guides/phoebus-alarm.md - section: Explanations - section: References contents: diff --git a/doc/_vale/Vocab/EPNix/accept.txt b/doc/_vale/Vocab/EPNix/accept.txt index d9465938..fe05a868 100644 --- a/doc/_vale/Vocab/EPNix/accept.txt +++ b/doc/_vale/Vocab/EPNix/accept.txt @@ -1,4 +1,6 @@ and so on +alarm +Alarm Archiver Appliance colmena disnix diff --git a/doc/nixos/guides/_pre-requisites.md b/doc/nixos/guides/_pre-requisites.md new file mode 100644 index 00000000..f1b8e962 --- /dev/null +++ b/doc/nixos/guides/_pre-requisites.md @@ -0,0 +1,40 @@ +# Pre-requisites + +- Having a NixOS machine with a flake configuration. + +If you're not sure how to do this, +you can follow the [Archiver Appliance tutorial], +which is a good introduction on how to make a NixOS VM. + +If you have such a configuration, +make sure that: + +- You have the `epnix` flake input +- You have added `epnix` as an argument to your flake outputs +- You have imported EPNix' NixOS module + +For example: + +``` {.diff filename="flake.nix"} + { + # ... ++ inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05"; + + # ... + outputs = { + self, + nixpkgs, ++ epnix, + }: { + nixosConfigurations.nixos = nixpkgs.lib.nixosSystem { + modules = [ ++ epnix.nixosModules.nixos + + # ... + ]; + }; + }; + } +``` + + [Archiver Appliance tutorial]: ../tutorials/archiver-appliance.md diff --git a/doc/nixos/guides/phoebus-alarm.md b/doc/nixos/guides/phoebus-alarm.md new file mode 100644 index 00000000..07fc9423 --- /dev/null +++ b/doc/nixos/guides/phoebus-alarm.md @@ -0,0 +1,175 @@ +--- +title: Phoebus Alarm single server setup +--- + +The Phoebus Alarm collection of services enables monitoring EPICS PVs, +and report alarms in a server. +Phoebus clients can then contact this server, +to see a list of current alarms, earlier alarms, and so on. + +This guide focuses on installing and configuring these services on a single server. + +For more information about these services, +examine the official documentation: + +- [Service Architecture] +- [Alarm Server] +- [the README of Alarm Server] for reference only, don't follow this guide on NixOS +- [Alarm Logging Service] + +The Phoebus Alarm Logging Service can also be called the Phoebus Alarm Logger. + + [Service Architecture]: https://control-system-studio.readthedocs.io/en/latest/services_architecture.html + [Alarm Server]: https://control-system-studio.readthedocs.io/en/latest/services/alarm-server/doc/index.html + [the README of Alarm Server]: https://github.com/ControlSystemStudio/phoebus/blob/master/app/alarm/Readme.md + [Alarm Logging Service]: https://control-system-studio.readthedocs.io/en/latest/services/alarm-logger/doc/index.html + +{{< include _pre-requisites.md >}} + +# Enabling the Phoebus Alarm services + +To enable the Phoebus Alarm server and the Phoebus Alarm Logger, +add this to your configuration: + +``` nix +{config, lib, ...}: let + kafkaPort = toString config.services.apache-kafka.port; + # Replace this with your machine's IP address + # or DNS domain name + ip = "192.168.1.42"; + kafkaSock = "${ip}:${kafkaPort}"; +in { + # The Phoebus Alarm server also automatically enables the Phoebus Alarm Logger + services.phoebus-alarm = { + enable = true; + openFirewall = true; + settings."org.phoebus.applications.alarm/server" = "${kafkaSock}"; + }; + + # Tell Apache Kafka to listen on this IP address + # If you don't have a DNS domain name, it's best to set a specific, non-local IP address. + services.apache-kafka.extraProperties = '' + listeners=PLAINTEXT://${kafkaSock} + ''; + + # Elasticsearch, needed by Phoebus Alarm Logger, 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 +# For the Phoebus Alarm Server: +# Replace the IP address with your server's IP address or DNS domain name +org.phoebus.applications.alarm/server=192.168.1.42:9092 + +# For the Phoebus Alarm Logger: +# Replace the IP address again +org.phoebus.applications.alarm.logging.ui/service_uri=http://192.168.1.42:8080 +``` + +# Configuring topics + +The Phoebus Alarm system uses "topics" as a way of grouping alarms. +These topics are the available roots of your alarm tree. +You need to synchronize the topic names between: + +- Phoebus Alarm Server +- Phoebus Alarm Logger +- Phoebus graphical clients + +Changing the topic names in the Phoebus Alarm Server NixOS modules automatically creates them. + +::: callout-warning +Currently, the Phoebus Alarm Server doesn't support several topics. +::: + +For example, +if you want to have the topic `Project`, +add this configuration to the server: + +``` nix +{config, lib, ...}: let + topics = ["Project"]; +in { + services.phoebus-alarm-server = { + # ... + settings = { + # ... + "org.phoebus.applications.alarm/config_names" = topics; + }; + }; + + services.phoebus-alarm-logger.settings.alarm_topics = topics; +} +``` + +For the Phoebus graphical client, +add this configuration: + +``` ini +# config_name is only used in the Phoebus graphical client +org.phoebus.applications.alarm/config_name = Project +org.phoebus.applications.alarm/config_names = Project +``` + +# Configuring the address list + +If you want to limit the IOCs reachable by the Phoebus Alarm Server, +use these option: + +``` nix +{ + services.phoebus-alarm-server = { + # ... + settings = { + # ... + + # The Phoebus Alarm Server will only have access to these IOCs + "org.phoebus.pv.ca/addr_list" = ["192.168.1.5" "192.168.1.42"]; + "org.phoebus.pv.ca/auto_addr_list" = false; + }; + }; +} +``` + +# Configuring email support + +To enable email support, +set the `org.phoebus.email/mailport` setting. +Here is a list of options you might want to set: + +``` nix +{ + services.phoebus-alarm-server = { + # ... + settings = { + # ... + + "org.phoebus.email/mailhost" = "smtp.my-company.org"; + + # Optional: + + # 25 for plain SMTP + "org.phoebus.email/mailport" = 25; + # If authentication is needed: + "org.phoebus.email/username" = "user"; + "org.phoebus.email/password" = "password"; + # Default address to be used for From: + # if unspecified, then the last used "from" address is used + "org.phoebus.email/from" = "Sender "; + }; + }; +} +``` + +::: callout-warning +Currently, Phoebus Alarm Server only supports plain SMTP. +::: + diff --git a/nixos/modules/phoebus/alarm-server.nix b/nixos/modules/phoebus/alarm-server.nix index 556bf993..9319af53 100644 --- a/nixos/modules/phoebus/alarm-server.nix +++ b/nixos/modules/phoebus/alarm-server.nix @@ -76,17 +76,18 @@ in { defaultText = lib.literalExpression ''"localhost:''${toString config.services.apache-kafka.port}"''; }; - "org.phoebus.applications.alarm/config_name" = lib.mkOption { - description = '' - Name of alarm tree root. - - Will be used as the name for the Kafka topic. - ''; - type = lib.types.str; - # TODO: bug? From the code it seems that specifying multiple topics - # here with create_topics will have issues (AlarmServerMain.java:654) - default = "Accelerator"; - }; + # Waiting for: https://github.com/ControlSystemStudio/phoebus/issues/2843 + # + #"org.phoebus.applications.alarm/config_name" = lib.mkOption { + # description = '' + # Name of alarm tree root. + # Will be used as the name for the Kafka topic. + # ''; + # type = lib.types.str; + # # TODO: bug? From the code it seems that specifying multiple topics + # # here with create_topics will have issues (AlarmServerMain.java:654) + # default = "Accelerator"; + #}; "org.phoebus.applications.alarm/config_names" = lib.mkOption { description = '' @@ -97,16 +98,72 @@ in { type = with lib.types; listOf str; # TODO: bug? From the code it seems that specifying multiple topics # here with create_topics will have issues (AlarmServerMain.java:654) - default = [cfg.settings."org.phoebus.applications.alarm/config_name"]; - defaultText = lib.literalExpression ''[cfg.settings."org.phoebus.applications.alarm/config_name"]''; + default = ["Accelerator"]; apply = lib.concatStringsSep ","; }; + + # Email options: + # --- + + "org.phoebus.email/mailhost" = lib.mkOption { + description = '' + The SMTP server host. + + If set to DISABLE (the default), email support is disabled. + ''; + type = lib.types.str; + default = "DISABLE"; + }; + + "org.phoebus.email/mailport" = lib.mkOption { + description = '' + The SMTP server port. + ''; + type = lib.types.port; + default = 25; + apply = toString; + }; + + "org.phoebus.email/username" = lib.mkOption { + description = '' + Username for authenticating to the SMTP server. + ''; + type = lib.types.str; + default = ""; + }; + + "org.phoebus.email/password" = lib.mkOption { + description = '' + Password for authenticating to the SMTP server. + + Note: the password will be put in plaintext, in the world-readable `/nix/store`. + ''; + type = lib.types.str; + default = ""; + }; + + "org.phoebus.email/from" = lib.mkOption { + description = '' + Default address to be used for the email field `From:`. + + If left empty, then the last used from address is used. + ''; + type = lib.types.str; + default = ""; + }; }; }; }; }; config = lib.mkIf cfg.enable { + assertions = [ + { + assertion = !(lib.hasInfix "," cfg.settings."org.phoebus.applications.alarm/config_names"); + message = "Phoebus Alarm Server doesn't support multiple topics, yet"; + } + ]; + systemd.services.phoebus-alarm-server = { description = "Phoebus Alarm Server";