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

Docs/specs/ZBXNEXT-282

From Zabbix.org
Jump to: navigation, search

Support of HTTP headers and other options for web monitoring

ZBXNEXT-282

Status: v1.7

Owner: Alexei, Sasha

Summary

Support of optional HTTP headers will extend scope of use of Zabbix web monitoring to enable, for example, monitoring of JSON and SOAP based services. Additionally new options to control SSL certificates, peer/host verification, request of page header only and optional follow redirect functionality.

Also maximum size of URL will be increased to 2048 characters.

Specification

Front-end changes

Additional columns for Configuration -> Host -> Web scenario (list) in this order:

 Name
 Number of steps
 Update interval
 Retries                                                                    # new column
 Authentication (None/Basic/NTLM)                                           # new column
 HTTP proxy (Yes/No)                                                        # new column
 Application (nothing/Application name)                                     # new column
 Status
 Info                                                 # new column, red 'X' with error message on mouse over, same way as for items

Additional options for Configuration -> Host -> Web scenario (scenario details):

 Headers                             # text field, same size as Post. Placed after 'Variables'.

Additional options for Configuration -> Host -> Web scenario (scenario details, new tab 'Authentication'):

 Authentication              # existing field, moved from Scenario
 User                        # existing field, moved from Scenario
 Password                    # existing field, moved from Scenario
 SSL verify peer [ ]
 SSL verify host [ ]
 SSL certificate file        # all labels are same size as HTTP Proxy
 SSL key file
 SSL key password

The SSL certificate file specifies client certificate that is sent to a Web server when establishing SSL connection. Unless it contains client private key the client private key file must be specified separately in SSL key file.

Additional options for Configuration -> Host -> Web scenario (step details) after existing 'Variables':

 Headers                                              # text field, same size as Post.
 Follow redirects            [X]                      # checked by default
 Retrieve only page headers  [ ]                      # not checked by default

In case "Retrieve only page headers" gets checked the "Required string" and "Post" gets disabled and on clicking "Save" the "Required string" and "Post" values are emptied in the database.

All of the new fields should be editable for inherited web scenarios.

Server/proxy side changes

New optional configuration parameters:

 SSLCertLocation                     # default value is ${datadir}/zabbix/ssl/certs
 SSLKeyLocation                      # default value is ${datadir}/zabbix/ssl/keys
 SSLCALocation                       # empty by default

If SSLCALocation is not empty it sets cURL option CURLOPT_CAPATH. Otherwise cURL will use system-wide CA directory.

If SSL certificate file is not empty then cURL option CURLOPT_SSLCERTTYPE should be set to "PEM" and CURLOPT_SSLCERT to SSLCertLocation+'SSL Cert File'. If SSL key file is not empty then cURL option CURLOPT_SSLKEYTYPE should be set to "PEM", CURLOPT_SSLKEY to SSLKeyLocation+'SSL key file' and CURLOPT_KEYPASSWD to 'SSL key password'. SSL certificate file can not be empty if SSL key file is set.

Custom headers are set using option CURLOPT_HTTPHEADER, the option can be used to replace and remove headers already set on scenario level, see http://curl.haxx.se/libcurl/c/curl_easy_setopt.html. For example, 'User-Agent:' with no data will remove User-Agent set on scenario level. Step level headers will overwrite headers set on scenario level.

In case of any problems with SSL validation Curl error message will be used.

Libcurl option CURLOPT_NOBODY should be used to control if only HTTP headers should be fetched.

Max number of redirects should be set 10, which seems to be a reasonable limit. The limit will be defined as a macro in one of include/*.h files.

Support of macros

SSL key password should support {$MACRO}. Headers will support all macros currently supported by Post, see https://www.zabbix.com/documentation/2.2/manual/appendix/macros/supported_by_location#footnotes, footnote #6.

SSL certificate file and SSL key file should support {$MACRO} as well as {HOST.*}.

API changes

httptest

Web scenario

New web scenario properties must be implemented:

  • headers - string, optional
  • verify_peer - integer, optional, default: 0; supported values: 0 - skip peer verification, 1 - verify peer
  • verify_host - integer, optional, default: 0; supported values: 0 - skip host verification, 1 - verify host
  • ssl_cert_file - string, optional, cannot be empty if ssl_key_file or ssl_key_password is specified
  • ssl_key_file - string, optional
  • ssl_key_password - string, optional

Scenario step

New scenario step properties must be implemented:

  • follow_redirects - integer, optional, default: 1; supported values: 0 - don't follow redirects, 1 - follow redirects
  • retrieve_mode - integer, optional, default: 0; supported values: 0 - content only, 1 - header only
  • headers - string, optional

Validation

  • Only integer fields must be validated.
  • When using Oracle or DB2 length of the web scenario and scenario step header fields will be limited to 2048 chars.

Translation strings

  • SSL certificate file
  • SSL key file
  • SSL key password
  • SSL verify peer
  • SSL verify host
  • Follow redirects
  • Retrieve only page headers
  • Headers

Database changes

New fields for table 'httptest':

FIELD           |ssl_cert_file   |t_varchar(255)  |'' |NOT NULL       |ZBX_PROXY,ZBX_NODATA                  
FIELD           |ssl_key_file    |t_varchar(255)  |'' |NOT NULL       |ZBX_PROXY,ZBX_NODATA                  
FIELD           |ssl_key_password|t_varchar(64)   |'' |NOT NULL       |ZBX_PROXY,ZBX_NODATA                  
FIELD           |verify_peer     |t_integer       |'0'|NOT NULL       |ZBX_PROXY                  
FIELD           |verify_host     |t_integer       |'0'|NOT NULL       |ZBX_PROXY
FIELD           |headers         |t_shorttext     |'' |NOT NULL       |ZBX_PROXY

New fields for table 'httpstep':

FIELD           |follow_redirects |t_integer      |'1'|NOT NULL       |ZBX_PROXY
FIELD           |retrieve_mode    |t_integer      |'0'|NOT NULL       |ZBX_PROXY   # 0 - page content only, 1 - headers only
FIELD           |headers          |t_shorttext    |'' |NOT NULL       |ZBX_PROXY

Modified field for table 'httpstep':

FIELD           |url              |t_varchar(2048)|'' |NOT NULL       |ZBX_PROXY

Documentation

  • What's new
  • Documentation on web monitoring
  • API

Also discussed

  • The popup for configuration of scenario step will not be redesigned in scope of this development

ChangeLog

v1.1

  • Removed ZBX_SYNC, ZBX_NODATA where needed
  • added scenario-level headers
  • max size of URL increased to 2048 characters
  • added information about validation of headers
  • added details about error messages in case of SSL related issues
  • radio box to configure what should be returned
  • added information about CURLOPT_NOBODY
  • set limit on max number of redirects

v1.2

  • minor reordering of fields
  • changed several field labels
  • changed the "Retrieve" parameter for scenario steps
  • all of the new fields should be editable for inherited web scenarios

v1.3

  • added support of macros for 'SSL certificate file' and 'SSL key file'

v1.4

  • use checkbox instead of radio button for retrieve mode
  • disable "Required string" if "Retrieve only headers" is checked
  • updated translation strings; delete: "page content" and "page headers", add: "Retrieve only page headers"

v1.5

  • changed ssl fields validation in "Web scenario" section

v1.6

  • by default SSLCALocation has no value, in which case we are not setting CURLOPT_CAPATH

v1.7

  • posts disabled on save if "retrieve only headers" is checked