Zabbix Documentation 2.2

3.04.04.2 (current)In development:4.4 (devel)Unsupported:1.82.02.22.43.23.4

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

manual:installation:upgrade_notes_220 [2018/12/05 11:48]
manual:installation:upgrade_notes_220 [2017/02/16 10:09] (current)
martins-v note about case-sensitive MySQL database
Line 1: Line 1:
 +==== -#8 Upgrade notes for 2.2.0 ====
  
 +=== Requirement changes ===
 +
 +  * 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
 +  * The "​mysqli"​ PHP extension is required instead of "​mysql"​
 +  * 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 ===
 +
 +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>​Automatic database upgrade for SQLite is not supported.</​note>​
 +
 +=== 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"​.
 +
 +=== 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 ===
 +
 +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.
 +
 +=== 64-bit range for object IDs ===
 +
 +Zabbix now supports a signed 64-bit range for internal object IDs in a standalone, non-distributed setup. Thus the highest available number of one-type objects is 2<​sup>​63</​sup>​-1 now.
 +
 +=== Database monitor item changes ===
 +
 +Before all ODBC parameters were stored in the item additional parameter field in the following format:
 +
 +  DSN=<​data source name>
 +  user=<​user name>
 +  password=<​password>​
 +  sql=<​query>​
 +
 +In Zabbix 2.2.0, ODBC 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
 +
 +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
 +
 +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):
 +  - 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:
 +<​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.
 +
 +=== Internal check changes ===
 +
 +The **zabbix[items]** internal check will now return the number of monitored items instead of the total number of items in database.
 +
 +Internal checks of the hosts monitored by proxies are now processed by the proxies.
 +
 +=== Empty string returned instead of EOF ===
 +
 +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 ===
 +
 +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.
 +
 +=== 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.
 +
 +=== Changes in system.uname item ===
 +
 +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 ===
 +
 +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. 
 +
 +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.
 +
 +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]].
 +
 +=== Changes in {ESC.HISTORY} macro ===
 +
 +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.
 +
 +=== Regular expression testing ===
 +
 +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.
 +
 +=== API changes ===
 +
 +API version has been bumped to 2.2.0 and will match Zabbix version from now on.
 +
 +=== More data sent for '​Latest data' ===
 +
 +//Latest data// page now sends data for all entries, including collapsed ones. This may considerably increase page size in some instances.
 +
 +=== Housekeeper changes ===
 +
 +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.
 +
 +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.
 +
 +<note warning>​Housekeeper is disabled by default after upgrading to 2.2. The desired housekeeper functionality should be enabled manually.</​note>​
 +=== JSON validation in server ===
 +
 +Previously, slightly incorrect JSON might be accepted by the Zabbix server. Since 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.
 +
 +=== Added UTF-8 validation for daemon parameters ===
 +
 +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 ===
 + 
 +//Status of host triggers// and //Status of host group triggers// screen elements have been renamed to //Host issues// and //Host group issues// respectively. ​
 + 
 +Previously, triggers without events would not be displayed in these two widgets, nor in the //Last 20 issues// widget. Now triggers wothout events are displayed as well in all three places.
 +
 +=== Dashboard widget position saving mechanism ===
 +
 +After upgrade to 2.2, custom dashboard layouts will be lost. This is caused by the dashboard widget positions, previously saved in a cookie, now being saved in the database.
 +
 +After the upgrade, browsers may have a dashboard cookie that is not used anymore, because in the new version there is no functionality for working with them.
 +
 +=== Changed trapper response to sent data ===
 +
 +Before Zabbix 2.2.0, a trapper response to the values sent by an active agent/​sender contained an info field in the following format:
 +  Processed <N> Failed <N> Total <N> Seconds spent <N>
 +Starting with Zabbix 2.2.0, the formatting of the info field was changed to be more readable:
 +  processed: <N>; failed: <N>; total: <N>; seconds spent: <N>
 +
 +=== Zabbix sender exit status changes ===
 +
 +Starting with Zabbix 2.2.0 the Zabbix sender will finish with exit status 0 only if all of the values were sent and processed successfully. If processing of at least one of values failed the exit status will be 2. If data sending failed the exit status will be 1. 
 +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 ===
 +
 +Column order for //alerts// table will be different after upgrade as compared to a fresh install (Oracle only). This is caused by inability to change column type from //varchar// to //nclob// and insert a column in a specific place on Oracle. It should not cause any functional differences.
 +
 +=== Item help definition moved to PHP code ===
 +
 +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