Script variables
Since v3.34.0 Control fills in values per host in scripts, pre/post hooks and arguments. One script then works for all customers, and download URLs, license keys or API keys are not stored in the script.
Placeholders
| Placeholder | Value |
|---|---|
{{host.name}}, {{host.hostname}}, {{host.ip}}, {{host.id}} | fields of the host |
{{host.FIELD}} | custom field FIELD of the host (else its default) |
{{kunde.name}}, {{kunde.nummer}}, {{kunde.ort}} | fields of the customer |
{{kunde.NAME}} | customer variable NAME, else the global variable of the same name |
{{global.NAME}} | global variable NAME |
{{standort.name}}, {{standort.adresse}}, {{standort.NAME}} | site of the host or site variable (since v3.38.0) |
{{wazuh.manager}}, {{wazuh.version}}, {{wazuh.gruppe}}, {{wazuh.passwort}} | values for the Wazuh installation from Settings > Wazuh, password as secret (since v3.44.0); {{wazuh.neu_anmelden}} = ja if the host reports the ID of another host (since v3.48.5) |
The Tactical RMM notation works too: {{agent.x}} = {{host.x}}, {{client.x}} = {{kunde.x}}, {{site.name}} (site), {{global.x}}. Upper/lower case of the name does not matter as long as it is unique. Other double braces, e.g. docker ps --format '{{.Names}}', stay unchanged.
Special characters and filters (since v3.65.15)
With a filter Control inserts the value as a complete string of the script language, including quotes:
| Filter | Language | Example | becomes |
|---|---|---|---|
|ps | PowerShell | $k = {{kunde.name|ps}} | $k = 'Müller & Söhne' |
|sh | bash, sh, zsh | K={{kunde.name|sh}} | K='Müller & Söhne' |
|py | Python | k = {{kunde.name|py}} | k = "Müller & Söhne" |
The filter adds the quotes itself, so do not put your own around it.
When the filter is required: host fields, custom fields and customer or site fields ({{host.*}}, {{kunde.name}}, {{kunde.ort}}, {{standort.name}}, {{standort.adresse}} ...) can be changed by users who may not write scripts. If such a value without filter contains one of the characters ` $ " ' \ ; & | < > ( ) { } % ^, a line break or typographic quotes, the script does not start (exit code 3). The message names the placeholder and the characters. In PowerShell \ is allowed (paths). Otherwise such a value could add its own commands to the script, running as SYSTEM or root.
Script variables and secrets ({{kunde.NAME}}, {{global.NAME}}, {{standort.NAME}}) and the {{wazuh.*}} values still work without a filter, e.g. a password in a here-string. Only users who may also manage scripts can change them. In arguments Control quotes the values anyway, a filter has no effect there.
Managing variables
Automation > Script variables (administrators only):
- Tab Global: applies to all customers.
- Tab Customer: applies only to hosts of that customer and overrides a global variable of the same name.
- Clicking the placeholder copies it.
In the script editor the Variables section lists the placeholders the script uses and an overview of all available ones.
Secrets
With Secret switched on, the value is stored encrypted and can no longer be read in the UI. When editing, it is kept as long as the field stays empty.
- The value only goes into the copy of the script that Control builds for the agent at fetch time. The stored task, logs and the audit log keep the placeholder.
- If the value appears in the script output, Control replaces it with
••••••. update.sh/install.shcreate the keySCRIPT_VAULT_KEYin.envonce. It must never change, otherwise stored secrets can no longer be read.
When a value is missing
If a value is missing, the script does not start on that host. The run ends with exit code 3 and the message DATAZONE: Script nicht gestartet - Kein Wert fuer {{kunde.x}} (Kunde ...). For checks, exit code 3 means unknown. An empty value is never inserted silently.
Example
param($Url, $Kunde)
Invoke-WebRequest $Url -OutFile "$env:TEMP\setup.exe"
Start-Process "$env:TEMP\setup.exe" -ArgumentList "/S /CUSTOMER=$Kunde" -WaitScript arguments:
-Url {{kunde.installer_url}}
-Kunde {{kunde.nummer}}