--- title: "Adding third-party executables" slug: "adding-third-party-executables-v6-7" description: "Learn how to enable appliance customizations, run scripts, and manage apt packages for enhanced functionality and monitoring in your system." updated: 2026-03-17T15:23:55Z published: 2026-04-03T16:41:11Z canonical: "support.appgate.com/adding-third-party-executables-v6-7" --- > ## 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 Although disabled by default, the appliance can run a script to support third party add-ons such as external reporting or monitoring agents. > [!NOTE] > NOTE > > The installation of `apt` packages also falls under this category. ## Appliance Customizations script If *Enabled Customizatio*n was set to *true* when running `cz-setup`, or if *Allow the use of appliance customization*s option was selected when the appliance seed file was created, then a new appliance will be able to run a valid customization script. If you need to use a customization scripts later, 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 with [appliance customizations](/v1/docs/appliance-customizations-v6-7). 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 ```plaintext # 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 file should be in a `.zip` format. Be careful when creating your zip file. For example, macOS adds other things into the file if you use the compress utility. Some Windows zip programs might struggle with DOS-to-UNIX format issues. The zip archive file has to meet 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.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag62-customization_warning.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A02%3A59Z&se=2026-10-26T23%3A02%3A59Z&sr=c&sp=r&sig=aT28TABaYQRhjT0BykFio2XM%2BEnS5yReJz7o6qJZB7w%3D) `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/shchmod +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 up to three 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 commentMIN_APPLIANCE_VERSION=6.2.6MAX_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/shecho "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.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag50-script_error.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A02%3A59Z&se=2026-10-26T23%3A02%3A59Z&sr=c&sp=r&sig=aT28TABaYQRhjT0BykFio2XM%2BEnS5yReJz7o6qJZB7w%3D) ## 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] > 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](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/alert-handler.zip?sv=2026-02-06&spr=https&st=2026-10-26T22%3A02%3A59Z&se=2026-10-26T23%3A02%3A59Z&sr=c&sp=r&sig=aT28TABaYQRhjT0BykFio2XM%2BEnS5yReJz7o6qJZB7w%3D) 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. The stop script stops the service and cleans up. ## Uploading the executable To add a script use the [Appliance Customizations](/v1/docs/appliance-customizations-v6-7) page to 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](/v1/docs/functions-v6-7) form.