Skip to content

Scripts ​

The script management feature allows you to centrally create, manage, and execute scripts on managed hosts. Scripts can be run individually or as a bulk action on multiple hosts.

Script Library ​

Access the script library via the Scripts navigation item. All available scripts are displayed here.

Adjusting the list ​

  • Column width: Drag the right edge of a column header. Double-click the edge to restore the default width. By default the name takes the remaining space.
  • List next to an open script: Drag the divider between list and script (double-click = default). Long names wrap to two lines, the full name is in the tooltip.
  • The browser remembers your widths.

Creating a Script ​

  1. Click Create Script
  2. Configure the script:
FieldDescriptionRequired
NameUnique name for the scriptYes
DescriptionWhat does the script do?No
LanguageInterpreter (see below)Yes
ModulesWhich modules the script is available forYes
Script CodeThe actual script contentYes
TimeoutMaximum execution time in secondsNo
Pre-HookScript code executed BEFORE the main scriptNo
Post-HookScript code executed AFTER the main scriptNo
NotificationNotification type on executionNo

Languages ​

LanguageInterpreterPlatforms
Bash/bin/bashLinux, PVE, PBS, OPNsense (FreeBSD)
PowerShellpowershell.exeWindows
Pythonpython3 (Linux) / python.exe (Windows)All (if installed)
Shell/bin/shLinux, FreeBSD

Module Assignment ​

A script can be assigned to one or more modules:

  • All - Available in all modules
  • OPNsense - Bash/Shell scripts for FreeBSD
  • Proxmox VE - Bash scripts for Debian
  • Proxmox Backup Server - Bash scripts for Debian
  • Linux - Bash scripts for all distributions
  • Windows - PowerShell scripts

Timeout ​

Each script can have an individual timeout:

  • Default: 5 minutes (300 seconds) if no timeout is specified
  • If the timeout is exceeded, the script process is terminated
  • For long-running operations, a higher value can be set

Arguments (since v3.34.0) ​

A script can have default arguments (editor, right column). One entry per line, split like a shell: -Url "https://example.com/a b.exe" gives two arguments. Placeholders like {{kunde.nummer}} are allowed, see Script variables.

WhereEffect
Scriptdefault for all runs
Job (action Script)replaces the script default; empty = default
Execute dialogthis run only; prefilled with the default, empty = no arguments

Control inserts the arguments into the script when the agent fetches it, no new agent needed: PowerShell receives them like -Parameter Value (a param() block works), sh/bash/zsh via set -- ($1, $2, "$@"), Python via sys.argv, Perl via @ARGV.

Pre-Hook / Post-Hook ​

Hooks are additional script blocks that are executed before or after the main script:

Pre-Hook (before the script):

  • Typical: Stop services, create backup, enable maintenance mode
  • Executed in the same language as the main script

Post-Hook (after the script):

  • Typical: Start services, cleanup tasks, notifications
  • Also executed when the main script fails

Notifications ​

After script execution, a notification can be sent:

TypeDescription
NoneNo notification (default)
EmailEmail to a configured address
RESTHTTP request to a URL (webhook)

For type Email, enter the recipient address; for REST, enter the webhook URL.

Script Editor ​

The integrated script editor provides:

  • Syntax highlighting for Bash, PowerShell, and Python
  • Line numbering
  • Tab indentation
  • Scroll synchronization

Script library (since v3.43.0) ​

Control ships about 50 tested Windows scripts (from the Tactical migration, cleaned up and converted to PowerShell). Each update creates them once; afterwards they are normal scripts: edit, copy, delete. Deleted ones do not come back, a script with the same name is not overwritten.

AreaExamples
Maintenanceclean up drive C:, sfc /scannow, restore point, power plan, extend partition C:
Terminal serverlog off all users, list sessions, Teams for all users, pascom client, RDP and RDP UDP
SecurityDefender scans, list ASR rules, security baseline, BitLocker keys, WDAC driver block list
Inventoryserial number, license status, battery health, Windows 11 readiness, check domain trust
Softwarewinget, Chocolatey, DATEV, 2FAST, Quba, Windows 11 upgrade, debloat
Checksantivirus active, Defender without detections, disk errors, Zabbix agent, Secure Boot 2023

Test before first use

