10 Upgrade notes for 3.0.0

These notes are for upgrading from Zabbix 2.4.x to Zabbix 3.0.0. All notes are grouped into:

• Critical - the most critical information related to the upgrade process and the changes in Zabbix functionality
• Informational - all remaining information describing the changes in Zabbix functionality

It is possible to upgrade to Zabbix 3.0.0 from versions before Zabbix 2.4.0. See the upgrade procedure section for all relevant information about upgrading from previous Zabbix versions.

Critical

Minimum required PHP version

The minimum required PHP version has been upped from 5.3.0 to 5.4.0.

Support for IE8 dropped

Support for Microsoft Internet Explorer 8 is not provided any more.

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.

Configuration parameters related to logging

As a new LogType configuration parameter has been added, it is important to note that previously Zabbix would log to syslog/eventlog by default if the LogFile parameter was empty. After the upgrade, Zabbix logs to file as default and the agent will not start if LogFile is not specified. To enable logging to syslog/eventlog, LogType must be set to system.

Upgrade with MariaDB 10.2.1 and before

Upgrading Zabbix may fail if database tables were created with MariaDB 10.2.1 and before, because in those versions the default row format is compact. This can be fixed by changing the row format to dynamic (see also ZBX-17690).

Informational

Item changes

net.dns and net.dns.record items on Windows now bypass the internal DNS resolver cache.

net.tcp.listen item on Linux kernels 2.6.14 and above, when detecting NETLINK capabilities, now tries to obtain information on sockets in the LISTEN state from the kernel's NETLINK interface. In case of failing to do that, it falls back on the old method of obtaining this information from the /proc virtual filesystem, which has also been improved. See What's new in Zabbix 3.0.0 for details.

