initconf is the name of a daemon running in the background of all VMs produced using the VM Build Container. It handles configuration, decommissioning, and upgrade of the VMs.

This page details how you can add custom configuration scripts that run on specified hooks in initconf - both during configuration of your VMs, and when a VM is decommissioned.

initconf hooks

There are two types of initconf hooks:

  • configuration hooks which run after new config has been uploaded to the CDS

  • quiesce hooks which run when a VM is decommissioned, e.g. due to an upgrade triggered by MDM.

These hooks are detailed in the tables below.

Configuration hooks

Configuration hook name Point hook is run

initial

This is the first configuration hook that will run. This hook will run immediately after new config has been uploaded to the CDS.

before-rhino-configuration

This will run before Rhino has been configured.

after-rhino-start

This will run after Rhino has started.

before-slee-start

This will run after the after-rhino-start hook completes, before the SLEE has started.

after-slee-start

This will run after the SLEE has started.

final

This will run after all other configuration config hooks complete.
Note The hook before-slee-start is run before the initconf task that is responsible for starting the SLEE after Rhino has been started. If initconf runs due to a change in CDS config after the SLEE has been started, the SLEE will already be running, but the before-slee-start config hook will still be run. The before-slee-start config script must take into account that the SLEE may already be running by the time this hook is run.

Quiesce hooks

Configuration hook name Point hook is run

before-scale-in-rhino

This will run before Rhino is stopped. It will run immediately after a VM has received a signal to quiesce.

after-scale-in-rhino

This will run after Rhino has been stopped.

Registering initconf hook scripts

To register initconf hook scripts to run against configuration or quiesce hooks, create executables named after each configuration hook you want to run against and add these to the optional custom-configuration.zip archive in the same directory as your Rhino license.

The initconf hook scripts must be in the root of the custom-configuration.zip archive, i.e. they must appear in the current working directory when the archive is extracted. The custom-configuration.zip archive may contain additional supplementary data for your initconf hook scripts alongside the executables. Configuration scripts can call other programs to achieve their tasks. These must already exist on the VMs or be provided in the custom-configuration.zip archive.

Note Each script’s name must match the corresponding hook’s name exactly. In particular, note that the names use hyphens (-), not underscores (_).
Note Ensure that the scripts have the user-executable permission bit set.
Note Ensure that the scripts' filenames have no extension, e.g. just before-rhino-configuration, not before-rhino-configuration.sh.

Example custom-configuration.zip archive structure:

custom-configuration.zip
├── initial
├── before-rhino-configuration
├── after-slee-start
├── custom-configurer.jar
└── supplementary-data
    └── data.json

The custom-config directory

A directory called custom-config will be created in the home directory of your VMs. This directory will contain the following sub-directories:

Directory Name Description

custom-config-workspace

Contents of the custom-configuration.zip archive will be extracted to this directory.

custom-config-data

All configuration yaml files will be copied to this directory

custom-config-output

This directory contains files containing any output generated by the initconf hook scripts.

How initconf hook scripts are run

Configuration hook scripts will be wrapped by initconf tasks to be run during the configuration process when new config is uploaded to the CDS. Quiesce scripts will be wrapped by quiesce tasks to be run during the quiesce process when a VM is decommissioned.

The initconf hook scripts will be run as the default user and will be run from the custom-config-workspace directory. The path to the custom-config-data directory will be passed to the initconf hook scripts as an argument so that they can use the data in the configuration yaml files.

When an initconf hook script is run, any output to the stdout and stderr streams will be captured and this output will be stored in a file in the custom-config-output directory. The output file for an initconf hook script will be named after the initconf hook script with a .out extension added. E.g. The file containing output for the initial initconf hook script will be named initial.out.

An empty file will be created if an initconf hook script does not write to either stdout or stderr. No output files will be created for hooks that do not have scripts registered against them.

If an initconf hook script returns with any return code other than 0, this will be interpreted as a failure. On such a failure the configuration process will end, and will start again when new config is uploaded to the CDS.

Environment variables

When an initconf hook script runs, the following variables are present in its environment.

  • The environment variable JAVA_HOME is set to the location of the Java Runtime Environment (JRE) that comes installed on the VM.

  • The environment variable RHINO_HOME points to the location of the Rhino installation.

  • The environment variable CLIENT_HOME points to the client directory within the Rhino installation, inside which you can find various Rhino tools, most notably ${CLIENT_HOME}/bin/rhino-console.

Example initial initconf hook script

If an initial initconf hook script with the contents

#!/bin/bash

cat hello.txt
echo Configuration yaml files:
ls "$1"

and a file called hello.txt with the contents Hello, world! are compressed into an archive called custom-configuration.zip using the command zip custom-configuration.zip initial hello.txt, and this zip file is included in the same directory as the Rhino license before building a VM, when the VM has been built these files will be extracted into the custom-config-workspace directory.

During configuration, the initial initconf hook script will be run against the initial configuration hook.

After configuration has been completed, an ls on the custom-config directory will show the following contents:

$ ls custom-config
custom-config-data  custom-config-workspace  custom-config-output

An ls on each sub-directory within the custom-config directory will show:

$ ls custom-config/custom-config-workspace
hello.txt  initial
$ ls custom-config/custom-config-data/
custom-config-data.yaml    routing-config.yaml  sdf-custom.yaml
custom-vmpool-config.yaml  sas-config.yaml      snmp-config.yaml
$ ls custom-config/custom-config-output/
initial.out

The contents of the resulting initial.out file will be:

Hello, world!

Configuration yaml files:
custom-config-data.yaml
custom-vmpool-config.yaml
routing-config.yaml
sas-config.yaml
sdf-custom.yaml
snmp-config.yaml

Example before-slee-start initconf hook script

The before-slee-start initconf hook is useful for setting up configuration within Rhino, based on the configuration in the custom-config-data.yaml configuration file.

For example, if a service uses an RA entity called custom-ra-entity, with a configuration property config-property, that we want to be able to configure on the VM at runtime. We can do this by providing the value in custom-config-data.yaml:

my-configuration:
  my-value: test

Note that this file is not present on the VM; it is provided using rvtconfig after the VM has been deployed. This means the value can be reconfigured and is not hard-coded on the VM.

To set this configuration within the VM, we can use the following before-slee-start initconf hook:

#!/opt/tasvmruntime-py/bin/python3

import os
import subprocess
import sys
import yaml

from pathlib import Path

config_dir = Path(sys.argv[1])
with open(config_dir / "custom-config-data.yaml", "r") as input_file:
    custom_config_data = yaml.safe_load(input_file)
config_property_value = custom_config_data["my-configuration"]["my-value"]

client_home = os.environ["CLIENT_HOME"]
process = subprocess.run(
    [
        f"{client_home}/bin/rhino-console",
        "updateraentityconfigproperties",
        "custom-ra-entity",
        "config-property",
        config_property_value,
    ],
    check=True,
    text=True,
)

This will cause the custom-ra-entity configuration property config-property to be set to the value provided in my-configuration/my-value in custom-config-data.yaml.

Previous page Next page