17 HTTP agent

Overview

This item type allows data polling using the HTTP/HTTPS protocol. Trapping is also possible using Zabbix sender or Zabbix sender protocol.

HTTP item check is executed by Zabbix server. However, when hosts are monitored by a Zabbix proxy, HTTP item checks are executed by the proxy.

HTTP item checks do not require any agent running on a host being monitored.

HTTP agent supports both HTTP and HTTPS. Zabbix will optionally follow redirects (see the Follow redirects option below). Maximum number of redirects is hard-coded to 10 (using cURL option CURLOPT_MAXREDIRS).

See also known issues for when using HTTPS protocol.

Zabbix server/proxy must be initially configured with cURL (libcurl) support.

Configuration

To configure an HTTP item:

  • Go to: Configuration → Hosts

  • Click on Items in the row of the host

  • Click on Create item

  • Enter parameters of the item in the form

17 HTTP agent - 图1

All mandatory input fields are marked with a red asterisk.

The fields that require specific information for HTTP items are:

TypeSelect HTTP agent here.
KeyEnter a unique item key.
URLURL to connect to and retrieve data. For example:
https://www.google.com
http://www.zabbix.com/download
Domain names can be specified in Unicode characters. They are automatically punycode-converted to ASCII when executing the HTTP check.
The Parse button can be used to separate optional query fields (like ?name=Admin&password=mypassword) from the URL, moving the attributes and values into Query fields for automatic URL-encoding.
Limited to 2048 characters.
Supported macros: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, user macros, low-level discovery macros.
This sets the CURLOPT_URL cURL option.
Query fieldsVariables for the URL (see above).
Specified as attribute and value pairs.
Values are URL-encoded automatically. Values from macros are resolved and then URL-encoded automatically.
Supported macros: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, user macros, low-level discovery macros.
This sets the CURLOPT_URL cURL option.
Request typeSelect request method type: GET, POST, PUT or HEAD
TimeoutZabbix will not spend more than the set amount of time on processing the URL (1-60 seconds). Actually this parameter defines the maximum time for making a connection to the URL and maximum time for performing an HTTP request. Therefore, Zabbix will not spend more than 2 x Timeout seconds on one check.
Time suffixes are supported, e.g. 30s, 1m.
Supported macros: user macros, low-level discovery macros.
This sets the CURLOPT_TIMEOUT cURL option.
Request body typeSelect the request body type:
Raw data - custom HTTP request body, macros are substituted but no encoding is performed
JSON data - HTTP request body in JSON format. Macros can be used as string, number, true and false; macros used as strings must be enclosed in double quotes. Values from macros are resolved and then escaped automatically. If “Content-Type” is not specified in headers then it will default to “Content-Type: application/json”
XML data - HTTP request body in XML format. Macros can be used as a text node, attribute or CDATA section. Values from macros are resolved and then escaped automatically in a text node and attribute. If “Content-Type” is not specified in headers then it will default to “Content-Type: application/xml”
Note that selecting XML data requires libxml2.
Request bodyEnter the request body.
Supported macros: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, user macros, low-level discovery macros.
HeadersCustom HTTP headers that will be sent when performing a request.
Specified as attribute and value pairs.
Supported macros: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, user macros, low-level discovery macros.
This sets the CURLOPT_HTTPHEADER cURL option.
Required status codesList of expected HTTP status codes. If Zabbix gets a code which is not in the list, the item will become unsupported. If empty, no check is performed.
For example: 200,201,210-299
Supported macros in the list: user macros, low-level discovery macros.
This uses the CURLINFO_RESPONSE_CODE cURL option.
Follow redirectsMark the checkbox to follow HTTP redirects.
This sets the CURLOPT_FOLLOWLOCATION cURL option.
Retrieve modeSelect the part of response that must be retrieved:
Body - body only
Headers - headers only
Body and headers - body and headers
Convert to JSONHeaders are saved as attribute and value pairs under the “header” key.
If ‘Content-Type: application/json’ is encountered then body is saved as an object, otherwise it is stored as string, for example:
17 HTTP agent - 图2
HTTP proxyYou can specify an HTTP proxy to use, using the format [protocol://][username[:password]@]proxy.example.com[:port].
The optional protocol:// prefix may be used to specify alternative proxy protocols (e.g. https, socks4, socks5; see documentation; the protocol prefix support was added in cURL 7.21.7). With no protocol specified, the proxy will be treated as an HTTP proxy. If you specify the wrong protocol, the connection will fail and the item will become unsupported.
By default, 1080 port will be used.
If specified, the proxy will overwrite proxy related environment variables like http_proxy, HTTPS_PROXY. If not specified, the proxy will not overwrite proxy-related environment variables. The entered value is passed on “as is”, no sanity checking takes place.
Note that only simple authentication is supported with HTTP proxy.
Supported macros: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, user macros, low-level discovery macros.
This sets the CURLOPT_PROXY cURL option.
HTTP authenticationAuthentication type:
None - no authentication used.
Basic - basic authentication is used.
NTLM - NTLM (Windows NT LAN Manager) authentication is used.
Kerberos - Kerberos authentication is used. See also: Configuring Kerberos with Zabbix.
Digest - Digest authentication is used.
Selecting an authentication method will provide two additional fields for entering a user name and password, where user macros and low-level discovery macros are supported.
This sets the CURLOPT_HTTPAUTH cURL option.
SSL verify peerMark the checkbox to verify the SSL certificate of the web server. The server certificate will be automatically taken from system-wide certificate authority (CA) location. You can override the location of CA files using Zabbix server or proxy configuration parameter SSLCALocation.
This sets the CURLOPT_SSL_VERIFYPEER cURL option.
SSL verify hostMark the checkbox to verify that the Common Name field or the Subject Alternate Name field of the web server certificate matches.
This sets the CURLOPT_SSL_VERIFYHOST cURL option.
SSL certificate fileName of the SSL certificate file used for client authentication. The certificate file must be in PEM1 format. If the certificate file contains also the private key, leave the SSL key file field empty. If the key is encrypted, specify the password in SSL key password field. The directory containing this file is specified by Zabbix server or proxy configuration parameter SSLCertLocation.
Supported macros: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, user macros, low-level discovery macros.
This sets the CURLOPT_SSLCERT cURL option.
SSL key fileName of the SSL private key file used for client authentication. The private key file must be in PEM1 format. The directory containing this file is specified by Zabbix server or proxy configuration parameter SSLKeyLocation.
Supported macros: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, user macros, low-level discovery macros.
This sets the CURLOPT_SSLKEY cURL option.
SSL key passwordSSL private key file password.
Supported macros: user macros, low-level discovery macros.
This sets the CURLOPT_KEYPASSWD cURL option.
Enable trappingWith this checkbox marked, the item will also function as trapper item and will accept data sent to this item by Zabbix sender or using Zabbix sender protocol.
Allowed hostsVisible only if Enable trapping checkbox is marked.
List of comma delimited IP addresses, optionally in CIDR notation, or hostnames.
If specified, incoming connections will be accepted only from the hosts listed here.
If IPv6 support is enabled then ‘127.0.0.1’, ‘::127.0.0.1’, ‘::ffff:127.0.0.1’ are treated equally and ‘::/0’ will allow any IPv4 or IPv6 address.
‘0.0.0.0/0’ can be used to allow any IPv4 address.
Note, that “IPv4-compatible IPv6 addresses” (0000::/96 prefix) are supported but deprecated by RFC4291.
Example: Server=127.0.0.1, 192.168.1.0/24, 192.168.3.1-255, 192.168.1-10.1-255, ::1,2001:db8::/32, zabbix.domain
Spaces and user macros are allowed in this field.
Host macros: {HOST.HOST}, {HOST.NAME}, {HOST.IP}, {HOST.DNS}, {HOST.CONN} are allowed in this field.

If the HTTP proxy field is left empty, another way for using an HTTP proxy is to set proxy-related environment variables.

For HTTP - set the http_proxy environment variable for the Zabbix server user. For example:
http_proxy=http://proxy\_ip:proxy\_port.

For HTTPS - set the HTTPS_PROXY environment variable. For example:
HTTPS_PROXY=http://proxy\_ip:proxy\_port. More details are available by running a shell command: # man curl.

[1] Zabbix supports certificate and private key files in PEM format only. In case you have your certificate and private key data in PKCS #12 format file (usually with extention *.p12 or *.pfx) you may generate the PEM file from it using the following commands:

  1. openssl pkcs12 -in ssl-cert.p12 -clcerts -nokeys -out ssl-cert.pem
  2. openssl pkcs12 -in ssl-cert.p12 -nocerts -nodes  -out ssl-cert.key

Examples

Example 1

Send simple GET requests to retrieve data from services such as Elasticsearch:

  • Create a GET item with URL: localhost:9200/?pretty

  • Notice the response:

  1. {
  2.   "name" : "YQ2VAY-",
  3.   "cluster_name" : "elasticsearch",
  4.   "cluster_uuid" : "kH4CYqh5QfqgeTsjh2F9zg",
  5.   "version" : {
  6.     "number" : "6.1.3",
  7.     "build_hash" : "af51318",
  8.     "build_date" : "2018-01-26T18:22:55.523Z",
  9.     "build_snapshot" : false,
  10.     "lucene_version" : "7.1.0",
  11.     "minimum_wire_compatibility_version" : "5.6.0",
  12.     "minimum_index_compatibility_version" : "5.0.0"
  13.   },
  14.   "tagline" : "You know, for search"
  15. }
  • Now extract the version number using a JSONPath preprocessing step: $.version.number
Example 2

Send simple POST requests to retrieve data from services such as Elasticsearch:

  • Create a POST item with URL: [http://localhost:9200/str/values/_search?scroll=10s](http://localhost:9200/str/values/_search?scroll=10s "http://localhost:9200/str/values/_search?scroll=10s")

  • Configure the following POST body to obtain the processor load (1 min average per core)

  1. {
  2.     "query": {
  3.         "bool": {
  4.             "must": [{
  5.                 "match": {
  6.                     "itemid": 28275
  7.                 }
  8.             }],
  9.             "filter": [{
  10.                 "range": {
  11.                     "clock": {
  12.                         "gt": 1517565836,
  13.                         "lte": 1517566137
  14.                     }
  15.                 }
  16.             }]
  17.         }
  18.     }
  19. }
  • Received:
  1. {
  2.     "_scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAAAkFllRMlZBWS1UU1pxTmdEeGVwQjRBTFEAAAAAAAAAJRZZUTJWQVktVFNacU5nRHhlcEI0QUxRAAAAAAAAACYWWVEyVkFZLVRTWnFOZ0R4ZXBCNEFMUQAAAAAAAAAnFllRMlZBWS1UU1pxTmdEeGVwQjRBTFEAAAAAAAAAKBZZUTJWQVktVFNacU5nRHhlcEI0QUxR",
  3.     "took": 18,
  4.     "timed_out": false,
  5.     "_shards": {
  6.         "total": 5,
  7.         "successful": 5,
  8.         "skipped": 0,
  9.         "failed": 0
  10.     },
  11.     "hits": {
  12.         "total": 1,
  13.         "max_score": 1.0,
  14.         "hits": [{
  15.             "_index": "dbl",
  16.             "_type": "values",
  17.             "_id": "dqX9VWEBV6sEKSMyk6sw",
  18.             "_score": 1.0,
  19.             "_source": {
  20.                 "itemid": 28275,
  21.                 "value": "0.138750",
  22.                 "clock": 1517566136,
  23.                 "ns": 25388713,
  24.                 "ttl": 604800
  25.             }
  26.         }]
  27.     }
  28. }
  • Now use a JSONPath preprocessing step to get the item value: $.hits.hits[0]._source.value
Example 3

Checking if Zabbix API is alive, using [apiinfo.version]($a311d94dca2cc0c9.md "manual:api:reference:apiinfo:version").

  • Item configuration:

17 HTTP agent - 图3

Note the use of the POST method with JSON data, setting request headers and asking to return headers only:

  • Item value preprocessing with regular expression to get HTTP code:

17 HTTP agent - 图4

  • Checking the result in Latest data:

17 HTTP agent - 图5

Example 4

Retrieving weather information by connecting to the Openweathermap public service.

  • Configure a master item for bulk data collection in a single JSON:

17 HTTP agent - 图6

Note the usage of macros in query fields. Refer to the Openweathermap API for how to fill them.

Sample JSON returned in response to HTTP agent:

  1. {
  2.     "body": {
  3.         "coord": {
  4.             "lon": 40.01,
  5.             "lat": 56.11
  6.         },
  7.         "weather": [{
  8.             "id": 801,
  9.             "main": "Clouds",
  10.             "description": "few clouds",
  11.             "icon": "02n"
  12.         }],
  13.         "base": "stations",
  14.         "main": {
  15.             "temp": 15.14,
  16.             "pressure": 1012.6,
  17.             "humidity": 66,
  18.             "temp_min": 15.14,
  19.             "temp_max": 15.14,
  20.             "sea_level": 1030.91,
  21.             "grnd_level": 1012.6
  22.         },
  23.         "wind": {
  24.             "speed": 1.86,
  25.             "deg": 246.001
  26.         },
  27.         "clouds": {
  28.             "all": 20
  29.         },
  30.         "dt": 1526509427,
  31.         "sys": {
  32.             "message": 0.0035,
  33.             "country": "RU",
  34.             "sunrise": 1526432608,
  35.             "sunset": 1526491828
  36.         },
  37.         "id": 487837,
  38.         "name": "Stavrovo",
  39.         "cod": 200
  40.     }
  41. }

The next task is to configure dependent items that extract data from the JSON.

  • Configure a sample dependent item for humidity:

17 HTTP agent - 图7

Other weather metrics such as ‘Temperature’ are added in the same manner.

  • Sample dependent item value preprocessing with JSONPath:

17 HTTP agent - 图8

  • Check the result of weather data in Latest data:

17 HTTP agent - 图9

Example 5

Connecting to Nginx status page and getting its metrics in bulk.

  • Configure Nginx following the official guide.

  • Configure a master item for bulk data collection:

17 HTTP agent - 图10

Sample Nginx stub status output:

  1. Active connections: 1 Active connections:
  2. server accepts handled requests
  3.  52 52 52 
  4. Reading: 0 Writing: 1 Waiting: 0

The next task is to configure dependent items that extract data.

  • Configure a sample dependent item for requests per second:

17 HTTP agent - 图11

  • Sample dependent item value preprocessing with regular expression:

17 HTTP agent - 图12

  • Check the complete result from stub module in Latest data:

17 HTTP agent - 图13