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
aptpackages 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_aptExecutable 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 |
|---|---|
| Called to start customizations on boot or when the remote customization checksum changes. |
Optional files:
File | Description |
|---|---|
| Specifies the appliance versions this customization applies to. |
| 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. |
| Called by |
| 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
/stopThe 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/confmetadata.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=7This 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 1Displays the message on the dashboard:

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
startscript runs as root. Drop privileges to theczuser 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.
