Zabbix Documentation 2.2

3.04.04.45.0 (current)| In development:5.2 (devel)| Unsupported:1.82.02.22.43.23.44.2Guidelines

User Tools

Site Tools


manual:installation:upgrade_notes_220

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:installation:upgrade_notes_220 [2013/11/22 08:00]
martins-v empty string returned instead of EOF for several items; some formatting fixes
manual:installation:upgrade_notes_220 [2017/02/16 10:09] (current)
martins-v note about case-sensitive MySQL database
Line 1: Line 1:
-==== -#Upgrade notes for 2.2.0 ====+==== -#Upgrade notes for 2.2.0 ==== 
 + 
 +=== Requirement changes ​===
  
   * Minimum supported PHP version changed from 5.1.6 to 5.3.0   * Minimum supported PHP version changed from 5.1.6 to 5.3.0
   * Minimum supported MySQL version changed from 5.0.0 to 5.0.3   * Minimum supported MySQL version changed from 5.0.0 to 5.0.3
 +  * The "​mysqli"​ PHP extension is required instead of "​mysql"​
   * Accepted data limit when using Zabbix protocol was changed from 128MB to 64MB.   * Accepted data limit when using Zabbix protocol was changed from 128MB to 64MB.
 +
 +=== Case-sensitive MySQL database ===
 +
 +A case-sensitive MySQL database is required for proper server work. It is [[:​manual/​appendix/​install/​db_scripts#​mysql|recommended]] to create a case-sensitive MySQL database during new installations. If you created a MySQL database with the utf8 character set previously, in order to support case sensitiveness of stored data, you need to convert the charset to utf8_bin.
  
 === New upgrade procedure === === New upgrade procedure ===
  
-There are no upgrade SQL scripts anymore - database upgrade is performed by the Zabbix server.+There are no upgrade SQL scripts anymore - database upgrade is performed by the Zabbix server/proxy.
  
 <note warning>​Database upgrade is automatic - make sure to have a backup before starting the new Zabbix server binary.</​note>​ <note warning>​Database upgrade is automatic - make sure to have a backup before starting the new Zabbix server binary.</​note>​
  
-=== 64-bit range for object IDs === +<​note>​Automatic database upgrade ​for SQLite is not supported.</note>
- +
-Zabbix now supports a signed 64-bit range for internal object IDs in a standalone, non-distributed setupThus the highest available number of one-type objects is 2<​sup>​63</supnow.+
  
 === Permission changes === === Permission changes ===
  
 Since Zabbix 2.2 "​Read-write"​ permissions have precedence over "​Read"​ permissions. Previously, if a user (through two different user groups) had both "​Read"​ and "​Read-write"​ permissions to a specific host, the host was only "​Read"​ to them. Now it will be "​Read-write"​. Since Zabbix 2.2 "​Read-write"​ permissions have precedence over "​Read"​ permissions. Previously, if a user (through two different user groups) had both "​Read"​ and "​Read-write"​ permissions to a specific host, the host was only "​Read"​ to them. Now it will be "​Read-write"​.
 +
 +=== Trigger calculation changes with item history=0 ===
 +
 +Previously you could set the //Keep history// option in item configuration to 0 and still have those triggers working that used only the last value in calculation. Starting with the introduction of [[:​manual/​introduction/​whatsnew220#​value_cache_for_faster_access_to_history_data|value cache]] in Zabbix 2.2, no trigger functions will be calculated if item history is set to 0.
  
 === Changed maintenance period logic === === Changed maintenance period logic ===
  
-Previously, a maintenance period for every second/​third/​etc day would first occur on the second/​third/​etc day after the //Active since// day. Now the first occurence ​will take place on the //Active since// day and then every second/​third/​etc day.+Previously, a maintenance period for every second/​third/​etc day would first occur on the second/​third/​etc day after the //Active since// day. Now the first occurrence ​will take place on the //Active since// day and then every second/​third/​etc day.
  
-=== Macro changes ​===+=== 64-bit range for object IDs ===
  
-EVENT.* macrossuch as {EVENT.ID}, {EVENT.TIME},​ {EVENT.DATE},​ {EVENT.AGE},​ {EVENT.ACK.HISTORY},​ {EVENT.ACK.STATUS},​ will behave differently in recovery notifications starting with Zabbix 2.2. +Zabbix now supports a signed 64-bit range for internal object IDs in a standalonenon-distributed setupThus the highest available number of one-type objects is 2<​sup>​63</​sup>​-1 now.
  
-Previously, when used in recovery messages they would return information of the recovery event. In Zabbix 2.2 they will return information of the original problem event.+=== Database monitor item changes ===
  
-To return information about the recovery event, separate recovery (EVENT.RECOVERY.* ) macros are introduced - {EVENT.RECOVERY.ID},​ {EVENT.RECOVERY.TIME},​ etc. For more information see [[:2.2/​manual/​appendix/​macros/​supported_by_location|Macros supported by location]].+Before all ODBC parameters were stored in the item additional parameter field in the following format:
  
-=== Regular expression testing ===+  DSN=<data source name> 
 +  user=<user name> 
 +  password=<​password>​ 
 +  sql=<​query>​
  
-The logic of displaying testing results of regular expressions has been [[:2.2/​manual/​introduction/​whatsnew220#​miscellaneous_improvements|improved]]Results are shown after applying the conditionnot before.+In Zabbix ​2.2.0ODBC parameter storage is changed: 
 +  * <data source name> is stored as the second parameter in the item key 
 +  * <user name> is stored in the item username field 
 +  * <​password>​ is stored in the item password field 
 +  * <​query>​ is stored in the item additional parameter field
  
-=== API changes ===+The database upgrade will automatically convert database monitor items into the new format. The only exception is items that exceed the following limits: 
 +  * Length of <data source name> plus length of item key must be less than 255 symbols. 
 +  * Length of <user name> must be less than 65 bytes 
 +  * Length of <​password>​ must be less than 65 bytes
  
-API version has been bumped to 2.2.0 and will match Zabbix version from now on.+If an item can't be converted because of the above limits, then it will be left unchanged ​and a warning message ​will be written to the log fileSuch items must be converted manually (shortening the problematic parameters so that they fit the new limits): 
 +  - add <data source name> to item key as the second parameter 
 +  - move <user name>, <​password>​ into respective Username, Password fields 
 +  - leave only <​query>​ in the <SQL query> field
  
-=== mysqli PHP extension required ===+Item conversion failure warning message examples: 
 +<​file>​ 
 + ​25208:​20130807:​103348.467 Failed to convert host "​dbmonitor"​ db monitoring item because key "​db.odbc.select[query4__123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789]"​ is too long. See upgrade notes for manual database monitor item conversion. 
 + ​25208:​20130807:​103348.467 Failed to convert host "​dbmonitor"​ db monitoring item because ODBC username "​123456789_123456789_123456789_123456789_123456789_123456789_123456789_"​ is too long. See upgrade notes for manual database monitor item conversion. 
 + ​25208:​20130807:​103348.467 Failed to convert host "​dbmonitor"​ db monitoring item because ODBC password "​123456789_123456789_123456789_123456789_123456789_123456789_123456789_"​ is too long. See upgrade notes for manual database monitor item conversion. 
 +</​file>​
  
-The "​mysqli"​ PHP extension is required instead of "​mysql"​.+=== Removed iODBC support ===
  
-=== More data sent for '​Latest data' ===+Zabbix supported unixODBC and iODBC for direct database monitoring. iODBC is not actively maintained and there were no known users of it with Zabbix, thus support for iODBC has been removed in 2.2. For database monitoring unixODBC should be used.
  
-//Latest data// page now sends data for all entries, including collapsed ones. This may considerably increase page size in some instances.+=== Internal check changes ===
  
-=== Housekeeper changes ===+The **zabbix[items]** internal check will now return the number of monitored items instead of the total number of items in database.
  
-The **DisableHousekeeping** server configuration option is supported no more. Instead, finer controls ​are located in the frontend, in //​Administration -> General -> [[:​2.2/​manual/​web_interface/​frontend_sections/​administration/​general|Housekeeper]]//,​ allowing to selectively enable/​disable housekeeping processes for specific tables.+Internal checks of the hosts monitored by proxies ​are now processed by the proxies.
  
-<note warning>​Housekeeper is disabled by default after upgrading to 2.2. The desired housekeeper functionality should be enabled manually.</​note>​+=== Empty string returned instead of EOF ===
  
-=== JSON validation in server ===+Several items that used to return EOF upon failure - **vfs.file.contents**,​ **vfs.file.regexp**,​ **web.page.get** and **web.page.regexp** - now return an empty string.
  
-Previouslyslightly incorrect JSON might be accepted by the Zabbix serverSince Zabbix 2.2, syntax validation ​will be performed. If custom LLD rules have been used with incorrect JSON syntax, they might stop working. In such case custom rules should be fixed to return properly formatted JSON.+=== Windows eventlog item changes === 
 + 
 +In Windows eventlog items, the //source// filter option is changed to support regular expressions. 
 + 
 +The database upgrade ​will automatically convert the fourth parameter of //​eventlog//​ item keys into a regular expression (adding //^// and //$// symbols at the start and end of the fourth parameter respectively for all existing //​eventlog//​ item keys).
  
 === Timeout and retries for SNMP checks === === Timeout and retries for SNMP checks ===
Line 61: Line 92:
 Zabbix server and proxy daemons will now correctly use the Timeout configuration parameter when performing SNMP checks. Additionally now the daemons will not perform retries after single unsuccessful (the timeout/​wrong credentials) SNMP request. Previously the SNMP library default timeout and retries values (1 second and 5 retries respectively) were actually used. Zabbix server and proxy daemons will now correctly use the Timeout configuration parameter when performing SNMP checks. Additionally now the daemons will not perform retries after single unsuccessful (the timeout/​wrong credentials) SNMP request. Previously the SNMP library default timeout and retries values (1 second and 5 retries respectively) were actually used.
  
-=== Changed ​item parameter validation ===+=== Changes in item parameter validation === 
 + 
 +A more strict parameter validation by Zabbix agent has been introduced. Whereas previously parameters for items that do not support parameters would be ignored, now the items will return ZBX_NOTSUPPORTED and become unsupported.
  
 Since 2.2 Zabbix agent will return ZBX_NOTSUPPORTED in case of invalid //timeout// or //count// values of **net.dns** check. Previously there was no validation and default or 0 values were used. From now on zero value will be also treated as an error. Since 2.2 Zabbix agent will return ZBX_NOTSUPPORTED in case of invalid //timeout// or //count// values of **net.dns** check. Previously there was no validation and default or 0 values were used. From now on zero value will be also treated as an error.
  
-=== Internal check changes ​===+=== Changes in system.uname item ===
  
-The **zabbix[items]** internal check will now return ​the number of monitored items instead of the total number ​of items in database.+Before Zabbix 2.2, the value for **system.uname** was obtained by invoking "uname -a" on Unix systems. Since Zabbix 2.2, the value is obtained by using the uname() system call. Hence, the value of this item might change after the upgrade and no longer includes the additional information that "uname -a" prints based on other sources. 
 +=== Changes ​in {EVENT.*} macros ===
  
-Internal checks of the hosts monitored by proxies are now processed by the proxies.+EVENT.* macros, such as {EVENT.ID}, {EVENT.TIME},​ {EVENT.DATE},​ {EVENT.AGE},​ {EVENT.ACK.HISTORY},​ {EVENT.ACK.STATUS},​ will behave differently in recovery notifications starting with Zabbix 2.2
  
-=== Empty string returned instead ​of EOF ===+Previously, when used in recovery messages they would return information ​of the recovery event. In Zabbix 2.2 they will return information of the original problem event.
  
-Several items that used to return ​EOF upon failure - **vfs.file.contents**, **vfs.file.regexp****web.page.get** and **web.page.regexp** - now return an empty string.+To return ​information about the recovery event, separate recovery (EVENT.RECOVERY.* ) macros are introduced - {EVENT.RECOVERY.ID}{EVENT.RECOVERY.TIME}, etcFor more information see [[manual:​appendix:​macros:​supported_by_location|Macros supported by location]].
  
-=== Added UTF-8 validation for daemon parameters ​===+=== Changes in {ESC.HISTORY} macro ===
  
-Daemon configuration parameter validation has been changed ​to disallow non-UTF-8 characters.+Previously, if one escalation step resulted in multiple messages being generated, the value of {ESC.HISTORY} macro would differ for different recipients. Now {ESC.HISTORY} creates the same message content within the same escalation step when notification is sent to multiple recipients.
  
-=== Logout session verification ​===+=== Regular expression testing ​===
  
-Logging out will now require a valid SID to be passed in the URL.+The logic of displaying testing results of regular expressions has been [[manual:​introduction:​whatsnew220#​miscellaneous_improvements|improved]]. Results are shown after applying ​the condition, not before.
  
-=== Windows eventlog item changes ===+=== API changes ===
  
-In Windows eventlog items, the //source// filter option is changed ​to support regular expressions.+API version has been bumped ​to 2.2.0 and will match Zabbix version from now on.
  
-The database upgrade will automatically convert the fourth parameter of //​eventlog//​ item keys into a regular expression (adding //^// and //$// symbols at the start and end of the fourth parameter respectively ​for all existing //​eventlog//​ item keys).+=== More data sent for '​Latest data' ===
  
-=== Database monitor item changes ===+//Latest data// page now sends data for all entries, including collapsed ones. This may considerably increase page size in some instances.
  
-Before all ODBC parameters were stored in the item additional parameter field in the following format:+=== Housekeeper changes ===
  
-  DSN=<​data source name> +The **DisableHousekeeping** server configuration option is supported no more. Instead, finer controls are located in the frontend, in //​Administration -General -[[manual:​web_interface:​frontend_sections:​administration:​general|Housekeeper]]//,​ allowing to selectively enable/​disable housekeeping processes for specific tables.
-  user=<​user name> +
-  password=<​password>​ +
-  sql=<​query>+
  
-In Zabbix 2.2.0, ODBC parameter storage is changed: +Due to the changes ​in how latest ​item values are stored, values of items with history storage period set to "​0"​ will not be displayed ​in the //​Monitoring -Latest data// and //​Monitoring -Overview// pages. The //​{ITEM.LASTVALUE}//​ macro in the frontend will also not work for such items. To avoid breaking this functionality the history storage period will be automatically changed from "​0"​ to "​1"​ for all existing items.
-  * <data source name> is stored as the second parameter ​in the item key +
-  * <user name> is stored in the item username field +
-  * <​passwordis stored in the item password field +
-  * <queryis stored ​in the item additional parameter field+
  
-The database upgrade will automatically convert database monitor items into the new format. The only exception is items that exceed the following limits: +<note warning>​Housekeeper is disabled by default after upgrading to 2.2. The desired housekeeper functionality should ​be enabled manually.</note
-  * Length of <data source name> plus length of item key must be less than 255 symbols. +=== JSON validation in server ===
-  * Length of <user namemust be less than 65 bytes +
-  * Length of <​password>​ must be less than 65 bytes+
  
-If an item can'​t ​be converted because of the above limitsthen it will be left unchanged and a warning message will be written ​to the log fileSuch items must be converted manually (shortening the problematic parameters so that they fit the new limits): +Previously, slightly incorrect JSON might be accepted by the Zabbix server. Since Zabbix 2.2syntax validation ​will be performed. If custom LLD rules have been used with incorrect JSON syntax, they might stop working. In such case custom rules should ​be fixed to return properly formatted JSON.
-  - add <data source name> to item key as the second parameter +
-  - move <user name>, <​password>​ into respective Username, Password fields +
-  - leave only <​query>​ in the <SQL query> field+
  
-Item conversion failure warning message examples: +=== Added UTF-8 validation for daemon parameters ​===
-<​file>​ +
- ​25208:​20130807:​103348.467 Failed to convert host "​dbmonitor"​ db monitoring item because key "​db.odbc.select[query4__123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789]"​ is too long. See upgrade notes for manual database monitor item conversion. +
- ​25208:​20130807:​103348.467 Failed to convert host "​dbmonitor"​ db monitoring item because ODBC username "​123456789_123456789_123456789_123456789_123456789_123456789_123456789_"​ is too long. See upgrade notes for manual database monitor item conversion. +
- ​25208:​20130807:​103348.467 Failed to convert host "​dbmonitor"​ db monitoring item because ODBC password "​123456789_123456789_123456789_123456789_123456789_123456789_123456789_"​ is too long. See upgrade notes for manual database monitor item conversion. +
-</​file>​ +
-=== Removed iODBC support ​===+
  
-Zabbix supported unixODBC and iODBC for direct database monitoring. iODBC is not actively maintained and there were no known users of it with Zabbix, thus support for iODBC has been removed in 2.2. For database monitoring unixODBC should be used.+Daemon configuration parameter validation ​has been changed to disallow non-UTF-8 characters.
  
-=== Changes in {ESC.HISTORY} macro ===+=== Logout session verification ​===
  
-Previously, if one escalation step resulted ​in multiple messages being generated, ​the value of {ESC.HISTORY} macro would differ for different recipients. Now {ESC.HISTORY} creates the same message content within the same escalation step when notification is sent to multiple recipients.+Logging out will now require a valid SID to be passed ​in the URL.
  
 === Screen element changes === === Screen element changes ===
Line 152: Line 168:
 Additionally if no arguments or server are specified the exit status will be 1 and for -h and -V options the exit status will be 0 (before Zabbix 2.2.0 exit status in the listed situations was 255). Additionally if no arguments or server are specified the exit status will be 1 and for -h and -V options the exit status will be 0 (before Zabbix 2.2.0 exit status in the listed situations was 255).
  
 +Additionally when reading data from a file (-i) or working in real time mode (-r) the Zabbix sender will immediately exit with a correct exit status after failing to parse or send an input line.
 === Different column order with Oracle === === Different column order with Oracle ===
  
Line 159: Line 176:
  
 The standard item keys that were previously stored in the //​help_items//​ table are now defined in the PHP CHelpItems class in //​frontends/​php/​include/​classes/​items/​CHelpItems.php//​. The //​help_items//​ table has been dropped. The standard item keys that were previously stored in the //​help_items//​ table are now defined in the PHP CHelpItems class in //​frontends/​php/​include/​classes/​items/​CHelpItems.php//​. The //​help_items//​ table has been dropped.
 +
 +=== Daemon security fixes ===
 +
 +Zabbix server now correctly enables SSL host verification when using Ez Texting service to send alerts.
 +
 +=== Queue changes ===
 +As the queue (Administration → Queue) is now retrieved directly from the server it is available only when Zabbix server is running and if the frontend has direct access to Zabbix server.
 +
 +=== Logging changes ===
 +
 +Before Zabbix 2.2.0, server and proxy would log messages about the availability of a particular type of checks on a host in the following format:
 +  SNMP item [ifInOctets.3] on host [gateway] failed: first network error, wait for 15 seconds
 +Starting with Zabbix 2.2.0, the type specification for SNMP, IPMI and JMX checks now includes the additional word "​agent":​
 +  SNMP agent item [ifInOctets.3] on host [gateway] failed: first network error, wait for 15 seconds