Security baseline (all ASR rules set to block), WDAC driver block list (effective after reboot), Extend partition C: (default -DryRun) and Debloat (fresh workstations only) change the system deeply. Run them on a test machine first.

Since v3.43.0 the agent receives PowerShell scripts containing umlauts with a UTF-8 marker (BOM). Windows PowerShell 5.1 previously read them as ANSI; umlauts and dashes could cause syntax errors.

Executing Scripts ​

Single Execution ​

  1. Right-click on a host → Run Script
  2. Or: Detail panel → Jobs tab → Run Script
  3. Select a script from the library
  4. Click Execute

Bulk Execution ​

  1. Select multiple hosts using the checkboxes
  2. Click Run Script in the bulk action bar
  3. Select the script
  4. Confirm the execution

The script is started in parallel on all selected hosts.

Results ​

Single Result ​

After execution, the result is displayed:

  • Exit code (0 = success, >0 = error)
  • Stdout - Standard output
  • Stderr - Error output
  • Execution duration
  • Timestamp

Execution History ​

Under Scripts > History tab, you can find all previous script executions with:

  • Host, script name, timestamp
  • Exit code and status
  • Output for reference

Output and complete log (since v3.75.0) ​

Scripts may produce a lot of output without loading the server. With agent 3.75.0:

  • Live view: as long as you have a running task expanded, the agent sends the newest output every second. Without a viewer it sends only the last lines every 30 seconds (like GitLab runners) - so even thousands of scripts at once hardly load the server. With very much output the live view shows the end, skipped parts are marked. The final result is still complete.
  • Final result up to 2 MB: stored completely in the task and the history, as before.
  • Final result over 2 MB: the task shows the start and the end, below it the button Download complete log. The complete log is kept for 90 days.
  • Limit 200 MB per log: if a script runs out of control, the first 50 MB and the last ~150 MB are kept. The log states how much is missing in between.
  • Interrupted run (machine off, agent restarted): the agent delivers a partial log up to that point when it reconnects.
  • Passwords from script variables and secret custom fields are masked in the live view, the result and the complete log.

Many machines at once ​

Machines with agent 3.75.0 or later all run at the same time, even thousands. Only machines with an older agent start at most 20 scripts per job at the same time, the rest follow as soon as one has finished (job_max_parallel under Settings > Parameters, 0 = no limit). Complete logs use at most task_log_max_gb together (default 5 GB compressed; at least 5 GB always stay free).

Hint in the script editor ​

The editor warns when a script probably reports every file on its own, e.g. Remove-Item ... -Verbose, robocopy without /NFL /NDL, set -x or rm -v. Better print a summary at the end ("1,234 files, 2.3 GB removed").

Emergency switch and alarm ​

  • Setting task_output_live under Settings > Parameters to 0 turns off the live output of all scripts. Final results and complete logs still arrive.
  • If a large share of the server agents disappears within 15 minutes (default 25 %, at least 20 agents; workstations and Macs do not count), an alarm goes to all active notification channels. The same happens when the realtime service does not answer for 3 minutes. Threshold: platform_alert_offline_pct (0 = off).

Older agents ​

Agents before 3.75.0 send the whole output so far with every line. The server protects itself: from 32 KB of script output such an agent gets no live view any more and is not accepted for 2 minutes. It stays online, the final result arrives at the end. Large final results are stored as a complete log by the server. On the machine itself the script stays slow with the old agent, only the agent update fixes that.

Versioning ​

Scripts are automatically versioned:

  • Each change creates a new version with an optional change description
  • Older versions are preserved
  • The current version is used when executing

System Scripts ​

DATAZONE Control includes predefined system scripts for common tasks:

  • Update scripts (per module and OS)
  • Reboot scripts
  • Service checks
  • Information gathering
  • Agent update scripts
  • OPNsense IPsec MSS clamping check and enable (see OPNsense)

System scripts are marked with a lock icon and cannot be edited or deleted. They serve as templates and references for your own scripts.

Best Practices ​

Recommendations

  • Error handling: Use set -e in Bash scripts for immediate termination on errors
  • Logging: Output meaningful messages to stdout
  • Idempotency: Scripts should be safe to run multiple times without side effects
  • Timeouts: Set appropriate timeouts for long-running scripts
  • Pre-/Post-Hooks: Use hooks for preparation/cleanup instead of putting everything in one script

DATAZONE Control Documentation