API, Neat tricks

Auto-registering Linux agents with TLS PSK encryption

Leave a comment

Zabbix supports Linux agent auto-registration and it’s a well documented process in the Zabbix manual. However, it’s not really straightforward to mass provision Zabbix agents on hundreds of servers if you want to have Zabbix agent <-> Zabbix server communication encrypted. At least not without some form of additional scripted step in your installation process. For large deployments I usually use Ansible, although this article just briefly covers that part and I’ll mostly focus on how to make sure your agents get registered for encrypted communication.

First of all you need `py-zabbix`  by Alexey Dubkov (https://github.com/blacked/py-zabbix). It’s a module listed on https://www.zabbix.org/wiki/Docs/api/libraries . I chose it because it already supports SSL to communicate with Zabbix https-enabled API.

You can install it manually with: `pip install py-zabbix` or use Ansible pip module for it:

- pip:
name: py-zabbix

You have to prepare your `/etc/zabbix/zabbix_agentd.psk` file which will contain TLS PSK key. You can do it with:

openssl rand -hex 32 > /etc/zabbix/zabbix_agentd.psk

cat /etc/zabbix/zabbix_agentd.psk
8327d03e993026fbbf19fb2de4aece1bb44bdeead594abf8d413972d5bc3cd2c

Next, make sure your /etc/zabbix/zabbix_agentd.conf contains proper TLS PSK configuration (consult Zabbix manual for details):

TLSConnect=unencrypted
TLSAccept=unencrypted,psk
TLSPSKIdentity=MYTLSPSKID
TLSPSKFile=/etc/zabbix/zabbix_agentd.psk

Now we are going to use a simple Python script with the Zabbix API to inform Zabbix that a host currently being auto-registered is capable of encrypted communication using TLS PSK. You can put that script in: /usr/lib/zabbix/externalscripts/autoreg-enable-tls-psk_comm.py .

#!/usr/bin/env python
import sys
from zabbix.api import ZabbixAPI
 
zapi = ZabbixAPI(url='https://zabbix.host.com/zabbix/', user='Admin', password='yourzabbixadminpasswordhere')
res1 = zapi.do_request('host.get', { 'filter': {'name': sys.argv[1]}, 'output': 'hostid'})
res2 = str(res1.get(u'result')).split('\'')
zabbix_hostid = res2[3]
zapi.do_request('host.update', {'hostid': zabbix_hostid, 'tls_connect': 2, 'tls_accept': 2, 'tls_psk_identity': "MYTLSPSKID", 'tls_psk': "8327d03e993026fbbf19fb2de4aece1bb44bdeead594abf8d413972d5bc3cd2c"})

Make sure to replace:

  • “https://zabbix.host.com/zabbix/” with the https-enabled address of your Zabbix API
  • “yourzabbixadminpasswordhere” with your Zabbix Admin password
  • “MYTLSPSKID” with whatever the ID you’ve chosen
  • “8327d03e993026fbbf19fb2de4aece1bb44bdeead594abf8d413972d5bc3cd2c” with whatever the TLS PSK value you’ve generated

Make sure to make you have proper ownership and permission settings for that script:

chown zabbix:zabbix /usr/lib/zabbix/externalscripts/autoreg-enable-tls-psk_comm.py

chmod 755 /usr/lib/zabbix/externalscripts/autoreg-enable-tls-psk_comm.py

Next – and this is a one time configuration you do using Zabbix frontend. I use Zabbix 3.0.9 here but it doesn’t differ much from 2.x in terms of what we’re going to do. Go to Configuration -> Actions. You should already have an action defined for Linux host autoregistration. If you don’t, go to https://www.zabbix.com/documentation/3.0/manual/discovery/auto_registration and follow the guide.

Once you’re done with setting up Linux host auto registration action, modify it by going to Operations, click new, then in Operation details set the following values:

  • Operation type: Remote command
  • Target list: new -> Target: Current host
  • Type: Custom script
  • Execute on: Zabbix Server
  • Commands: /usr/lib/zabbix/externalscripts/autoreg-enable-tls-psk_comm.py {HOST.HOST}

Zabbix Action Remote Custom Script

Click Update to save and update above-mentioned Zabbix Action .

The word of clarification: this guide works for checks performed by Zabbix server talking to Zabbix agents. Unfortunately you cannot auto-register Zabbix agent using encrypted communication right from the first byte transmitted. Do you remember these lines in your zabbix_agentd.conf file?

TLSConnect=unencrypted
TLSAccept=unencrypted,psk

Once Zabbix agent is installed and instructed to communicate to Zabbix server for auto-registration it will do so without any encryption. This is the only way to make Zabbix server talk to a new host and register it first. During auto-registration process I also assign standard Linux templates to my hosts and those assume connections will be initiated from Zabbix server to pull data from Zabbix agents. If you use active connections from agents to Zabbix server, you need to add an extra step/script in your auto-registration process to modify  zabbix_agentd.conf and use:

TLSConnect=psk

after auto-registration process is done.

That’s it! Enjoy!

Jacek Lakomiec
Database Fury LLC

Leave a Reply