The Scripts screen in Portail ZAPP (menu Administration › Connectors and automation › Scripts) holds the register of administration scripts that can then be run on the server or on machines equipped with an Outpost agent. It is restricted to Administrators.
The script list
Each script shows its Name, Engine, Target, Author and Last modified date (the date of its most recent version). Type part of the name in Search, then Filter; Reset returns to the full list. Click a row to open the script.
Create a script
Create a script asks for:
- Name and Description. The name is unique: two scripts cannot have the same name, ignoring case, accents and leading or trailing spaces ("Purge temp" and "purge TEMP" are the same name);
- Engine: Windows PowerShell 5.1, PowerShell 7 (pwsh), Bash, sh (POSIX) or Shebang (#!). Pick an engine available on the target machines;
- Target: Local only (on the server), Outposts only (on agents) or Local and Outposts. A script cannot be run on a target its scope excludes;
- Default timeout (seconds): beyond it, the execution is stopped and becomes Timed out. Left empty, it is 300 seconds; 24 hours (86,400 seconds) at most;
- Default retry count: the value is saved, but it does not currently trigger any automatic retry; 10 at most;
- Content: the script text, 2 MB at most (2,097,152 bytes once encoded in UTF-8; an accented letter counts as two bytes). The same limit applies to every new version;
- Parameters (optional): Add a parameter for each value requested at launch.
For each parameter, enter its Name, its Type (String, Integer, Boolean or Enum), whether it is Required, its display Order and, depending on the type, a Validation regex, a Min and a Max, or Allowed values separated by commas (mandatory for an Enum). Values entered at launch are checked against these rules.
Create saves the script and its version 1. After creation, the name, description, engine, target, timeout and confirmation threshold cannot be changed from the screen or through the API: a new version only changes the content and the parameters. A GOLIVE, however, copies them from the source instance. The confirmation threshold for a run on a machine group is 25 machines; only creating the script through the API (POST /api/v1/scripts, field groupConfirmationThreshold) lets you set another one.
Use a secret
Never paste a password into a script: reference a secret from the Secrets module with the syntax {{secret:secret-name}}. The value is inserted at execution time; it is neither saved in the script nor kept in the history. For an execution on a remote machine, the command waiting to be sent is encrypted in the database, then erased as soon as the execution is finished. Caution: if the script itself prints the secret (for example by writing out its variables), the value appears in the execution output. A badly written reference is rejected on save. If the secret does not exist or the Secrets module is not enabled, the execution is refused.
Versions
A script's page lists its Versions (number, author, date). Click a version to display its Content and Parameters.
New version starts from the content and parameters of the latest version; edit them, then Create. A saved version cannot be changed: every change creates a new version, which keeps track of what was run. A new version can be used immediately, with no approval step.
From the displayed version, Execute runs the script and History shows its executions (see "Run a script"). You can therefore rerun an earlier version.
Target authorization
The Target authorization section decides who can run this script on which Outpost agents. Each rule links a Role (a user group) to a Machine group (defined in the Outpost agents module). Choose both, then Add; Delete removes a rule.
- With no rule at all, the script cannot be run on any remote agent.
- To run the script on an agent, you must belong to the group of a rule whose machine group contains that agent. An agent that belongs to no machine group cannot receive any script.
- These rules do not apply to local execution on the server.
When the Outpost agents module is not enabled, the section says so and no rule can be added.
Troubleshooting: creation refused
When Create refuses a script or a new version, the screen explains why in your language above the form and keeps everything you typed: fix it and save again. The API (POST /api/v1/scripts, POST /api/v1/scripts/{id}/versions) answers 400 (404 for a deleted script, ScriptNotFound) with the stable code (error), an English sentence (message), the translation key (messageKey) and its values (parameters). The technical message stays in the server log. Through the API, a required field that is missing or empty (name, content, parameter name) or an unknown enumeration value given as text is refused earlier, by the standard API validation (400 in the ProblemDetails format).
| Code | Cause | What to do |
|---|---|---|
ScriptNameRequired |
The name is empty | Give the script a name |
ScriptContentRequired |
The content is empty | Write the script |
UnknownScriptEngine |
The engine sent to the API does not exist | Choose an engine from the list (GET /api/v1/scripts/engines) |
UnknownTargetScope |
The target sent to the API does not exist | LocalOnly, AgentsOnly or Both |
InvalidDefaultTimeout |
The default timeout is below 1 second | Enter 1 second or more, or leave it empty |
DefaultTimeoutAboveMaximum |
The default timeout exceeds 24 hours (86,400 seconds) | Enter 86,400 seconds or less |
InvalidDefaultRetryCount |
The number of retries is negative | Enter 0 or more |
DefaultRetryCountAboveMaximum |
The number of retries exceeds 10 | Enter 10 or less |
InvalidGroupConfirmationThreshold |
The confirmation threshold (API) is negative | Enter 0 or more |
DuplicateScriptName |
Another script already has this name (case, accents and surrounding spaces ignored); two simultaneous creations of the same name: the second one gets this refusal | Choose another name |
ScriptContentTooLarge |
The content exceeds 2 MB (size and maximum shown, in bytes) | Shorten the script, or move large data to a file the script reads |
MalformedSecretReference |
A secret reference is badly written | Write {{secret:secret-name}} |
ParameterNameRequired |
A parameter row has no name | Name the parameter or remove the row |
DuplicateParameterName |
Two parameters have the same name (name shown); for PowerShell, upper and lower case count as the same | Keep a single row per name |
InvalidParameterRegex |
The validation regex of the parameter (name shown) is invalid | Fix the regular expression |
InvalidParameterBounds |
The Min of the parameter (name shown) is above its Max | Swap or fix the bounds |
EnumParameterWithoutValues |
An Enum parameter (name shown) has no allowed value |
Enter the values separated by commas |
ScriptNotFound |
The script was deleted while a new version was being written: the screen explains it without showing the form again, the API answers 404 |
Back to the script list |
VersionConflict |
Other versions of the same script were being saved at the same time, several times in a row; the API answers 409 |
Save again |
Content that is too large is always refused with this code, never with a server error about the request size.
Any other error is not a refusal: the screen shows the error page and the API answers 500, without the technical message.
GOLIVE: skipped scripts
During a GOLIVE, every promoted script goes through the same checks as the Create screen: name, bounds of the timeout and of the number of retries, size and secret references of the content, parameters of the versions to add, and a name still free in the target instance. A script that fails them shows up in the preview with a "Script skipped" warning and the reason (for example "another script of this instance already has this name"), followed by the value at fault and, for a version, its number (v3). That script is not applied, nor a process that uses it; the rest of the GOLIVE is. Fix it in the source instance (or rename the script of the target instance), then promote it again.
A script is matched from one instance to another by its identifier, the same everywhere: it is updated, never created again. A script created by hand in each instance is found by its name.
See also
- "Run a script": launching a script and following its result.
- "Monitoring Outpost agents": agents and machine groups.