How to set host encryption parameters via the API?

Zabbix 3.0 introduced a major new feature – encryption between Zabbix components. If you’d like to add a new host with encryption enabled, you would go to the documentation of the host.create method… and be surprised. It says nothing about the encryption at all. You might continue to the host object page, but that wouldn’t have anything on encryption either.

Encryption tab in the host properties

How so?

Zabbix developers spent a lot of time polishing the feature and making it really robust, but they apparently run out of time and did not document the encryption-related API changes. Let’s figure out how to configure encryption settings.

PropertyTypeDescription
tls_connectIntegerFrontend field "Connections to host"

Possible values:
* 1 - no encryption
* 2 - PSK
* 4 - certificate
tls_acceptIntegerFrontend field "Connections from host"

Possible values - a bitmap value of:
* 1 - no encryption
* 2 - PSK
* 4 - certificate
tls_psk_identityStringPSK identity. Required if either tls_connect or tls_accept has PSK enabled
tls_pskStringThe preshared key, at least 32 hex digits. Required if either tls_connect or tls_accept has PSK enabled
tls_issuerStringRequired certificate issuer
tls_subjectStringRequired certificate subject

Most of the parameters there are simple, but what about “bitmap value” for tls_accept? As this control consists of three checkboxes that could be marked in any combination, it is not feasible to assign a magic unique number to each combination. Instead, it is a value where each bit represents one checkbox.

Checkboxes for the "Connections from host" option

Consider this example:

001
CertificatePSKNo encryption

Here, only the first (rightmost) bit is set. This bit represents the “No encryption” checkbox, and the resulting binary value is 001 – which is also 1 in decimal, and the value we have to send to the API. Now let’s say we want to enable only the “Certificate” checkbox.

100
CertificatePSKNo encryption

Here the leftmost bit is set, and the resulting binary value is 100. That’s 4 in decimal, which is to be sent to the API. But what if we would like to set “No encryption” and “PSK” checkboxes?

011
CertificatePSKNo encryption

Now the binary value is 011, which is the missing decimal number 3.

The tls_accept parameter accepts values of 1 to 7, representing all the possible checkbox combinations – or all binary values from 001 to 111.  If thinking in binary is not your thing, just remember that the values are 1-2-4 for No encryptionPSKCertificate, and you get a combination simply by adding them up. What’s the value for all checkboxes marked? Right, 1+2+4 = 7.

Note that these same parameters are valid also for the host.update method, and the corresponding proxy methods.

Oh, and how did we figure it all out? We did the easiest thing – checked the specification.  Specifications were a great source of information, and it’s a shame Zabbix team decided to close them – but that’s a topic for another day 🙂

Examples

A description is good to have, but examples can clear up confusion. Here are some common usecases:

“Connections to host” PSK example:

{
    "jsonrpc": "2.0",
    "method": "host.create",
    "params": {
        "host": "Linux server",
        "interfaces": [
            {
                "type": 1,
                "main": 1,
                "useip": 1,
                "ip": "192.168.1.1",
                "dns": "",
                "port": "10050"
            }
        ],
        "groups": [
            {
                "groupid": "28"
            }
        ],
        "tls_connect": 2,
        "tls_psk_identity": "test",
        "tls_psk": "ffffffffffffffffffffffffffffffffffffffffff"
    },
    "auth": "4b8dce2153bbba6e5e9988a2a4d729ac",
    "id": 1
}

“Connections to host” certificate example:

{
    "jsonrpc": "2.0",
    "method": "host.create",
    "params": {
        "host": "Linux server",
        "interfaces": [
            {
                "type": 1,
                "main": 1,
                "useip": 1,
                "ip": "192.168.1.1",
                "dns": "",
                "port": "10050"
            }
        ],
        "groups": [
            {
                "groupid": "28"
            }
        ],
        "tls_connect": 4,
        "tls_issuer": "required issuer",
        "tls_subject": "required subject"
    },
    "auth": "4b8dce2153bbba6e5e9988a2a4d729ac",
    "id": 1
}

“Connections from host” no encryption + PSK example

{
    "jsonrpc": "2.0",
    "method": "host.create",
    "params": {
        "host": "Linux server",
        "interfaces": [
            {
                "type": 1,
                "main": 1,
                "useip": 1,
                "ip": "192.168.1.1",
                "dns": "",
                "port": "10050"
            }
        ],
        "groups": [
            {
                "groupid": "28"
            }
        ],
        "tls_accept": 3,
        "tls_psk_identity": "ide",
        "tls_psk": "ffffffffffffffffffffffffffffffffffffffffff"
    },
    "auth": "4b8dce2153bbba6e5e9988a2a4d729ac",
    "id": 1
}

Leave a Reply