See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1816

From Zabbix.org
Jump to: navigation, search

Use Curl for the agent's web.page items

ZBXNEXT-1816

Status: Draft

Owner: viktors

Summary

Currently Zabbix item web.page does not support use of cURL. Adding cURL to this item would allow redirects, SSL negotiation and other functionality that cURL is providing. cURL functionality would be used only when Zabbix is configured with libcurl.

Specification

web.page.get

To get the content of a web page item keyweb.page.get is used. Returns the web page source as text or an empty string on fail.

Currently web.page.get syntax is:

 web.page.get[host,<path>,<port>]

Where there are 3 parameters - 1 obligatory and 2 optional.

Very useful would be to add two more parameters. One of them would provide headers that can be passed to a web server. The other one could select cURL library options.

The new web.page.get syntax would be:

 web.page.get[host,<path>,<port>,<headers>,<options>]
  • host - hostname
  • path - path to HTML document (default is /)
  • port - port number (default is 80)
  • headers - header lines (default is empty string, i.e. no specific headers)
  • options - one or multiple supported options (default is empty string, i.e. no specific options)


New syntax if decided to do merge of "host", "path", and "port" into "url":

 web.page.get[url,<headers>,<options>]


Example:

 web.page.get[http://www.zabbix.com:80/about.php,[Host: www.zabbix.com,User-Agent: Zabbix 2.4.1],[PROXY=127.0.0.2,FOLLOWLOCATION=1]]

or

 web.page.get[http://www.zabbix.com:80/about.php,User-Agent: Zabbix 2.4.1,FOLLOWLOCATION=1]

The syntax that should be used to write "headers" and "options" parameters is described in documentation on item key parameters.

Headers have to be specified in the order that the user wishes the header to be like. Each following header line is placed below the previous one. If the same header is used multiple times it is added to the bottom of the header again as a new line with the new value.

The order in which the options are set does not matter. All options are set with an option followed by a parameter. Use equal ("=") sign to separate option name form its parameter. For option name use capital letters only and separate words with underscore ("_"). Do not include white space before or after the equal sign. If the same option is defined multiple times with different values only the last one will be valid. This is not recommended and each option should be used only once.

web.page.perf and web.page.regexp

Item keys web.page.perf (loading time of full web page (in seconds)) and web.page.regexp (find string on a web page) will be using cURL to access web pages same way web.page.get does.

Current syntax:

 web.page.perf[host,<path>,<port>]
 web.page.regexp[host,<path>,<port>,<regexp>,<length>,<output>]

New syntax:

 web.page.perf[host,<path>,<port>,<headers>,<options>]
 web.page.regexp[host,<path>,<port>,<regexp>,<length>,<output>,<headers>,<options>]

New syntax if decided to do merge of "host", "path", and "port" into "url":

 web.page.perf[url,<headers>,<options>]
 web.page.regexp[url,<regexp>,<length>,<output>,<headers>,<options>]

Supported option list

Option Parameters Comment
HEADER 0 - not to include the header in the body output (default)

1 - include the header in the body output

Example: HEADER=1
HTTP_VERSION CURL_HTTP_VERSION_NONE - We don't care about what version the library uses. libcurl will use whatever it thinks fit (default).

CURL_HTTP_VERSION_1_0 - Enforce HTTP 1.0 requests. CURL_HTTP_VERSION_1_1 - Enforce HTTP 1.1 requests. CURL_HTTP_VERSION_2_0 - Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.x if HTTP 2 can't be negotiated with the server. (Added in 7.33.0)

PROXY String holding the host name or dotted numerical IP address. A numerical IPv6 address must be written within [brackets].

NULL - default, no proxy is used.

Set the proxy to use for the upcoming request. The parameter should be a char * to a zero terminated string holding the host name or dotted numerical IP address. A numerical IPv6 address must be written within [brackets].
PROXYPORT Proxy port

0 - not specified which makes it use the default port

Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string PROXY or uses the default one.

While this accepts a 'long', the port number is 16 bit so it can't be larger than 65535.

FOLLOWLOCATION 0 - disabled (default)

1 - tells to follow any Location: header that the server sends as part of a HTTP header in a 3xx response.

The Location: header can specify a relative or an absolute URL to follow.

libcurl will issue another request for the new URL and follow new Location: headers all the way until no more such headers are returned. MAXREDIRS can be used to limit the number of redirects libcurl will follow.

MAXREDIRS The set number will be the redirection limit amount.

Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects.

If that many redirections have been followed, the next redirect will cause an error (CURLE_TOO_MANY_REDIRECTS). This option only makes sense if the FOLLOWLOCATION is used at the same time.
USERNAME

String holding the user name Blank - default

USERNAME sets the user name to be used in protocol authentication.

To specify the password and login options, along with the user name, use the PASSWORD and LOGIN_OPTIONS options.

PASSWORD String holding the password

Blank - default

PASSWORD option should be used in conjunction with the USERNAME option.
LOGIN_OPTIONS String holding the option

NULL - default

For more information about the login options please see RFC 2384, RFC5092 and IETF draft draft-earhart-url-smtp-00.txt

LOGIN_OPTIONS can be used to set protocol specific login options, such as the preferred authentication mechanism via "AUTH=NTLM" or "AUTH=*", and should be used in conjunction with the USERNAME option.

For more information about these options please visit the cURL option list web site using link provided below.

References

Error codes in libcurl are listed on the web site that can be accessed using link below. Why they occur and possibly what you can do to fix the problem is also included.

API changes

No API changes.

Translation strings

Description (NAME) for web.page.get in item key helper window have to be translated.

To be decided

  • Which exact cURL functionality options to use in Zabbix. Software development may highly depend on this.
  • Should web.page.* items return ZBX_NOTSUPPORTED if Zabbix configured without libcurl.
  • Should merge of "host", "path", and "port" into "url" be done? That would make it possible to specify either http:// and https://.

Syntax:

 web.page.get[host,<headers>,<options>]
 web.page.perf[host,<headers>,<options>]
 web.page.regexp[host,<headers>,<options>,<regexp>,<length>,<output>]

Documentation

ChangeLog

  • N/A