Agent Installation

The DATAZONE Control Agent is installed via an automatic onboarding script. A dedicated installation command is available for each platform.

Prerequisites

Onboarding Token - Generate a token under Settings > Onboarding
Network Access - The host must be able to reach the DATAZONE Control server via HTTPS
Root/Admin Privileges - Installation requires administrator privileges

Linux Installation

Automatic (Recommended)

Run the following command as root:

bash

curl -sSL https://control.yourdomain.com/agent/linux-install.sh | bash -s -- --token YOUR_TOKEN

Token and URL

The correct command with a pre-filled token is displayed in the web interface when you add a new host (click Install Agent in the Linux module).

This performs the following steps:

Download the agent binary (datazone-agent-linux-amd64 or arm64)
Install to /usr/local/bin/datazone-agent
Create configuration in /etc/datazone/agent.json
Set up and start the systemd service

Manual

Download the binary:

bash

curl -sSL -o /usr/local/bin/datazone-agent https://control.yourdomain.com/agent/datazone-agent-linux-amd64
chmod +x /usr/local/bin/datazone-agent

Create the configuration:

bash

mkdir -p /etc/datazone
cat > /etc/datazone/agent.json << EOF
{
  "server_url": "wss://control.yourdomain.com",
  "agent_token": "YOUR_TOKEN",
  "agent_type": "linux",
  "log_level": "info"
}
EOF

Create the systemd service:

bash

cat > /etc/systemd/system/datazone-agent.service << EOF
[Unit]
Description=DATAZONE Control Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/datazone-agent
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable datazone-agent
systemctl start datazone-agent

Installation Paths

Component	Path
Binary	`/usr/local/bin/datazone-agent`
Configuration	`/etc/datazone/agent.json`
Service	`/etc/systemd/system/datazone-agent.service`
Update Log	`/var/log/datazone-agent-update.log`

Proxmox VE Installation

Automatic (Recommended)

Run the following command as root on the Proxmox VE host:

bash

curl -sSL https://control.yourdomain.com/agent/pve-install.sh | bash -s -- --token YOUR_TOKEN

The script automatically detects the Proxmox VE environment and configures the agent accordingly.

Manual

Manual installation is identical to the Linux installation, but the agent_type must be set to pve:

json

{
  "server_url": "wss://control.yourdomain.com",
  "agent_token": "YOUR_TOKEN",
  "agent_type": "pve",
  "log_level": "info"
}

Installation Paths

Identical to Linux (see above).

Proxmox PBS Installation

Automatic (Recommended)

Run the following command as root on the Proxmox Backup Server:

bash

curl -sSL https://control.yourdomain.com/agent/pbs-install.sh | bash -s -- --token YOUR_TOKEN

Manual

Manual installation is identical to the Linux installation, but the agent_type must be set to pbs:

json

{
  "server_url": "wss://control.yourdomain.com",
  "agent_token": "YOUR_TOKEN",
  "agent_type": "pbs",
  "log_level": "info"
}

Installation Paths

Identical to Linux (see above).

Windows Installation

Automatic (Recommended)

Open a PowerShell as Administrator and run:

powershell

irm https://control.yourdomain.com/agent/windows-install.ps1 | iex; Install-DatazoneAgent -Token "YOUR_TOKEN"

Token and URL

The correct command with a pre-filled token is displayed in the web interface when you add a new host (click Install Agent in the Windows module).

This performs the following steps:

Download the agent binary and updater
Install to C:\Program Files\DATAZONE\Agent\
Create configuration in C:\ProgramData\DATAZONE\agent.json
Set up and start the Windows service

Manual

Download the binary and copy it to C:\Program Files\DATAZONE\Agent\datazone-agent.exe
Create the configuration in C:\ProgramData\DATAZONE\agent.json:

json

{
  "server_url": "wss://control.yourdomain.com",
  "agent_token": "YOUR_TOKEN",
  "agent_type": "windows",
  "hostname": "HOSTNAME",
  "heartbeat_interval": 60,
  "log_file": "C:\\ProgramData\\DATAZONE\\logs\\agent.log"
}

powershell

New-Service -Name "datazone-agent" -BinaryPathName "C:\Program Files\DATAZONE\Agent\datazone-agent.exe" -DisplayName "DATAZONE Control Agent" -StartupType Automatic
Start-Service datazone-agent

Installation Paths

