Device lifecycle hooks

The Red Hat Edge Manager agent can run user-defined commands at specific points in the device lifecycle by using device lifecycle hooks.

For example, you can add a shell script to your operating system images that backs up your application data. You can then specify that the script must run and complete successfully before the agent can start updating the operating system.

As another example, certain applications or system services do not automatically reload their configuration file when the file changes on the disk. You can manually reload the configuration file by specifying a command as another hook, which is called after the agent completes the update process.

The Red Hat Edge Manager agent discovers hook rules only in subdirectories of /etc/flightctl/hooks.d/ and /usr/lib/flightctl/hooks.d/. Those subdirectory names are case-sensitive and must be all lowercase. For example, afterUpdating is not valid; use afterupdating.

The following subdirectories are supported:

Table 1. Supported hook subdirectories
hooks.d subdirectory Description

beforeupdating

The hook is called after the agent completes preparing for the update, but before changing the operating system. If an action in this hook returns with a failure, the agent cancels the update.

afterupdating

The hook is called after the agent writes the update to disk. If an action in this hook returns with a failure, the agent cancels and rolls back the update.

beforerebooting

The hook is called before the system reboots. The agent blocks the reboot until the action completes or times out. If any action in this hook returns with a failure, the agent cancels and rolls back the update.

afterrebooting

The hook is called when the agent first starts after a reboot. If any action in this hook returns with a failure, the agent reports the failure but continues starting up.

Rule files

You can define device lifecycle hooks by adding rule files under one of the following directory trees on the device:

  • /usr/lib/flightctl/hooks.d/<hook_directory>/: Read-only from the running system; add rules here by baking them into the operating system image.
  • /etc/flightctl/hooks.d/<hook_directory>/: Read-writable at runtime; you can update these rules by several methods.

In both paths, replace <hook_directory> with one of beforeupdating, afterupdating, beforerebooting, or afterrebooting. For example, a custom rule that runs after the update is written to disk belongs in a file such as /etc/flightctl/hooks.d/afterupdating/50-my-hook.yaml.

When creating and placing the files, you must consider the following practices:

  • The name of the rule must be all lower case.
  • The hook subdirectory name under hooks.d/ must be one of the lowercase names in the table; mixed-case or camel case names are ignored by the agent.
  • If you define rules in both locations, the rules are merged.
  • If you add more than one rule files to a lifecycle hook directory, the files are processed in lexical order of the file names.
  • If you define files with identical file names in both locations, the file in the /etc folder takes precedence over the file of the same name in the /usr folder.

A rule file is written in YAML format and contains a list of one or more actions. An action can be an instruction to run an external command.

When you specify many actions for a hook, the actions are performed in sequence, finishing one action before starting the next.

If an action returns with a failure, the following actions are skipped.

A run action takes the following parameters:

Table 2. Run action parameters
Parameter Description

Run

The command to run, including any flags or arguments. Specify the full path to the executable (for example /usr/bin/nmcli connection reload) or an executable name that resolves through the PATH environment variable of the agent (for example nmcli conn reload), consistent with the built-in rules under /usr/lib/flightctl/hooks.d/. The agent uses the PATH from its runtime environment (for example, as set when the agent runs as a systemd service). The command is not run in a shell: the rule value is not shell-expanded, so you cannot use shell parameter expansion such as $HOME or chain commands with | or ; in the rule text. To use shell features, call a shell explicitly, for example /usr/bin/bash -c 'echo $SHELL $HOME $USER'.

EnvVars

Optional. A list of key-value pairs to set as environment variables for the command.

WorkDir

Optional. The directory the command is run from.

Timeout

Optional. The maximum duration that is allowed for the action to complete. Specify the duration as a single positive integer followed by a time unit. The following units are supported: s (seconds), m (minutes), and h (hours).

If

Optional. A list of conditions that must be true for the action to be run. If not provided, actions run unconditionally.

By default, actions are performed every time the hook is triggered. However, for the afterupdating hook, you can use the If parameter to add conditions that must be true for an action to be performed. Otherwise, the action is skipped.

For example, to run an action only if a given file or directory changes during the update, you can define a path condition that takes the following parameters:

Table 3. Path condition parameters
Parameter Description

Path

An absolute path to a file or directory that must change during the update as condition for the action to be performed. Specify paths by using forward slashes (/). If the path is to a directory, it must end with a forward slash (/). If you specify a path to a file, the file must have changed to satisfy the condition. If you specify a path to a directory, a file in that directory or any of its subdirectories must have changed to satisfy the condition.

Op

A list of file operations, such as created, updated, and removed, to limit the type of changes to the specified path as condition for the action to be performed.

If you specify a path condition for an action in the afterupdating hook, you can use the following variables in arguments to your command. These variables are replaced with the absolute paths to the changed files:

Table 4. Path condition variables
Variable Description

${ Path }

The absolute path to the file or directory specified in the path condition.

${ Files }

A space-separated list of absolute paths of the files that changed during the update and are covered by the path condition.

${ CreatedFiles }

A space-separated list of absolute paths of the files that were created during the update and are covered by the path condition.

${ UpdatedFiles }

A space-separated list of absolute paths of the files that were updated during the update and are covered by the path condition.

${ RemovedFiles }

A space-separated list of absolute paths of the files that were removed during the update and are covered by the path condition.

The Red Hat Edge Manager agent includes a built-in set of rules defined in /usr/lib/flightctl/hooks.d/afterupdating/00-default.yaml. The following commands are executed if certain files are changed:

Table 5. Built-in afterupdating hook rules
File Command Description

/etc/systemd/system/

systemctl daemon-reload

Changes to systemd units are activated by signaling the systemd daemon to reload the systemd manager configuration. This reruns all generators, reloads all unit files, and re-creates the entire dependency tree.

/etc/NetworkManager/system-connections/

nmcli conn reload

Changes to NetworkManager system connections are activated by signaling the NetworkManager daemon to reload all connections. For more information, see the Additional resources section.

/etc/firewalld/

firewall-cmd --reload

Changes to the permanent configuration of firewalld are activated by signaling firewalld to reload firewall rules as new runtime configuration.

For networking configuration details, see Configuring and managing networking in the Additional resources section.