Zabbix Configuration with API

Despite the will of Zabbix to be as automated as possible, some tasks cannot be automated. Nevertheless, Zabbix offers an HTTP-based API which can be used programmatically.

This opens the door to huge possibilities in terms of automation.

JSON-RPC

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. In regard to Zabbix, we simply have to post HTTP requests to Zabbix web server to create, update or delete configuration entities.

Authentication

The usual workflow is to first an authentication token (also via HTTP request) and then use that token in subsequent HTTP requests. For example:

# curl --request POST \
>   --url 'http://<zabbix_server>:8080/api_jsonrpc.php' \
>   --header 'Content-Type: application/json-rpc' \
>   --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'
{"jsonrpc":"2.0","result":"63b2cc9388daaaa0e150a0e2ccce6a68","id":1}

This is nice, but a bit too heavy.

Another solution is to create an API token directly in Zabbix frontend. In Users, API tokens section, click “Create API token”, following window will open:

It is recommended to set an expiration date and renew it as needed. You can see that I selected a user. I created a dedicated service user which is admin but has no right to login to front end (part of No access to the frontend group).

On next screen, the API token will be display:

Copy it and store it in a safe place as it will not be possible to display it (only regenerating it).

Auto-registration Actions

Auto-registration is a cool way to have host integrated into Zabbix server as I demonstrated it in this blog post. However, auto-registration actions setup cannot be imported from a file. If we want a consistent configuration across multiple Zabbix server, this configuration must be automated. As it is plain text, it is also possible to version that in a GIT repository.

API will help us in that matter.

There is a long chapter in Zabbix documentation about the API detailing all the methods and arguments.

First, I create a JSON file which contains details about the auto-registration action:

{
    "jsonrpc": "2.0",
    "method": "action.create",
    "params": {
        "name": "Register Linux",
        "eventsource": "2",
        "filter": {
            "evaltype": "2",
            "conditions": [
                {
                    "conditiontype": "22",
                    "operator": "2",
                    "value": "linux"
                }
            ]
        },
        "operations": [
            {
                "operationtype": "4",
                "opgroup": [
                    {
                        "groupid": "2"
                    }
                ]
            }
        ]
    }
        ,"auth":"1166aaaaa8b9d1ad8b848744e1a6edf760b9ef9bcbbbbbbbdd98ca7",
    "id": 1
}

You will have to replace auth value by the API token you have generated in the Web UI.

Next, the curl command looks like:

curl -s --request POST \
 --url 'http://<zabbix_server>:8080/api_jsonrpc.php' \
 --header 'Content-Type: application/json-rpc' \
 --data @create_action.json

If everything goes well, server will return a JSON string like the following:

{"jsonrpc":"2.0","result":{"actionids":["20"]},"id":1}

actionids is the ID in Zabbix configuration. It can be useful if an update via the API is required. It can also be found with curl on action.get method:

curl -s --request POST \
 --url 'http://<zabbix_server>:8080/api_jsonrpc.php' \
 --header 'Content-Type: application/json-rpc' \
 --data @get_action.json

Where get_action.json looks like this:

{
  "jsonrpc": "2.0",
  "method": "action.get",
  "params": {
    "filter": {
      "name": "Register Linux"
    }
  },
  "auth": "1166aaaaa8b9d1ad8b848744e1a6edf760b9ef9bcbbbbbbbdd98ca7",
  "id": 1
}

And, finally, command output looks like this:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "actionid": "20",
      "name": "Register Linux",
      "eventsource": "2",
      "status": "0",
      "esc_period": "1h",
      "pause_suppressed": "1",
      "notify_if_canceled": "1",
      "pause_symptoms": "1"
    }
  ],
  "id": 1
}