Component	Path
Binary	`C:\Program Files\DATAZONE\Agent\datazone-agent.exe`
Updater	`C:\Program Files\DATAZONE\Agent\datazone-updater.exe`
Configuration	`C:\ProgramData\DATAZONE\agent.json`
Logs	`C:\ProgramData\DATAZONE\logs\`

OPNsense Installation

Automatic (Recommended)

Run the following in the OPNsense shell as root:

bash

fetch --no-verify-peer -o /tmp/install-plugin.sh https://control.yourdomain.com/agent/install-plugin.sh && sh /tmp/install-plugin.sh --token YOUR_TOKEN

Token and URL

The correct command with a pre-filled token is displayed in the web interface when you add a new firewall (click Install Agent in the OPNsense module).

SSL Certificate

The --no-verify-peer flag is necessary because OPNsense (FreeBSD) often does not have an up-to-date CA root bundle and cannot verify the SSL certificate otherwise. Authenticity is ensured through the onboarding token.

This performs the following steps:

Download the agent binary (datazone-agent-freebsd-amd64)
Install to /usr/local/opnsense/scripts/datazone-agent/
Create configuration in /usr/local/etc/datazone-agent.json
Set up and start the rc.d service
Automatically remove old Python agent remnants (if present)

Manual

Download the FreeBSD binary:

bash

fetch --no-verify-peer -o /usr/local/opnsense/scripts/datazone-agent/datazone-agent https://control.yourdomain.com/agent/datazone-agent-freebsd-amd64
chmod +x /usr/local/opnsense/scripts/datazone-agent/datazone-agent

Create the configuration:

bash

cat > /usr/local/etc/datazone-agent.json << EOF
{
  "server_url": "https://control.yourdomain.com",
  "agent_token": "YOUR_TOKEN",
  "agent_type": "opnsense"
}
EOF

Set up the rc.d service (automatically created by the install script)

Installation Paths

Component	Path
Binary	`/usr/local/opnsense/scripts/datazone-agent/datazone-agent`
Configuration	`/usr/local/etc/datazone-agent.json`
rc.d Script	`/usr/local/etc/rc.d/datazone_agent`
Log	`/var/log/datazone-agent.log`
PID (Daemon)	`/var/run/datazone-daemon.pid`
PID (Agent)	`/var/run/datazone-agent.pid`

Onboarding (Self-Registration)

The onboarding mechanism allows hosts to register themselves without requiring a pre-generated individual token. Instead, a single master token is used.

Prerequisites

Generate a master token under Settings > Onboarding
The master token authorizes self-registration of any number of hosts

Linux / PVE / PBS Onboarding

bash

curl -sSL https://control.yourdomain.com/agent/onboarding.sh | bash -s -- --master-token YOUR_MASTER_TOKEN

Optional Parameters:

Parameter	Description	Default
`--master-token`	Master token for registration (required)	-
`--agent-type`	Agent type: `linux`, `pve`, `pbs`	`linux`
`--customer-number`	Customer number for assignment	`ONBOARDING`

Examples:

bash

# Register Linux server with customer K-001
curl -sSL https://control.yourdomain.com/agent/onboarding.sh | bash -s -- \
  --master-token YOUR_TOKEN --agent-type linux --customer-number K-001

# PVE host without customer assignment (assigned to "Onboarding")
curl -sSL https://control.yourdomain.com/agent/onboarding.sh | bash -s -- \
  --master-token YOUR_TOKEN --agent-type pve

Windows Onboarding

Open a PowerShell as Administrator and run:

powershell

irm https://control.yourdomain.com/agent/onboarding.ps1 | iex; Install-DatazoneOnboarding -MasterToken "YOUR_MASTER_TOKEN"

Optional Parameters:

Parameter	Description	Default
`-MasterToken`	Master token for registration (required)	-
`-CustomerNumber`	Customer number for assignment	`ONBOARDING`
`-SkipRustDesk`	Skip RustDesk installation	No

Example with customer assignment:

powershell

irm https://control.yourdomain.com/agent/onboarding.ps1 | iex; Install-DatazoneOnboarding -MasterToken "YOUR_TOKEN" -CustomerNumber "K-001"

Process

The script sends the master token to the API and receives an individual agent token
The host is automatically created in the system (under the specified customer or "Onboarding")
Agent binary is downloaded and installed
Service is configured and started
The host appears in the corresponding module within a few seconds

Customer Number

The customer number corresponds to the Customer Number field in customer management. If no customer number is provided, the host is assigned to the special "ONBOARDING" customer and can be moved manually later.

Via the Web Interface

DATAZONE Control displays an Install Agent button for each module type that provides the appropriate installation command with pre-filled token and server URL:

Navigate to the desired module (OPNsense, Proxmox VE, PBS, Linux, or Windows)
Click the Install Agent button
Copy the displayed command
Run it on the target host

Agent Update

Automatic

The agent can update itself via the backend:

Open a host in the detail modal
Go to the Agent tab
Click Update Agent

The agent checks for available updates every 5 minutes. Alternatively, an update can be triggered immediately via the web interface.

Manual

Replace the binary and restart the service:

bash

# Linux / PVE / PBS
systemctl stop datazone-agent
cp new-binary /usr/local/bin/datazone-agent
systemctl start datazone-agent

powershell

# Windows
Stop-Service datazone-agent
Copy-Item new-binary.exe "C:\Program Files\DATAZONE\Agent\datazone-agent.exe"
Start-Service datazone-agent

bash

# OPNsense
service datazone_agent stop
cp new-binary /usr/local/opnsense/scripts/datazone-agent/datazone-agent
service datazone_agent start

Agent Uninstallation

Linux / Proxmox VE / Proxmox PBS

bash

# 1. Stop and disable the service
sudo systemctl stop datazone-agent
sudo systemctl disable datazone-agent

# 2. Remove service file
sudo rm /etc/systemd/system/datazone-agent.service
sudo systemctl daemon-reload

# 3. Remove binary
sudo rm /usr/local/bin/datazone-agent

# 4. Remove configuration
sudo rm -rf /etc/datazone/

# 5. Remove log files (optional)
sudo rm -f /var/log/datazone-agent-update.log
sudo rm -f /var/log/datazone-agent-pending.json

Windows

Automatic (Recommended)

Open a PowerShell as Administrator and run:

powershell

irm https://control.yourdomain.com/agent/windows-uninstall.ps1 | iex; Uninstall-DatazoneAgent

If RustDesk is installed and should be kept:

powershell

irm https://control.yourdomain.com/agent/windows-uninstall.ps1 | iex; Uninstall-DatazoneAgent -KeepRustDesk

The script performs the following steps:

Stop and remove the Windows service
Delete the installation directory C:\Program Files\DATAZONE\
Delete the data directory C:\ProgramData\DATAZONE\
Optionally: Uninstall RustDesk (default: yes)

Manual

powershell

# 1. Stop the service
Stop-Service -Name "datazone-agent" -Force

# 2. Kill process (if still running)
Stop-Process -Name "datazone-agent" -Force -ErrorAction SilentlyContinue

# 3. Remove the Windows service
sc.exe delete "datazone-agent"

# 4. Remove installation directory
Remove-Item -Recurse -Force "C:\Program Files\DATAZONE\"

# 5. Remove data and configuration
Remove-Item -Recurse -Force "C:\ProgramData\DATAZONE\"

OPNsense (FreeBSD)

bash

# 1. Stop the service
service datazone_agent stop

# 2. Disable autostart
sysrc -f /etc/rc.conf.d/datazone_agent datazone_agent_enable=NO

# 3. Remove rc.d script
rm /usr/local/etc/rc.d/datazone_agent

# 4. Remove binary
rm /usr/local/opnsense/scripts/datazone-agent/datazone-agent

# 5. Remove configuration
rm /usr/local/etc/datazone-agent.json

# 6. Remove log and PID files (optional)
rm -f /var/log/datazone-agent.log
rm -f /var/run/datazone-daemon.pid
rm -f /var/run/datazone-agent.pid

Host in DATAZONE Control

Uninstalling the agent does not remove the host from DATAZONE Control. To also remove the host from the web interface, use the Delete tab in the host's detail modal.

Next Steps

After installation, the host should appear in the corresponding module within a few seconds. If not, refer to the Troubleshooting guide.

Agent Installation ​

Prerequisites ​

Linux Installation ​

Automatic (Recommended) ​

Manual ​

Installation Paths ​

Proxmox VE Installation ​

Automatic (Recommended) ​

Manual ​

Installation Paths ​

Proxmox PBS Installation ​

Automatic (Recommended) ​

Manual ​

Installation Paths ​

Windows Installation ​

Automatic (Recommended) ​

Manual ​

Installation Paths ​

OPNsense Installation ​

Automatic (Recommended) ​

Manual ​

Installation Paths ​

Onboarding (Self-Registration) ​

Prerequisites ​

Linux / PVE / PBS Onboarding ​

Windows Onboarding ​

Process ​

Via the Web Interface ​

Agent Update ​

Automatic ​

Manual ​

Agent Uninstallation ​

Linux / Proxmox VE / Proxmox PBS ​

Windows ​

Automatic (Recommended) ​

Manual ​

OPNsense (FreeBSD) ​

Next Steps ​

Agent Installation

Prerequisites

Linux Installation

Automatic (Recommended)

Manual

Installation Paths

Proxmox VE Installation

Automatic (Recommended)

Manual

Installation Paths

Proxmox PBS Installation

Automatic (Recommended)

Manual

Installation Paths

Windows Installation

Automatic (Recommended)

Manual

Installation Paths

OPNsense Installation

Automatic (Recommended)

Manual

Installation Paths

Onboarding (Self-Registration)

Prerequisites

Linux / PVE / PBS Onboarding

Windows Onboarding

Process

Via the Web Interface

Agent Update

Automatic

Manual

Agent Uninstallation

Linux / Proxmox VE / Proxmox PBS

Windows

Automatic (Recommended)

Manual

OPNsense (FreeBSD)

Next Steps