Zabbix Documentation 2.2

3.04.05.0 (current)| In development:5.2 (devel)| Unsupported:1.82.02.22.43.23.44.24.4Guidelines

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/12 17:34]
kodai change section number for package installation
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 ​===+
  
-Previously, slightly incorrect JSON might be accepted by the Zabbix serverSince Zabbix 2.2syntax validation will be performedIf custom LLD rules have been used with incorrect JSON syntaxthey might stop working. In such case custom rules should be fixed to return properly formatted JSON.+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. 
 + 
 +=== 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 60: 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 checks changes ​===+=== Changes in system.uname item ===
  
-The internal check zabbix[items] 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
  
-=== Added UTF-8 validation for daemon parameters ===+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.
  
-Daemon configuration parameter validation has been changed to disallow non-UTF-8 characters.+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 [[manual:​appendix:​macros:​supported_by_location|Macros supported by location]].
  
-=== Logout session verification ​===+=== Changes in {ESC.HISTORY} macro ===
  
-Logging out will now require a valid SID to be passed ​in the URL.+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.
  
-=== Windows eventlog item changes ​===+=== Regular expression testing ​===
  
-In Windows eventlog items, the //source// filter option is changed to support ​regular expressions.+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.
  
-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).+=== API changes ===
  
-=== Database monitor item changes ===+API version has been bumped to 2.2.0 and will match Zabbix version from now on.
  
-Before all ODBC parameters were stored in the item additional parameter field in the following format:+=== More data sent for '​Latest data' ===
  
-  DSN=<data source name> +//​Latest ​data// page now sends data for all entries, including collapsed ones. This may considerably increase page size in some instances.
-  user=<​user name> +
-  password=<​password>​ +
-  sql=<​query>​+
  
-In Zabbix 2.2.0, ODBC parameter storage is changed: +=== Housekeeper changes ===
-  * <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+
  
-The database upgrade will automatically convert database monitor items into the new format. The only exception is items that exceed the following limits: +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.
-  ​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 <​passwordmust be less than 65 bytes+
  
-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 file. Such items must be converted manually (shortening the problematic parameters so that they fit the new limits): +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.
-  ​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: +<​note ​warning>Housekeeper ​is disabled by default after upgrading ​to 2.2The desired housekeeper functionality should be enabled manually.</note
-<file> +=== JSON validation in server ​===
- ​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 longSee 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 monitoringiODBC 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.+Previously, slightly incorrect JSON might be accepted by the Zabbix ​serverSince Zabbix 2.2, syntax validation will be performedIf 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.
  
-=== Changes in {ESC.HISTORY} macro ===+=== Added UTF-8 validation for daemon parameters ​===
  
-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.+Daemon configuration parameter validation has been changed to disallow non-UTF-8 characters. 
 + 
 +=== Logout session verification === 
 + 
 +Logging out will now require a valid SID to be passed ​in the URL.
  
 === Screen element changes === === Screen element changes ===
Line 147: 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 154: 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