Skip to content

ANNEX C – ERMI Services Installation Guide

Overview

This document provides installation guidance for ERMI-related services that are required to support various out-of-band management features, such as Virtual Media and Event Service integration.

Currently, the document covers the installation of the following services:

  • Samba Server: Used by the ERMI Virtual Media implementation to provide remote ISO/IMG access.

  • Redfish Event Listener Service: Used to receive and process Redfish events emitted by managed systems.

All services described in this document are deployed using Docker to simplify installation, configuration, and lifecycle management. Therefore, the target environment must support Docker Engine and Docker Compose.

The command behavior is intentionally designed to resemble systemctl for a familiar user experience.

Prerequisites

Before proceeding, ensure that the target system meets the following requirements:

  • Docker Engine 20.10 or later

  • Docker Compose v2 (docker compose)

  • Sufficient privileges to manage Docker containers (either run as root or a user belonging to the docker group)

Download Required Files

Download the ERMI service deployment files to your local system.

The directory structure is expected to include files similar to the following: 

.
├── SambaDocker
    ├── docker-compose.yml
    ├── Dockerfile
    ├── entrypoint.sh
    ├── sambactl.sh
    ├── .env
    ├── images
├── RedfishEventServer
    ├── docker-compose.yml
    ├── Dockerfile
    ├── entrypoint.sh
    ├── relctl.sh
    ├── .env
    ├── cert
    ├── Event-Listener

Note

The sambactl.sh script is a management utility that provides a systemctl-style interface for managing the Samba service container. The relctl.sh script is a management utility that provides a systemctl-style interface for managing the Redfish Event Listener service container.

Setting Up the Samba Server

The Samba server is used to host virtual media images (ISO or IMG files) that can be mounted by the ERMI Virtual Media service.

Management Script Overview

The sambactl.sh script is a management utility that provides a systemctl-style interface for managing the Samba service container.

The images directory is shared with the Docker container and is used to store files that need to be shared via Samba. Any files placed in this directory will be accessible via the Samba share.

This script provides the following commands:

  • start – Start the Samba service (create the container if it does not exist)
  • stop – Stop the Samba service
  • restart – Restart the Samba service
  • status – Display the current service status
  • rebuild – Recreate the container and rebuild the image
  • destroy – Remove the container (destructive operation)
  • logs - Follow container logs

Warning

The destroy command permanently removes the container. Any unsaved runtime data inside the container will be lost.

Starting the Samba Server

Before starting the service, ensure your environment supports Docker and Docker Compose.

To start the Samba server using default settings:

sudo ./sambactl.sh start

Default configuration values:

  • SAMBA_USER: admin
  • SAMBA_PASS: admin
  • SAMBA_SHARE: share

The images directory will be mounted into the container as the Samba share, so you can place any files you want to share in this directory.

Customizing Samba Configuration

You can specify custom credentials and share name when starting or rebuilding the service:

sudo ./sambactl.sh start -u <username> -p <password> -s <share_name>
Example

sudo ./sambactl.sh start -u guest -p guest123 -s iso

These values are stored in the .env file and are reused on subsequent starts unless explicitly changed.

Checking Service Status

To check the current status of the Samba service: 

./sambactl.sh status

Example output: 

● samba.service
   Loaded: loaded (docker compose)
   Active: active (running)

To follow the logs in real time: 

./sambactl.sh logs

Stopping the Samba Server

To stop the service without removing the container: 

sudo ./sambactl.sh stop

This operation preserves the container and configuration for later reuse.

Notes and Best Practices

  • Always place files that need to be shared inside the images directory.
  • Do not place sensitive system files in the images directory, as they will be exposed via Samba.
  • Use rebuild only when you want to recreate the container (for example, after changing the Dockerfile or .env settings).
  • Use destroy only if you want to completely remove the container.

Setting Up the Redfish Event Listener Server

The Redfish Event Listener Server receives and processes Redfish events emitted by managed systems.
This service is containerized and can be managed using the relctl.sh script.

Management Script Overview

The relctl.sh script is a systemctl-style utility to manage the REL (Redfish Event Listener) container.

It provides the following commands:

  • start – Start the REL service (create the container if it does not exist)
  • stop – Stop the REL service
  • restart – Restart the REL service
  • status – Display the current service status
  • rebuild – Recreate the container and rebuild the image
  • destroy – Remove the container (destructive operation)
  • logs - Follow container logs
  • export - Copy all event files from container to host

All event files generated by the listener are stored in the container’s /app/data directory, which is mapped to ./Event-Listener on the host.

Warning

The destroy command permanently removes the container. Any unsaved runtime data inside the container will be lost.

Starting the Redfish Event Listener

Before starting the service, ensure your environment supports Docker and Docker Compose.

To start the Redfish Event Listener using default settings:

sudo ./relctl.sh start

Default configuration values:

  • REL_HTTPS_PORT: 443
  • REL_CERT_FILE: cert.pem
  • REL_KEY_FILE: server.key

The service will: - Clone the Redfish Event Listener repository into the container (if not present). - Copy user certificates (if provided). - Update config.ini with listener port, certificate paths, and SSL enabled. - Bind the listener to 0.0.0.0 so it is reachable from the host.

Customizing Redfish Event Listener Configuration

You can specify custom related settings when starting or rebuilding the service:

sudo ./relctl.sh start -p <port> -c <cert file name> -k <key file name>
Example

sudo ./relctl.sh start -p 5000 -c mycert.pem -k myserver.key

Certificate usage

  • Default (no files needed):

    If you do not provide any certificate files, the container will use the default certificates included in the Redfish Event Listener repository. You do not need to place any files in the cert/ directory.

  • Custom certificates: Place your custom certificate and key in the cert/ directory (filenames can be specified in .env).

    Only the certificate file names should be specified. The files must be placed in the cert/ directory.

Checking Service Status

To check the current status of the Samba service: 

./relctl.sh status

Example output: 

● rel-service
   Loaded: loaded (docker compose)
   Active: active (running)

To follow the logs in real time: 

./relctl.sh logs

Stopping the Redfish Event Listener

To stop the service without removing the container: 

sudo ./relctl.sh stop

This operation preserves the container and configuration for later reuse.

Exporting Event Files

The export command copies event files from the container to a separate host directory for archival or analysis purposes.

To copy all generated event files from the container to the host: 

sudo ./relctl.sh export

  • Default destination is ./events_export if not specified.
  • The script copies Event*.txt files from /app/data in the container.
  • If no event files are present, a friendly message is displayed.

Notes and Best Practices

  • Always ensure the container is running before exporting events.
  • Persisted event files are stored in ./Event-Listener.
  • Use rebuild only when changing ports or certificates.
  • Avoid stopping the container forcefully to prevent losing in-flight events.

Summary

This document introduced the installation process for ERMI-related services using Docker-based deployment. By leveraging containerization and standardized management scripts, these services can be installed, configured, and maintained in a consistent and repeatable manner.

Future updates will expand this guide to include advanced configuration options and additional ERMI service components.