--- title: "Adding third-party executables" slug: "adding-third-party-executables-v7-0" description: "Learn how to enable appliance customizations, run scripts, and manage third-party add-ons for enhanced functionality and monitoring." tags: ["Third-Party Executables", "Appliance Customization", "Scripts"] updated: 2026-06-05T14:36:10Z published: 2026-06-05T19:17:41Z canonical: "support.appgate.com/adding-third-party-executables-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Adding third-party executables 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] > 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](/v1/docs/appliance-customizations-v7-0) 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: ```bash # 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 # 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.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag62-customization_warning.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A42Z&se=2026-11-21T22%3A39%3A42Z&sr=b&sp=r&sig=1FdscIw%2BG3kN%2B4KentdK036npLdMdFFqPWXTk1h%2FGCc%3D) | | `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: ```plaintext metadata.txt /data/bin/agentA     /bin/agentB     /conf/config.JSON /start /status /stop ``` The `start` script might look like the following: ```shell #!/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. ```plaintext # 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: ```shell #!/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.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag50-script_error.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A42Z&se=2026-11-21T22%3A39%3A42Z&sr=b&sp=r&sig=cmqykPa7kp3ClL6HWnNUXtAnts8GWzYwHFvErciKRDI%3D) --- ## 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] > 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](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/alert-handler.zip?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A42Z&se=2026-11-21T22%3A39%3A42Z&sr=b&sp=r&sig=lltikiA39t9fyH2jLUvFNHGGzu1giXCq%2F3LQHigHu5k%3D). 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.