Adding third-party executables

Prev Next

Appliances can run a script to support third-party add-ons such as external reporting or monitoring agents. This capability is disabled by default.

NOTE

Installing apt packages also falls under this category.


Appliance customization script

To run a customization script on a new appliance, Enabled Customization must be set to true when running cz-setup, or Allow the use of appliance customizations must be selected when the appliance seed file is created.

To check whether customizations are enabled on an existing appliance, run::

sudo cz-config get customization/enabled

To enable cutomizations, run:

sudo  cz-config set -j customization/enabled true

Customization scripts always carry the risk of degraded functionality, performance, or system security. They are also known to interfere with appliance upgrades. All customizations are managed through the Appliance Customizations page to reduce these risks. Because scripts run with root privileges, AppGate ZTNA does not recommend their use.


Installing packages from a start up script

Customizations are disabled when the cloud startup script runs. To install apt packages during startup of a cloud instance, temporarily allow apt to run:

# 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 customization file must be in .zip format. Take care when creating the ZIP file — macOS adds extra files when you use the Compress utility, and some Windows ZIP tools may introduce DOS-to-UNIX format issues.

The ZIP archive must meet the following requirements.

Required file:

File

Description

start

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

Optional files:

File

Description

metadata.txt

Specifies the appliance versions this customization applies to.

stop

Called to stop customizations before upgrades or before starting new customizations. The stop script kills or stops the start script before it runs. Use this when the start script is a long-running process such as a listener.

status

Called by configd health checks. The exit code reports status: 0 is healthy, 6 is a warning, and any other value is an error. If a warning or error is reported, the appliance echoes the script's message to the dashboard. This lets you verify that one or more executables are running as expected and pass relevant diagnostic messages to the dashboard. If no status executable is 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, and so on.

The ZIP file must not contain anything else.


ZIP file structure

A ZIP file might have the following structure:

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

The start script might look like the following:

#!/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.tx format

You can specify up to three numbers in the version. When no number is specified, it is treated as less than any specified number. Empty lines and extra spaces are ignored.

# This is a comment
MIN_APPLIANCE_VERSION=6.2.6
MAX_APPLIANCE_VERSION=7

This example runs scripts on all sub-versions of v6 starting from 6.2.6. It does not run on 7.0.0 because 7 is treated as less than 7.0.0.

Status script example

A status script such as the following:

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

Displays the message on the dashboard:

Error message indicating customization issue with appliance and forwarding logs.


The executable

Keep executables as simple as possible. Avoid loops and long delays, and handle exceptions appropriately.

Only one script is supported per appliance. If you need to run more than one executable, package them together and call each executable sequentially within a single script. The start and stop scripts in the ZIP file must start and stop all executables.

NOTE

The start script runs as root. Drop privileges to the cz user if root access is not required for the customization.

Including audit logs

The auditgen utility generates additional audit log entries on demand from any daemon, including third-party executables. Specify key-value pairs to add fields to the logs. Use - instead of a list of key-value pairs to read JSON from standard input and generate one audit log entry per line.

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

Example:

auditgen hwmonitor event_type=disk_failure device=/dev/sda3

Executable example

The following is an example of a working appliance customization ZIP file that installs a syslog handler service on an appliance: appliance customization zip file. The data folder contains a Python script, a service definition, and a certificate file. The start script installs and enables the syslog service. The stop script stops the service and cleans up.


Uploading the executable

To add a script, go to Appliance Customizations (System > Appliance Customizations) and upload your executable as a ZIP file. The uploaded ZIP file is extracted to opt/customization.zip. After uploading, select the customization in the appropriate appliance configuration form.