vfs.fs.discovery item on Windows now returns an additional {#FSDRIVETYPE} macro with possible values of "unknown", "norootdir", "removable", "fixed", "remote", "cdrom", "ramdisk". Note, however, that if filtering by {#FSDRIVETYPE}, low-level discovery will ignore entities discovered by older agents which return responses without this macro.

SNMP discovery item OID value now accepts a discovery[{#MACRO1}, oid1, {#MACRO2}, oid2, ...] format (see low level discovery for details). The OID values of existing SNMP discovery rules will be converted to the new format (discovery[{#SNMPVALUE},<old oid value>]) during database upgrade.

A check for valid reference has been added for global regular expressions in snmptrap, log, logrt and eventlog items. If entered reference is not valid, due to misspelling or missing referenced global regular expression, the item will become unsupported and appropriate error message will be displayed.

An item to monitor VMware virtual machine CPU ready state was added to the default virtual machine monitoring template. If a performance counter based item was used to monitor virtual machine CPU ready state (for example vmware.vm.perfcounter[{$URL},{HOST.HOST},"cpu/ready[summation]"]), then it can be replaced with the new item (vmware.vm.cpu.ready[{$URL},{HOST.HOST}]).

vm.memory.size[available] item on AIX now returns the sum of free and cached memory. Before Zabbix 3.0 only the free memory size was returned.

vm.memory.size[available] item on Linux now reads MemAvailable (the system's native estimate) from /proc/meminfo on Linux kernels 3.14 and above. Depending on the system state (like the amount of reclaimable slab), the new value may differ significantly from the old version and may thus cause triggers to change their value. Before Zabbix 3.0 it was always the sum of free, buffers, and cached memories.

Items proc.mem and proc.num now return 0 if the specified user does not exist. Before Zabbix 3.0 these items became not supported.

Added items net.udp.service and net.udp.service.perf with the possibility to check NTP service. Before Zabbix 3.0 checking of NTP service was done using net.tcp.service and net.tcp.service.perf items. Database upgrade patches automatically convert NTP service checks using net.tcp.service and net.tcp.service.perf to the new item.

service_state[service] item for Windows is now deprecated. The new service.info[service,state] item should be used instead and will return the same information.

system.uname item on Windows gets values from WMI Win32_OperatingSystem and Win32_Processor classes instead of volatile Windows APIs and undocumented registry keys. After upgrade the values returned by the item might change.

Validation has been added for the 'clock' and 'ns' field values in trapper items, expecting integer timestamp values.

API changes

Deprecated exists() and getObjects() methods as well as the selectHosts and expandData parameters of the several get() methods have been removed. See API changes from 2.4 to 3.0 for details.

Daemon changes

Command-line parameter validation has been made more strict. Using the same option several times, mutually exclusive options or parameters which are not option values now is an error. Help option ('-h') does not output a version number anymore.

Default configuration file changes

Default configuration files have been changed. Most changes do not affect existing installations, but a new installation or an automated process that uses those files might have to be adjusted. See What's new in 3.0 for a list of changed parameters.

MaxHousekeeperDelete change will affect existing installations unless this parameter is specified in the configuration file.

Proxy configuration data size

Proxy configuration data size sent from server has been increased. For every item 2 new fields will be sent: "lastlogsize" and "mtime". This will result in 1-2 % increase of proxy configuration data size.

Log files

Log file rotation has been improved. This can result in a situation where the log file, after being rotated, is empty for some time. This could not happen before.

Database recovery message on DebugLevel=2

If database query fails the following message will be printed to log file: database is down: reconnecting in 10 seconds. When database goes up database connection re-established will be printed. There were no such messages on DebugLevel=2 previously.

Time to delete lost low level discovery resources

Server will now calculate the time when to delete lost low level discovery resources based on the time when it processes a discovery rule. Previously a discovery item time stamp was used for this purpose. The new logic is meant to save users from situations when the discovery item is sent via Zabbix sender with invalid time stamp. However, if the discovery item is checked via proxy and/or active agent and a delay occurs on its way to the server, this situation results in lost resources being deleted later compared to the old logic.

History cache changes

History text cache and the related internal checks (zabbix[wcache,text,<mode>]) were removed - the text data is now also stored in history cache. Depending on setup the HistoryCacheSize parameter in configuration file should be increased by the old HistoryTextCacheSize value.

History index cache was added to index the data store in history cache. The index cache size is configured by HistoryIndexCacheSize configuration file parameter. The history index cache size determines the maximum number of items that can be stored in history cache while the history cache size determines the maximum number of item values that can be stored in history cache.

When history index cache is full Zabbix exits with a corresponding error. In the worst case Zabbix must be able to store values from all items in history cache - so the index cache size must be large enough to index all items on system. The index cache size needs roughly 100 bytes to cache one item.

The history index cache usage can be monitored with internal check zabbix[wcache,index,<mode>]. See Internal checks for details.

Action and action condition caching

Actions and action conditions are now stored in configuration cache. That means changing actions or their conditions does not affect action processing until configuration cache is synchronized.

Dropping Inetd Zabbix agent

The Inetd version of Zabbix agent (zabbix_agent) has been dropped as it did not seem to have any users.

Running Windows agent in console mode

Previously the Windows agent defaulted to running in console if no service management command line options were specified. Now to run Windows agent in console the -f command line option is required.

Changes in modules

Because of adding support for log file monitoring with any value type, the AGENT_RESULT structure has been modified. This means that modules that were using it must be recompiled.

Numbered macro resolution

Server used to resolve {MACRO<1-9>} just like the ordinary {MACRO} in non-trigger-related locations. Now in such places only {MACRO} can be used, {MACRO<1-9>} won't be recognised. In trigger-related locations {MACRO<1-9>} can still be used to reference items and respective hosts in the order they appear in trigger expression. Resolution of {{HOST.HOST<1-9>}:key.func()} in graph names was not affected.

Frontend changes

• Configuration → Maps | Screens | Slide shows is not available anymore. Instead, all configuration options for these entities have been moved to Monitoring → Maps and Monitoring → Screens (that includes both screens and slide shows) sections.

• Zeroes are not displayed any more in lists for entities with no items. Whereas previously a (0) would be displayed next to the entity in a table column, now nothing is displayed.

Previous version:
Zabbix 3.0:

• A hardcoded ----[BULK ACKNOWLEDGE]---- string is no longer added to bulk acknowledgement messages by default.

• In IT service configuration, when clicking on a service name to open a popup (displaying options for adding child, editing or deleting service), the service name is no longer displayed in the heading.

• In the fullscreen view of Monitoring → Triggers, the Triggers info screen element is no longer displayed as the top line. Removing the extra element makes it consistent with other fullscreen views and improves performance of the page.

|<| |<| |-|

• Some field labels have been changed in screen element definition to be more intuitive and correct:

• History screens displaying 11 seconds more data than the selected interval has now been fixed and history screens obey the interval strictly.

• Translation of the byte unit prefixes - K for kilobytes, M for megabytes, etc. - has been removed because the "bytes" unit was not translated.

• Frontend maintenance mode superglobal variable $_REQUEST['warning_msg'] has been replaced by $ZBX_GUI_ACCESS_MESSAGE. See maintenance mode page for details.

• Popup action menu is closed when user clicks outside of it.

• The global script result window is now displayed without a header (it used to display a Result of "script name" string). The header is reinstated in version 3.0.3.

• Changes in value mapping allow to preserve these settings for the imported/exported hosts and templates. However, if you want to import host/template with custom "Host status" value map created in previous Zabbix versions you should recreate this setting in Administration → General → Value mapping before importing as this setting was enhanced and renamed in Zabbix 3.0.

• User and user group permission form has been redesigned. Permissions are no longer displayed in colour-coded listboxes.

• When copying elements, the copy page (where you choose the copy target) is not showing the element count any more.

Trigger function improvements

A check for valid reference has been added for global regular expressions in logeventid(), regexp() and iregexp() trigger functions. If entered reference is not valid, due to misspelling or missing referenced global regular expression, the trigger will switch to unknown state and appropriate error message will be displayed.

Logging IP addresses of connections between server and proxy

The messages printed to the log files will now contain IP addresses of incoming/outgoing connections between Zabbix server and Zabbix proxy.

The following messages were removed:

sending heartbeat message to server failed: <ERROR>
       Error while sending data to the server [<ERROR>]
       Error while receiving answer from server [<ERROR>]
       cannot obtain configuration data from server: <ERROR>
       received configuration data from server, datalen <LENGTH>
       sending host availability data to server failed: <ERROR>
       sending data to server failed: <ERROR>
       cannot collect proxy configuration: <ERROR>
       sending configuration data to proxy "<PROXY>", datalen <LENGTH>
       cannot send proxy configuration, error:"<ERROR>", info:"<INFO>"
       host availability data from active proxy on "<IP>" failed: <ERROR>
       error while sending host availability data to server: <ERROR>
       sending host availability data to server: error:"<ERROR>", info:"<INFO>"
       proxy configuration request from active proxy on "<IP>" failed: <ERROR>
       cannot collect proxy configuration: <ERROR>
       sending configuration data to proxy "<PROXY>", datalen <LENGTH>
       cannot send configuration: <ERROR>
       invalid proxy configuration data: <ERROR>
       autoregistration data from active proxy on "<IP>" failed: <ERROR>
       error while sending auto-registration data to server: <ERROR>
       sending auto-registration data to server: error:"<ERROR>", info:"<INFO>"
       discovery data from active proxy on "<IP>" failed: <ERROR>
       error while sending discovery data to server: <ERROR>
       sending discovery data to server: error:"<ERROR>", info:"<INFO>"
       history data from active proxy on "<IP>" failed: <ERROR>
       error while sending history data to server: <ERROR>
       sending history data to server: error:"<ERROR>", info:"<INFO>"
       heartbeat from active proxy on "<IP>" failed: <ERROR>
       misconfiguration error: the proxy is running in the active mode but server sends requests to it as to proxy in passive mode
       received configuration data from server, datalen <LENGTH>

The following messages were introduced and correspond to the removed messages above:

cannot send heartbeat message to server at "<IP>": <ERROR>
       cannot obtain configuration data from server at "<IP>": <ERROR>
       received configuration data from server at "<IP>", datalen <LENGTH>
       cannot send host availability data to server at "<IP>": <ERROR>
       cannot send history data to server at "<IP>": <ERROR>
       cannot collect configuration data for proxy "<PROXY>": <ERROR>
       sending configuration data to proxy "<PROXY>" at "<IP>", datalen <LENGTH>
       cannot send configuration data to proxy "<PROXY>" at "<IP>": <ERROR>
       cannot parse host availability data from active proxy at "<IP>": <ERROR>
       cannot send host availability data to server at "<IP>": <ERROR>
       cannot parse proxy configuration data request from active proxy at "<IP>": <ERROR>
       cannot collect configuration data for proxy "<PROXY>" at "<IP>": <ERROR>
       sending configuration data to proxy "<PROXY>" at "<IP>", datalen <LENGTH>
       cannot send configuration data to proxy "<PROXY>" at "<IP>": <ERROR>
       cannot parse proxy configuration data received from server at "<IP>": <ERROR>
       cannot parse autoregistration data from active proxy at "<IP>": <ERROR>
       cannot send auto-registration data to server at "<IP>": <ERROR>
       cannot parse discovery data from active proxy at "<IP>": <ERROR>
       cannot send discovery data to server at "<IP>": <ERROR>
       cannot parse history data from active proxy at "<IP>": <ERROR>
       cannot send history data to server at "<IP>": <ERROR>
       cannot parse heartbeat from active proxy at "<IP>": <ERROR>
       misconfiguration error: the proxy is running in the active mode but server at "<IP>" sends requests to it as to proxy in passive mode
       received configuration data from server at "<IP>", datalen <LENGTH>

See also

• Template changes