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.

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.

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.

Consider this example:

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.

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?

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 encryption–PSK–Certificate, 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
}