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
- Click Create Script
- Configure the script:
| Field | Description | Required |
|---|---|---|
| Name | Unique name for the script | Yes |
| Description | What does the script do? | No |
| Language | Interpreter (see below) | Yes |
| Modules | Which modules the script is available for | Yes |
| Script Code | The actual script content | Yes |
| Timeout | Maximum execution time in seconds | No |
| Pre-Hook | Script code executed BEFORE the main script | No |
| Post-Hook | Script code executed AFTER the main script | No |
| Notification | Notification type on execution | No |
Languages
| Language | Interpreter | Platforms |
|---|---|---|
| Bash | /bin/bash | Linux, PVE, PBS, OPNsense (FreeBSD) |
| PowerShell | powershell.exe | Windows |
| Python | python3 (Linux) / python.exe (Windows) | All (if installed) |
| Shell | /bin/sh | Linux, 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.
| Where | Effect |
|---|---|
| Script | default for all runs |
| Job (action Script) | replaces the script default; empty = default |
| Execute dialog | this 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:
| Type | Description |
|---|---|
| None | No notification (default) |
| Email to a configured address | |
| REST | HTTP 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.
| Area | Examples |
|---|---|
| Maintenance | clean up drive C:, sfc /scannow, restore point, power plan, extend partition C: |
| Terminal server | log off all users, list sessions, Teams for all users, pascom client, RDP and RDP UDP |
| Security | Defender scans, list ASR rules, security baseline, BitLocker keys, WDAC driver block list |
| Inventory | serial number, license status, battery health, Windows 11 readiness, check domain trust |
| Software | winget, Chocolatey, DATEV, 2FAST, Quba, Windows 11 upgrade, debloat |
| Checks | antivirus 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
- Right-click on a host → Run Script
- Or: Detail panel → Jobs tab → Run Script
- Select a script from the library
- Click Execute
Bulk Execution
- Select multiple hosts using the checkboxes
- Click Run Script in the bulk action bar
- Select the script
- 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_liveunder Settings > Parameters to0turns 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 -ein 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