Zabbix Active Agent Autoregistration

Let’s see how the Zabbix active agent autoregistration works in the communication.

I have configured the Zabbix agent (version 6.2.3) on the Linux host at 192.168.7.17 with this configuration:

ServerActive=192.168.7.15
Hostname=Test-agent

After restarting the agent, the Zabbix server (version 6.2.3) at 192.168.7.15 logged immediately in /var/log/zabbix/zabbix_server.log:

cannot send list of active checks to "192.168.7.17": host [Test-agent] not found

This happens every two minutes, which is the default RefreshActiveChecks configuration value (120 seconds) in the Zabbix agent.

There is no autoregistration yet because the Zabbix server is not configured with any autoregistration actions.

Let’s first see how the traffic from the active agent looks like. I used tcpdump on the Zabbix server (sudo tcpdump -v -w test-agent-no-host.pcap host 192.168.7.17), and then opened the capture file in Wireshark with the Zabbix dissectors installed. These were the packets when filtered with “zabbix” protocol:

The agent started with a heartbeat message. That’s starting with Zabbix 6.2.0, I’m using agent version 6.2.3 here in this test. The heartbeat message is sent every 60 seconds by default, and there is no specific response needed from the server.

The next one (packet #12) is the request for active checks:

Zabbix Request for active checks for "Test-agent", Len: 47
    Header: ZBXD
    Flags: 0x01
        0000 0... = Reserved bits: All zeros (0)
        .... .0.. = Large packet: No
        .... ..0. = Compressed: No
        .... ...1 = Zabbix communications protocol: Yes
    Length: 47
    Reserved: 0
    [This is an agent connection]
    Agent Name: Test-agent
    Agent Active Checks: True
    Data: {"request":"active checks","host":"Test-agent"}
    JavaScript Object Notation
    [Data length: 47]

The server responds with a failure (packet #14):

Zabbix Response (failed), Len: 58
    Header: ZBXD
    Flags: 0x01
        0000 0... = Reserved bits: All zeros (0)
        .... .0.. = Large packet: No
        .... ..0. = Compressed: No
        .... ...1 = Zabbix communications protocol: Yes
    Length: 58
    Reserved: 0
    [This is an agent connection]
    [Agent name from the request: Test-agent]
    Response: True
    Failed: True
    Data: {"response":"failed","info":"host [Test-agent] not found"}
    JavaScript Object Notation
    [Data length: 58]
    [Time since request: 0,023441 seconds]

This sequence repeats forever unless something is reconfigured.

I’ll start configuring the autoregistration by stopping the agent for now, and adding an autoregistration action in Zabbix with these settings:

• Action name: Linux hosts
• Conditions: Host metadata contains linux
• Operations:
  • Add host
  • Link to template “Linux by Zabbix agent active”

I’ll then add this to the agent configuration:

HostMetadata=linux

and start the agent.

The server logged immediately this error again:

cannot send list of active checks to "192.168.7.17": host [Test-agent] not found

but that is just a “false alarm”: actually the server started executing the autoregistration action just fine and added the new host “Test-agent” in the Zabbix hosts list.

After waiting for a few minutes this is how the new packet capture (sudo tcpdump -v -w test-agent-autoreg.pcap host 192.168.7.17) looks like:

Now the agent included the string configured in HostMetadata directive in the active checks request:

Data: {"request":"active checks","host":"Test-agent","host_metadata":"linux"}

The server still responded with failed status, but that’s apparently by design: The server decides to respond immediately (with a failure because there is no matching host), and start executing the autoregistration actions only after that. Then, when the agent requests for the active checks again in two minutes (packet #44), the server can respond successfully (packet #46):

The response is “success” and the server sends a long list of checks that the agent should start executing according to the configuration set in the Zabbix server.

Later in the packet list there is the data that the agent started collecting and sending to the server, for example (packet #54):

Zabbix Send agent data from "Test-agent", Len: 219
    Header: ZBXD
    Flags: 0x01
        0000 0... = Reserved bits: All zeros (0)
        .... .0.. = Large packet: No
        .... ..0. = Compressed: No
        .... ...1 = Zabbix communications protocol: Yes
    Length: 219
    Reserved: 0
    [This is an agent connection]
    Session: 979c1326e575545fc81854362c42d8a1
    Agent Name: Test-agent
    Agent Data: True
    Data: {"request":"agent data","session":"979c1326e575545fc81854362c42d8a1",
"data":[{"host":"Test-agent","key":"agent.hostname","value":"Test-agent","id":1,
"clock":1667033971,"ns":528640802}],"clock":1667033971,"ns":528744331}
    JavaScript Object Notation
    [Data length: 219]

The server response is “success” (packet #56):

Zabbix Response for agent data (success), Len: 90
    Header: ZBXD
    Flags: 0x01
        0000 0... = Reserved bits: All zeros (0)
        .... .0.. = Large packet: No
        .... ..0. = Compressed: No
        .... ...1 = Zabbix communications protocol: Yes
    Length: 90
    Reserved: 0
    [This is an agent connection]
    [Agent name from the request: Test-agent]
    [Agent Data: True]
    Response: True
    Success: True
    Data: {"response":"success","info":"processed: 1; failed: 0; total: 1;
seconds spent: 0.000088"}
    JavaScript Object Notation
    [Data length: 90]
    [Time since request: 0,000173 seconds]

That’s how the communication now proceeds until something is reconfigured:

• Agent connects to the server every two minutes and requests the current list of active checks to execute
• Agent connects to the server also any time it decides to have enough data to send to the server

You can download the sample capture files from here:

• test-agent-no-host.pcap (github.com)
• test-agent-autoreg.pcap (github.com)