Playbooks

Playbooks are multi-step workflows that execute multiple scripts and tasks sequentially on hosts. A typical use case is a maintenance window with snapshot, update, reboot, and health check as consecutive steps.

Concept

A playbook consists of:

1. Definition - Name, description, and target module
2. Steps - Ordered list of actions (script, task, or wait)
3. Error Handling - Configurable per step (stop or continue)

Step Types

Type	Description	Configuration
Script	Execute a script from the library	Script selection, optional timeout
Task	Execute a system task (update, reboot, etc.)	Task type + parameters
Wait	Pause between steps	Duration in seconds
Wake on LAN	Send magic packet to a host	Automatic MAC + proxy detection
Check Online	Wait until a host is online	Timeout + poll interval
VM Snapshot	Create a PVE snapshot of a VM	VMID + snapshot name
Webhook	Send an HTTP request to a URL	URL, method, body, headers

Error Handling (On-Error)

For each step, you can define what happens when an error occurs:

Option	Behavior
stop	Playbook is immediately stopped (default)
continue	Next step is executed despite the error

Timeout per Step

Each step can have an individual timeout (default: 300 seconds). If the timeout is exceeded, the step is considered failed and the configured error handling takes effect.

Available Task Types

The following task types are available for playbook steps of type "Task":

General (all modules)

Task Type	Description
AGENT_UPDATE	Update agent to the latest version
RUN_SCRIPT	Execute a script from the library
REBOOT	Reboot the system

OPNsense

Task Type	Description
system_update	OPNsense firmware update
update_reboot	Firmware update with reboot
OPN_REBOOT	Reboot OPNsense
OPN_UPGRADE_CHECK	Check major upgrade availability
OPN_MAJOR_UPGRADE	Perform major upgrade
BACKUP	Create configuration backup
SYNC_CONFIG	Synchronize HA configuration

Proxmox VE

Task Type	Description
PVE_UPDATE	Package update (apt dist-upgrade)
PVE_REBOOT	Reboot PVE host
PVE_UPGRADE_CHECK	Check major upgrade availability
PVE_MAJOR_UPGRADE	Perform major upgrade
PVE_VM_START	Start VM
PVE_VM_STOP	Stop VM (hard)
PVE_VM_SHUTDOWN	Shut down VM (ACPI)
PVE_VM_REBOOT	Reboot VM
PVE_SNAPSHOT	Create VM snapshot
PVE_SNAPSHOT_DELETE	Delete VM snapshot

Proxmox Backup Server

Task Type	Description
PBS_UPDATE	Package update (apt dist-upgrade)
PBS_REBOOT	Reboot PBS host
PBS_UPGRADE_CHECK	Check major upgrade availability
PBS_MAJOR_UPGRADE	Perform major upgrade
PBS_GC	Garbage collection on datastore
PBS_VERIFY	Verify backup integrity
PBS_PRUNE	Prune old backups
PBS_SYNC	Synchronize datastore

Linux

Task Type	Description
LINUX_UPDATE	Package update (apt upgrade / dnf upgrade)

Windows

Task Type	Description
WINDOWS_UPDATE	Install Windows updates

Webhook Step

The Webhook step type sends an HTTP request to any URL. This allows triggering external systems like DATAZONE Connect, Slack, Teams, or other REST APIs.

Field	Description	Default
URL	Target URL for the HTTP request	-
Method	HTTP method (GET, POST, PUT, DELETE)	POST
Body	Request body (JSON) with placeholders	-
Headers	HTTP headers (e.g., Content-Type)	-
Timeout	Maximum wait time in seconds	30s
Success Codes	Expected HTTP status codes	2xx

Variable Placeholders

The following placeholders can be used in the body and URL, and are automatically replaced with data from the current host:

Placeholder	Description
{hostname}	Hostname of the target host
{ip}	IP address of the host
{module}	Module type (linux, windows, opnsense, etc.)
{host_id}	Host ID in DATAZONE Control
{customer_name}	Customer name
{customer_number}	Customer number
{playbook_name}	Playbook name
{step_number}	Current step number
{date}	Current date (YYYY-MM-DD)

Connect Integration

Webhook steps are ideal for connecting to DATAZONE Connect. This enables automatic creation of activity reports in Nuclos or sending Teams notifications, for example.

Managing Playbooks

Access playbook management via the Playbooks navigation item.

Creating a Playbook

1. Click Create Playbook
2. Configure the playbook:

