Adding third-party executables

Although disabled by default, the appliance can run a script to support third party add-ons such as external reporting or monitoring agents.

NOTE
The installation of apt packages also falls under this category.

Appliance Customizations script

If Enabled Customization was set to true when running cz-setup or if Allow the use of appliance customizations option was selected when the appliance seed file was created, then a new appliance will be able to run a valid customization script.

If, later you need to use a customization scripts then you can check the setting using:

sudo cz-config get customization/enabled

and this facility can be enabled by running:

sudo cz-config set -j customization/enabled true

Such scripts always carry the risk that their execution may result in degraded functionality, performance or system security posture. They are also known to interfere with the operation of the appliances especially when it comes to upgrades, so to try to mitigate these problems, all customizations are managed via Appliance Customizations. Because such scripts will be run with root privileges Appgate does not recommended their use.

Installing packages from a start up script

Customizations are disabled when running the cloud start up script. However, if you need to install apt packages during start up of a cloud instance this can be done by temporarily allowing apt to run :

Allowing apt

# Temporarily allow running apt so we can install things,
# configd is waiting on the startup script to complete so we can't use a cz-config set command.
cp /mnt/root-ro/etc/apt/sources.list /etc/apt/sources.list
rm /etc/dpkg/dpkg.cfg.d/customization-check
restore_apt () {
    cp /mnt/state/config/current/compiled/etc/apt/sources.list /etc/apt/sources.list
    cp /mnt/root-ro/etc/dpkg/dpkg.cfg.d/customization-check /etc/dpkg/dpkg.cfg.d/customization-check
}
trap restore_apt EXIT

# Install apt packages
apt-get update
apt-get install --yes <list of apt packages>

# Restore apt configuration
trap - EXIT
restore_apt

Executable file format

The file should be in a .zip format. Be careful when creating your zip file. macOS for instance adds other things into the file if you just use the compress utility. Some Windows zip programs might struggle with dos-to-unix format issues. The zip archive file has to meet some very specific requirements:

Must contain this file:

start
Called to start customizations on boot or when the remote customization checksum changes

May contain one or more of the following files:

metadata.txt

Specifies the versions that this customization applies to.

stop
Called to stop customizations before upgrades or before starting new customizations. The stop script will kill/stop the start script before it is executed. This applies to cases where the start script was a long running process such as a listener.

status
Called by the configd healthchecks. The exit code is used to report status, 0 healthy, 6 warning and anything else is considered an error. If a warning or error is reported then the appliance will echo the message from the script to the dashboard. This allows checks to be made on one or more executables to verify they are running as expected and for relevant diagnostic messages to be passed to the dashboard. If the status executable is not defined the status is assumed to be healthy.

Appliance health details showing warning status for appliance health and a healthy status for gateway appliance.

data/
a directory containing binaries, data, configurations, etc.

Must not contain anything else

ZIP File structure

The .zip file structure therefore might look like:

metadata.txt /data/bin/agentA /bin/agentB /conf/config.JSON /start /status /stop

The Start script then might look like:

#!/bin/sh chmod +x /opt/customization/data/bin/agentA && \ chmod +x /opt/customization/data/bin/agentB && \ -u cz /opt/customization/data/bin/agentA -u cz /opt/customization/data/bin/agentB -config-dir /opt/customization/data/conf

Metadata.txt format:

You can specify 1 2 or 3 numbers in the version. When no number is specified it is assumed to be less than any specified numbers. Empty lines are ignored. Random spaces are ignored.

# This is a comment MIN_APPLIANCE_VERSION=6.2.6 MAX_APPLIANCE_VERSION=7

This would run scripts on all sub-versions of v6 starting from 6.2.6. It would not run on 7.0.0 because 7 is considered less than 7.0.0.

A status script containing

#!/bin/sh echo "Lorem ipsum dolor sit amet, consectetur adipiscing elit,sed do eiusmod tempor incididunt ut labore et dolore magna aliqua." exit 1

Would show the following in the dashboard:

Error message indicating customization issue with appliance and forwarding logs.

The executable

Any executable should be as simple as possible to achieve the desired outcome. Consideration should be given to its execution - avoiding adding loops or long delays and ensuring any exceptions are handled appropriately.

You can only have one script per appliance, so if you need to run more than one executable then they need to be packaged together with all the executables called sequentially within the one script. The start/stop script included in the zip file needs to start/stop all executables.

NOTE
The start script is run as root but you should drop privileges if root is not required to run the customization (use 'cz' user).

Including audit logs

There is a useful utility that generates additional audit log entries on demand from any daemon including third party executables. By specifying key-value pairs the requested fields will appear in the logs. With a - instead of a list of key,value pairs it will read JSON from standard input and generate one audit log entry each line.

auditgen DAEMON_NAME KEY=VALUE [KEY=VALUE]...

Example:

auditgen hwmonitor event_type=disk_failure device=/dev/sda3

Executable example

Here is an example of a working appliance customization zip file that installs a syslog handler service to an appliance. Under the data folder, there is a python script, a service definition and a certificate file. The start script installs and enables the syslog service. stop script stops the service and cleans up.

Uploading the executable

To add a script use the Appliance Customizations form where you upload your executable as a zip file. The uploaded customization zip is extracted to opt/customization.zip. When this is uploaded, remember that you then need to select this customization in the appropriate appliance configuration form.