Overview

As I mentioned on my previous post, we'll be automating the autoregistration process so any new agent that comes online registers itself with the Zabbix server, gets placed in the right host group, and has the right templates linked.

This guide assumes that you are capable of deploying a virtual machine on your own and that you already have a working agent install (manual or scripted from the previous post).

The flow we are building looks like this:

  1. The agent starts and sends an active check request to the proxy/server.
  2. The agent identifies itself with a HostMetadata value (e.g. windows-prod, linux-db).
  3. The Zabbix server matches the metadata against an autoregistration action and: creates the host, assigns it to a host group, links the relevant templates.

The two pieces you control on the agent side are HostMetadata (what the host says it is) and ServerActive (where the host reports to). Everything else is configured once on the server.

Server-Side: Create the Autoregistration Action

Before any agent registers, the server needs an action that knows what to do.

Go to Alerts -> Actions -> Autoregistration actions -> Create action.

1. Action Tab

  • Name: Auto-register Windows hosts
  • Conditions: add a new condition Type: Host metadata Operator: contains Value: windows

2. Operations Tab

Add the following operations:

  • Add host
  • Add to host groups: Windows servers
  • Link to templates: Windows by Zabbix agent
  • (Optional) Set host inventory mode: Automatic

Repeat the same flow for Linux:

  • Name: Auto-register Linux hosts
  • Host metadata contains: linux
  • Add to host groups: Linux servers
  • Link to templates: Linux by Zabbix agent

Use contains instead of equals so you can use compound metadata like windows-prod-iis and still match on windows. This makes it easy to add more granular actions later without rewriting the existing ones.

Windows: Configure HostMetadata

The agent must include a HostMetadata (or HostMetadataItem) value that the action above can match.

1. Manual Edit

Edit C:\Program Files\Zabbix Agent\zabbix_agentd.conf and set:

ServerActive=10.0.0.246
HostMetadata=windows-prod
HostnameItem=system.hostname

Then restart the service:

Restart-Service 'Zabbix Agent'

2. Powershell Automation

The script below patches the config file in place and restarts the service. It is safe to run multiple times it replaces the existing line if present, appends it otherwise.

<#
.SYNOPSIS
    Configures the Zabbix Agent 2 for autoregistration and restarts the service.
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [string]$ServerActive,                         # e.g. 10.0.0.246

    [Parameter(Mandatory = $true)]
    [ValidateNotNullOrEmpty()]
    [string]$HostMetadata,                         # e.g. windows-prod

    [string]$ConfigPath  = 'C:\Program Files\Zabbix Agent\zabbix_agentd.conf',
    [string]$ServiceName = 'Zabbix Agent'
)

$ErrorActionPreference = 'Stop'

if (-not (Test-Path $ConfigPath))
{
    throw "Config not found: $ConfigPath"
}

function Set-ConfigValue
{
    param([string[]]$Lines, [string]$Key, [string]$Value)

    $pattern = "^\s*#?\s*$Key\s*="
    $newLine = "$Key=$Value"

    if ($Lines -match $pattern)
    {
        return $Lines -replace $pattern + '.*', $newLine
    }
    return $Lines + $newLine
}

$lines = Get-Content $ConfigPath
$lines = Set-ConfigValue -Lines $lines -Key 'ServerActive' -Value $ServerActive
$lines = Set-ConfigValue -Lines $lines -Key 'HostMetadata' -Value $HostMetadata
$lines = Set-ConfigValue -Lines $lines -Key 'HostnameItem' -Value 'system.hostname'

Set-Content -Path $ConfigPath -Value $lines -Encoding ASCII

Write-Verbose "Restarting $ServiceName"
Restart-Service -Name $ServiceName

Write-Verbose "Done. Agent will register on next active check (~120s)."

Run it like so:

.\Set-ZabbixAutoregistration.ps1 -ServerActive '10.0.0.246' -HostMetadata 'windows-prod' -Verbose

3. Verify Registration

Within a couple of minutes, the new host should appear under Monitoring -> Hosts. From the Windows side you can confirm the agent is talking to the server with:

& 'C:\Program Files\Zabbix Agent\zabbix_agentd.exe' -t agent.ping
Get-Content 'C:\Program Files\Zabbix Agent\zabbix_agentd.log' -Tail 20

The log will contain a line similar to:

agent #12 started [active checks #1]

If you don't see registration on the server, double check:

  • The HostMetadata value matches the action condition (contains windows).
  • ServerActive points to the proxy/server, not the passive Server value.
  • Firewall allows outbound 10051 from the agent.

Linux: Configure HostMetadata

The Linux agent uses the same two settings, just in /etc/zabbix/zabbix_agentd.conf.

1. Manual Edit

ServerActive=10.0.0.246
HostMetadata=linux-prod
HostnameItem=system.hostname

sudo systemctl restart zabbix-agent

2. Bash Automation

#!/usr/bin/env bash
set -euo pipefail

SERVER_ACTIVE="${1:-10.0.0.246}"
HOST_METADATA="${2:-linux-prod}"
CONFIG="/etc/zabbix/zabbix_agentd.conf"

set_value() {
    local key="$1" value="$2"
    if grep -qE "^\s*#?\s*${key}\s*=" "$CONFIG"; then
        sudo sed -i -E "s|^\s*#?\s*${key}\s*=.*|${key}=${value}|" "$CONFIG"
    else
        echo "${key}=${value}" | sudo tee -a "$CONFIG" >/dev/null
    fi
}

set_value 'ServerActive' "$SERVER_ACTIVE"
set_value 'HostMetadata' "$HOST_METADATA"
set_value 'HostnameItem' 'system.hostname'

sudo systemctl restart zabbix-agent2

Run it as:

./set-zabbix-autoreg.sh 10.0.0.246 linux-prod

3. Verify Registration

zabbix_agent2 -t agent.ping
sudo tail -n 20 /var/log/zabbix/zabbix_agentd.log

You should see the same active check configuration update from ... line in the log, and the host will show up on the server within ~120 seconds.

What to Do Next

With one autoregistration action per platform and the right HostMetadata baked into your provisioning scripts, every new VM you build will end up monitored, grouped, and templated without anyone touching the Zabbix UI. The pattern that wins is: encode role, environment, and OS family into HostMetadata at provisioning time, then let server-side actions decide grouping and templating from that string.

Three concrete moves to roll this out this week:

  1. Pick one OS family and one autoregistration action. Don't try to autoregister everything on day one. Get Linux working end to end (provision -> agent comes up -> host appears -> templates apply) before you touch Windows or proxies.
  2. Bake HostMetadata into the cloud-init or unattended template. Hard-coded metadata in zabbix_agentd.conf defeats the purpose. Read it from instance tags, an inventory file, or the hostname pattern so a new role only requires a tag change, not an agent reconfig.
  3. Add a Disable host step to the action for off-hours registrations. Hosts that come up at 2 AM during a deploy shouldn't auto-page. Register them disabled, let humans flip them on the next morning. Cheaper than the false-positive postmortem.

Pairs naturally with the Low-Level Discovery post (so once a host registers, its disks and services discover themselves) and the PSK and TLS post (so the autoregistration handshake isn't the soft underbelly of an otherwise-encrypted fleet).