From 0ed900687c8de85bd0137ff697bf1e71a2a46a2e Mon Sep 17 00:00:00 2001 From: Minijackson Date: Wed, 4 Sep 2024 15:05:14 +0200 Subject: [PATCH] doc/nixos-services: add ChannelFinder user guide --- .../user-guides/channel-finder.rst | 327 ++++++++++++++++++ docs/nixos-services/user-guides/index.rst | 1 + 2 files changed, 328 insertions(+) create mode 100644 docs/nixos-services/user-guides/channel-finder.rst diff --git a/docs/nixos-services/user-guides/channel-finder.rst b/docs/nixos-services/user-guides/channel-finder.rst new file mode 100644 index 00000000..132a1798 --- /dev/null +++ b/docs/nixos-services/user-guides/channel-finder.rst @@ -0,0 +1,327 @@ +ChannelFinder service setup +=========================== + +ChannelFinder is a directory service which enables searching for PV names, +called *channels names*, +and associated metadata. + +A ChannelFinder server is usually combined with a "RecCaster" module in the IOC, +that sends the metadata, +and a "RecCeiver" server +that scans and retrieves the metadata from "RecCaster." + +For more information on the ChannelFinder architecture, +see the official `ChannelFinder introduction`_. + +.. _ChannelFinder introduction: https://channelfinder.readthedocs.io/en/latest/overview.html + +.. include:: ./pre-requisites.rst + +ChannelFinder service +--------------------- + +To enable the ChannelFinder service, +use :ref:`opt-services.channel-finder.enable` and related options. +You will also need to enable ElasticSearch. + +For example: + +.. code-block:: nix + :caption: :file:`channel-finder.nix` --- ChannelFinder configuration example + + {lib, pkgs, ...}: { + services.channel-finder = { + enable = true; + openFirewall = true; + settings = { + + # Choose your authentication type (see below for explanations) + # --- + #"demo_auth.enabled" = true; + #"ldap.enabled" = true; + + "server.port" = 8444; + "server.http.port" = 8082; + }; + }; + + # Install Elasticsearch, + # because it's a ChannelFinder service dependency + services.elasticsearch = { + enable = true; + package = pkgs.elasticsearch7; + }; + + # Elasticsearch, needed by ChannelFinder, 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" + ]; + } + +For more settings, +see the `ChannelFinder configuration`_ reference. + +.. _ChannelFinder configuration: https://channelfinder.readthedocs.io/en/latest/config.html + +Authentication +^^^^^^^^^^^^^^ + +ChannelFinder supports different types of authentication backends: + +Demo authentication + *Not recommended for production servers*. + Users, + their roles, + and passwords + are specified in the configuration file, + in plain text. + +External LDAP server + The ChannelFinder service connects to an external LDAP server, + and uses it for authentication and role assignment. + + .. note:: + Configuring an fully-featured LDAP server is out of scope for this guide, + but the ChannelFinder service can connect to another service's embedded LDAP server. + + For example, + ChannelFinder could connect to a Phoebus Olog's embedded LDAP server configured beforehand. + +Demo authentication +~~~~~~~~~~~~~~~~~~~ + +.. caution:: + + This authentication type is not recommended for production servers. + +Users, +roles, +and passwords +are stored as comma-separated list in the configuration. + +For example: + +.. code-block:: nix + :caption: :file:`channel-finder.nix` --- demo authentication example + + services.channel-finder = { + settings = { + "demo_auth.enabled" = true; + "demo_auth.users" = "admin,operator,expert"; + "demo_auth.pwd" = "adminPass,operatorPass,expertPass"; + # Multiple roles can be given by separating them with ':' + "demo_auth.roles" = "ADMIN:EXPERT,USER,USER:EXPERT"; + }; + }; + +External LDAP server +~~~~~~~~~~~~~~~~~~~~ + +This section assumes you already have a configured LDAP server. +This configured LDAP server can be an embedded LDAP server of another service. + +If you want to use your company's LDAP server, +contact your IT team for the LDAP configuration: + +- URL, +- base DN, +- user DN pattern, +- search base, +- and search path. + +Here is an example configuration: + +.. code-block:: nix + :caption: :file:`channel-finder.nix` --- external LDAP authentication example + + services.channel-finder = { + settings = { + "ldap.enabled" = true; + "ldap.urls" = "ldaps://auth.mycompany.com/dc=mycompany,dc=com"; + "ldap.user.dn.pattern" = "uid={0},ou=People,dc=mycompany,dc=com"; + "ldap.groups.search.base" = "ou=Group,dc=mycompany,dc=com"; + "ldap.groups.search.pattern" = "(memberUid= {1})"; + }; + }; + +RecCeiver +--------- + +The RecCeiver service scans for IOCs in the network, +and fetches the list of PV names and other metadata. +You can configure it to put this information into the ChannelFinder service. + +Use the ``channelfinderapi.DEFAULT`` setting for configuring the connection to the ChannelFinder service, +and use the ``settings`` option for configuring all other settings. + +For a list of available ``settings``, +examine the `RecCeiver demo.conf`_ file. + +TODO: explain which cf role is needed + +For example: + +.. code-block:: nix + :caption: :file:`channel-finder.nix` --- RecCeiver configuration example + :name: recceiver-configuration-example + + {lib, pkgs, ...}: { + # Other previous options... + + services.recceiver = { + enable = true; + + channelfinderapi.DEFAULT = { + username = "admin"; + password = "adminPass"; + }; + + settings = { + recceiver = { + # Necessary if you want a firewall, + # which is enabled by default in NixOS. + bind = "0.0.0.0:5050"; + + # When receiving metadata, + # print it on the command-line (show), + # and send it to ChannelFinder (cf). + procs = ["show" "cf"]; + }; + cf = { + # PV metadata to send to ChannelFinder + alias = "on"; + recordDesc = "on"; + recordType = "on"; + }; + }; + }; + + networking.firewall.allowedTCPPorts = [5050]; + } + +.. _RecCeiver demo.conf: https://github.com/ChannelFinder/recsync/blob/1.6/server/demo.conf + +.. _recceiver-firewall: + +Firewall +^^^^^^^^ + +If ``settings.bind`` is unset, +RecCeiver listens on a random port, +which makes it difficult to open the firewall. + +To open the firewall, +make sure to set the bind address to a fixed port, +and open it in the firewall as TCP, +as shown in the :ref:`recceiver-configuration-example`. + +On the IOC side, +the firewall needs to allow the UDP announcer port, +which by default is 5049. + +If your IOC is a NixOS machine, +you can open the firewall with this configuration: + +.. code-block:: nix + :caption: Opening the IOC's firewall for RecCaster + + networking.firewall.allowedUDPPorts = [5049]; + +Setting the address list +^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to scan a specific network, +or if you want to change the port number used for scanning, +you can use the ``settings.recceiver.addrlist`` option. + +.. warning:: + + If you change the port, + make sure to also change it in the IOC firewall rules. + + See :ref:`recceiver-firewall`. + +.. code-block:: nix + :caption: :file:`channel-finder.nix` --- changing the RecCeiver address list + + {lib, pkgs, ...}: { + # ... + + services.recceiver = { + # ... + settings = { + recceiver = { + # ... + + # If you change the port, + # make sure to also change it in the IOC firewall rules + addrlist = ["192.168.1.255:5049"]; + }; + # ... + }; + }; + + # ... + } + +.. _recceiver-custom-metadata: + +Custom metadata +^^^^^^^^^^^^^^^ + +To add custom metadata variable to the ChannelFinder service, +use the ``settings.cf.environment_vars`` option, +for example: + +.. code-block:: nix + :caption: :file:`channel-finder.nix` --- adding custom metadata to ChannelFinder + + {lib, pkgs, ...}: { + # ... + + services.recceiver = { + # ... + settings = { + # ... + cf = { + # ... + environment_vars = { + # Follows the pattern: + # IOC_VARIABLE = "ChannelFinderProperty"; + CONTACT = "Concact"; + EPICS_BASE = "EpicsBase"; + EPICS_VERSION = "EpicsVersion"; + PWD = "WorkingDirectory"; + }; + }; + }; + }; + }; + +External ChannelFinder server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If your ChannelFinder server is located on another machine, +use the ``channelfinderapi.DEFAULT.BaseURL`` option: + +.. code-block:: nix + :caption: :file:`channel-finder.nix` --- specifying an external ChannelFinder server + + services.recceiver = { + # ... + + channelfinderapi.DEFAULT = { + BaseURL = "http://192.168.1.42:8082/ChannelFinder"; + # ... + }; + + # ... + }; + +RecCaster +--------- + +To configure RecCaster in your IOCs, +examine the guide :doc:`../../ioc/user-guides/reccaster`. diff --git a/docs/nixos-services/user-guides/index.rst b/docs/nixos-services/user-guides/index.rst index 2aa264af..4ff8641a 100644 --- a/docs/nixos-services/user-guides/index.rst +++ b/docs/nixos-services/user-guides/index.rst @@ -11,5 +11,6 @@ User guides :maxdepth: 1 ./ca-gateway.rst + ./channel-finder.rst ./phoebus-alarm.rst ./phoebus-save-and-restore.rst