Field	Description
Name	Unique name for the playbook
Description	Purpose and workflow
Module	Target module (or all)
Active	Whether the playbook can be executed

Configuring Steps

In the step editor, you can add, edit, and reorder steps via drag-and-drop:

1. Click Add Step
2. Select the step type (Script / Task / Wait)
3. Configure the step:
   • Script: Select a script from the library (filtered by playbook module)
   • Task: Select a task type from the list (see above)
   • Wait: Enter the pause duration in seconds
4. Set the error behavior (stop / continue)
5. Optional: Define a timeout per step (default: 300 seconds)

Reordering Steps

Steps can be reordered via drag-and-drop or using the arrow buttons. Step numbers are automatically adjusted.

Per-Step Target Override

By default, all steps are executed on the host for which the playbook was started. With the Different Target option, a step can be executed on a different host or even a different module.

This is particularly useful for cross-module workflows:

• WoL a Windows host that runs as a VM on a PVE host
• Snapshot on the PVE host before updating the Windows host
• Check online another host after sending a WoL packet

Enable the Different Target checkbox in the step editor to select a different module and host.

VM Snapshot Step

The VM Snapshot step type creates a snapshot of a virtual machine on a PVE host:

Field	Description
VMID	ID of the virtual machine (e.g., 100)
Snapshot Name	Name of the snapshot, {date} is replaced with the current date
Include RAM	Include VM memory in the snapshot

Placeholders

The snapshot name supports the {date} placeholder, which is automatically replaced with the current date in YYYYMMDD-HHMMSS format. Example: playbook-{date} becomes playbook-20260213-030000.

Check Online Step

The Check Online step type waits until a host is online (e.g., after a WoL packet or reboot):

Field	Description	Default
Timeout	Maximum wait time in seconds	300s

The step checks every 10 seconds whether the host is reachable. If the timeout expires, the configured error handling mode is applied.

Executing a Playbook

Via Playbook Management

1. Open the playbook in the list
2. Click Execute
3. Select the target module and hosts
4. Confirm the execution

Via Context Menu

1. Right-click on a host in the host table
2. Select Run Playbook
3. Choose the desired playbook from the submenu

Via Schedules (Jobs)

Playbooks can be configured as scheduled actions in update schedules:

1. Create a new job under Jobs
2. Select Playbook as the action type
3. Choose the playbook from the dropdown list
4. Configure the schedule and target hosts

Monitoring Execution

Running Executions

Under Playbooks > Executions tab, you can see all running and completed executions:

Column	Description
Playbook	Name of the executed playbook
Host	Target host
Status	Running, Success, Failed, or Stopped
Current Step	Which step is currently being executed
Progress	Visual progress bar
Started	Start time of the execution

Step Results

Click on an execution to open the detail view:

• Each step is displayed with a status badge (Success / Failed / Running / Skipped)
• Output and duration per step
• On errors: Which on-error action was triggered

Stopping an Execution

Running executions can be stopped at any time:

1. Open the execution
2. Click Stop
3. The current step will still complete, then the playbook stops

Examples

PVE Maintenance Window

A typical playbook for Proxmox VE maintenance:

Step	Type	Action	On Error	Timeout
1	Script	Create VM snapshots	stop	600s
2	Task	PVE_UPDATE	continue	1800s
3	Wait	Wait 30 seconds	-	-
4	Script	Health check	continue	120s
5	Task	PVE_REBOOT	stop	300s
6	Script	Send notification	continue	60s

Windows Update with PVE Snapshot Protection

A cross-module playbook: wake up a Windows host, protect it, and update it:

Step	Type	Target	Action	On Error
1	Wake on LAN	Windows host	Wake up host	stop
2	Check Online	Windows host	Wait until online (max 5 min)	stop
3	VM Snapshot	PVE host	Snapshot VM 100	stop
4	Task	Windows host	Windows Update	continue
5	Check Online	Windows host	Wait after reboot (max 10 min)	continue

Cross-Module

In this example, the playbook is started on the Windows host. Step 3 uses Different Target to create the snapshot on the PVE host where the VM runs.

Best Practices

• Snapshots first: Always create a snapshot before critical changes
• Include health checks: Verify that the system functions properly after updates
• Check online after WoL: Use the check_online step after Wake-on-LAN
• Notifications: Use the last step for status messages
• Timeouts: Set appropriate timeouts to detect hanging steps
• Error handling: Use continue for non-critical steps and stop for critical ones