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 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.

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 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⁶³-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):

1. add <data source name> to item key as the second parameter
2. move <user name>, <password> into respective Username, Password fields
3. leave only <query> in the <SQL query> field

Item conversion failure warning message examples:

 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.

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 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 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 → 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.

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