Zabbix Documentation 3.4

2.23.04.04.2 (current)In development:4.4 (devel)Unsupported:1.82.02.43.23.4

User Tools

Site Tools


manual:installation:upgrade_notes_340

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Previous revision
manual:installation:upgrade_notes_340 [2018/12/05 11:48]
manual:installation:upgrade_notes_340 [2019/02/12 06:39] (current)
martins-v formatting change
Line 1: Line 1:
 +==== 10 Upgrade notes for 3.4.0 ====
  
 +These notes are for upgrading from Zabbix 3.2.x to Zabbix 3.4.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.4.0 from versions before Zabbix 3.2.0. See the [[:​manual/​installation/​upgrade|upgrade procedure]] section for all relevant information about upgrading from previous Zabbix versions.
 +
 +==== Critical ====
 +
 +=== Dropping SQLite support for server/​frontend ===
 +
 +SQLite is no longer supported as a backend database for Zabbix server and frontend. It is still supported for Zabbix proxy.
 +
 +=== Dropping IE9 and IE10 support ===
 +
 +Support for Microsoft Internet Explorer 9 and Explorer 10 will not be provided any more.
 +
 +=== Clearing web browser cookies/​cache ===
 +
 +After the upgrade you may need to clear web browser cookies and web browser cache for the frontend to work properly.
 +
 +===  Additional dependencies ===
 +  * libpcre - the PCRE library is now mandatory when compiling Zabbix server. It is required for [[https://​en.wikipedia.org/​wiki/​Perl_Compatible_Regular_Expressions|Perl Compatible Regular Expression]] (PCRE) support. The naming may differ depending on the GNU/Linux distribution,​ for example '​libpcre3'​ or '​libpcre1'​. Note that you need exactly PCRE (v8.x); PCRE2 (v10.x) library is not used;
 +  * libevent (version 1.4 or later) library is now mandatory: ​
 +    * for Zabbix server always;
 +    * for Zabbix proxy if compiling with IPMI monitoring.
 +
 +=== 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.
 +
 +=== PCRE library for regular expressions ===
 +
 +Regular expression support in Zabbix has been switched from POSIX extended regular expressions to [[https://​en.wikipedia.org/​wiki/​Perl_Compatible_Regular_Expressions|Perl Compatible Regular Expressions]] (PCRE) for enhanced regular expressions and consistency with the frontend. While PCRE is mostly compatible with POSIX, still there are some differences such as that POSIX functions find the longest of the leftmost match, but PCRE stops on the first valid match. POSIX equivalence classes and collating elements are not supported. ​
 +
 +<note warning>​As some regular expressions may yield different results after the upgrade, before upgrading you must review the regular expressions in use in supported [[:​manual/​regular_expressions#​regular_expression_support_by_location|locations]]. Expressions where the previous syntax may lead to a different result after the upgrade must be manually converted to PCRE regular expression syntax yielding the same result as before the upgrade.\\ \\ See also: [[http://​www.greenend.org.uk/​rjk/​tech/​regexp.html|Differences between]] POSIX extended and PCRE regular expressions. </​note>​
 +
 +<note tip>GNU grep utility supports both POSIX extended regular expressions (with '​-E'​ switch) and PCRE regular expressions (with '​-P'​ switch). You can run it first with an '​-E',​ then with a '​-P'​ switch with the regular expression and analyze the test file. If both outputs are not identical to the expected, the regular expression should be modified to work correctly after upgrade.</​note>​
 +
 +Note that if you upgrade only server and proxies, but some hosts continue to use older Zabbix agents (before v3.4), those older agents still "​understand"​ POSIX regular expressions only. Regular expressions used in their log[], logrt[] etc items should not be modified to PCRE syntax until the agents are upgraded.
 +
 +=== Command/​script execution changes ===
 +
 +Due to command/​script exit code check [[manual/​introduction/​whatsnew340#​return_code_check_for_scripts_and_commands|introduction]] in Zabbix 3.4, [[manual/​config/​notifications/​media/​script|alertscripts]] can be executed multiple times if their exit code is different from 0. Previously configured items with user parameters executed by Zabbix server, external check items, and **system.run** items whose exit code is not 0 may become “Not supported” due to additional checks for exit code; behaviour of the items with "​nowait"​ flag is not changed though.
 +
 +===  Configuration parameters ===
 +
 +The ''​SenderFrequency''​ [[:​manual/​appendix/​config/​zabbix_server|configuration]] parameter has been removed. It must be removed from server configuration for 3.4 when upgrading, otherwise you will get an error and the server **will not** start. Retry frequency of failed alerts is now looked up in the [[:​manual/​config/​notifications/​media/​email#​options|media type]] configuration (//Attempt interval// parameter) and is 10 seconds by default. The default of SenderFrequency used to be 30 seconds.
 +
 +=== URL-encoding in web scenarios ===
 +
 +While [[:​manual/​introduction/​whatsnew340#​automatic_url-encoding|automatic URL-encoding]] is supported starting with Zabbix 3.4, values in existing scenarios will not be automatically converted to URL-encoding. If you want those values URL-encoded you have to edit the [[:​manual/​web_monitoring#​configuring_steps|scenarios]] manually using the new fields:
 +
 +  * move query variables from the URL into //Query fields//
 +  * move post variables from //Raw data// into //Form data//
 +
 +If you have already manually URL-encoded values they will be left as is and will not be double URL-encoded.
 +
 +=== Upgrading Java gateway ===
 +
 +Zabbix Java gateway has to be upgraded to support the new functionality of: 
 +
 +  * [[:​manual/​introduction/​whatsnew340#​configurable_jmx_endpoints|configurable JMX endpoints]];​
 +  * [[:​manual/​discovery/​low_level_discovery/​jmx|low-level discovery of JMX objects]].
 +
 +=== JMX item protocol changes ===
 +
 +An example of the new protocol:
 +
 +<​code>​
 +{"​request":"​java gateway jmx","​jmx_endpoint":"​service:​jmx:​rmi:///​jndi/​rmi://​127.0.0.1:​12345/​jmxrmi","​keys":​["​jmx[\"​java.lang:​type={#​FSNAME}\",​\"​HeapMemoryUsage.used\"​]"​]}
 +</​code>​
 +
 +==== Informational ====
 +
 +=== Configuration parameters ===
 +
 +A new configuration parameter ''​SocketDir''​ has been added to Zabbix server and proxy configurations. This parameter points to the directory where internal Zabbix socket files are stored (/tmp by default). Server and proxy use different socket file names so it's safe to use the same ''​SocketDir''​ for server and proxy running on the same system. However, running multiple servers or proxies in the same system will require different ''​SocketDir''​ configurations.
 +
 +=== Dashboard changes ===
 +
 +The dashboard section has seen a major [[:​manual/​introduction/​whatsnew340#​new_dashboards|overhaul]] in Zabbix 3.4, which brings a number of related changes:
 +
 +  * The //Last 20 issues// widget has been removed and replaced by a //​Problems//​ widget, which is similar in layout to the //​Monitoring//​ -> //​Problems//​ section. Because of this, the DEFAULT_LATEST_ISSUES_CNT frontend [[:​manual/​web_interface/​definitions|definition]] is not used any more and has been removed.
 +  * //​Problems//​ and //System Status// widgets no longer display triggers in the PROBLEM state if there is no corresponding event (i.e., the event is deleted)
 +
 +=== Map permission changes ===
 +
 +Maps are no longer hidden if the user does not have read permission to all map elements. Instead, the map is shown, proving the user has read access to at least one map element. The elements that the user does not have read permission to are displayed with a grey icon and without any textual information on it (except for triggers which do have labels).
 +
 +See also: [[:​manual/​config/​visualisation/​maps/​map#​access_based_on_permissions|Network map configuration]]
 +
 +=== Using templates for network devices ===
 +
 +If you are importing the new out-of-the-box [[:​manual/​config/​templates_out_of_the_box/​network_devices|templates for network devices]], you may want to also update the ''​@Network interfaces for discovery''​ global regular expression to:
 +
 +<​code>​
 +Result is FALSE: ^Software Loopback Interface
 +Result is FALSE: ^(In)?​[lL]oop[bB]ack[0-9._]*$
 +Result is FALSE: ^NULL[0-9.]*$
 +Result is FALSE: ^[lL]o[0-9.]*$
 +Result is FALSE: ^[sS]ystem$
 +Result is FALSE: ^Nu[0-9.]*$
 +</​code>​
 +
 +to filter out loopbacks and null interfaces on most systems.
 +
 +=== Support of macros and time suffixes in time periods ===
 +
 +To allow for an extended macro and time suffix [[:​manual/​introduction/​whatsnew340#​support_of_macros_and_time_suffixes_in_time_periods|support]],​ several fields that previously stored their value in days have been converted to store the values **in seconds**, e.g.:
 +
 +  * History/​trend storage period in items and item prototypes
 +  * //Keep lost resources// setting in low-level discovery
 +  * Global housekeeping settings
 +
 +While the numeric values are adjusted automatically during an upgrade, it is a **different** case if the //Keep lost resources// setting contained a macro before the upgrade. Its value (in days) is no longer valid in this field and cannot be adjusted by simply appending '​d'​ to the macro, because that is not an allowed macro syntax. The macro value cannot be changed either, because the macro may be used in other places. Therefore in this case during an upgrade the //Keep lost resources// setting is automatically converted to the maximum value of 25 years. This is something to take care of manually after the upgrade.
 +
 +=== Parallel processing of alerts ===
 +
 +Previously all problem notifications were handled by one alerter process. In the new version, **parallel processing** of alerts is implemented. There is a new alert manager process that can distribute alerts to several "​worker"​ processes. Media types are processed in parallel. The maximum number of concurrent sessions is configurable per media type, but the total number of alerter processes on server can only be limited by the new StartAlerters [[:​manual/​appendix/​config/​zabbix_server|parameter]].
 +
 +During an upgrade, the number of concurrent sessions is set as '​1'​ for each media type, while the default value of StartAlerters is '​3'​. For the e-mail media type, you may want to [[:​manual/​config/​notifications/​media/​email#​options|manually]] increase the number of concurrent sessions or set it to '​0'​ (unlimited) for faster processing of alerts.
 +
 +Alert manager will now also fail alert scripts without access rights, without retrying.
 +
 +=== Database watchdog removed ===
 +
 +The database watchdog process (db watchdog) has been removed and its tasks are now handled by the [[:​manual/​installation/​upgrade_notes_340#​parallel_processing_of_alerts|alerter process]]. If you are monitoring your Zabbix server using the //Template App Zabbix Server// template you might get an unsupported item '​Zabbix busy db watchdog processes, in %'. In this case just remove or disable this item from the template.
 +
 +=== IT services renamed to services ===
 +
 +Configuration and monitoring sections that previously were called "IT services"​ have been renamed to "​Services"​ to reflect the fact that a broader range of services can be measured, not only IT.
 +
 +=== Item value preprocessing options ===
 +
 +Item value preprocessing options have been [[:​manual/​introduction/​whatsnew340#​item_value_preprocessing|unified]] and expanded as a separate tab in item configuration. As a result, several of the previously separate preprocessing parameters in items/item prototypes have been dropped:
 +
 +  * //Data type//, //Use custom multiplier//​ and //Store value// fields
 +  * ''​data_type'',​ ''​multiplier''​ and ''​delta''​ fields in API
 +  * ''​data_type'',​ ''​multiplier''​ and ''​delta''​ tags in XML export
 +
 +During an upgrade, all of these properties in existing items/item prototypes are converted to the new preprocessing options automatically. Similarly, when importing XMLs from older versions, these options are converted to the new preprocessing options.
 +
 +Additionally,​ //Delta (simple change)// and //Delta (speed per second)// preprocessing options have been renamed to //Simple change// and //Change per second//.
 +
 +<note important>​Too many data gathering processes (pollers, unreachable pollers, HTTP pollers, Java pollers, pingers, trappers, proxypollers) together with IPMI manager, SNMP trapper and preprocessing workers can exhaust the per-process file descriptor limit for the preprocessing manager. This will cause Zabbix server to stop (usually shortly after the start, but sometimes it can take more time). The configuration file should be revised or the limit should be raised to avoid this situation.</​note>​
 +
 +=== Item changes ===
 +
 +Previously the //sleep// parameter of the **proc.num** agent item on FreeBSD, OpenBSD and NetBSD platforms incorrectly counted processes in both interruptible sleep and uninterruptible sleep state. Now it has been fixed to count processes only in interruptible sleep while the new //disk// parameter can be used to obtain process count in uninterruptible sleep.
 +
 +=== Macro changes ===
 +
 +Since event correlation was introduced in Zabbix 3.2.0, the {TRIGGER.STATUS} macro could no longer be relied upon to accurately show problem status - the problem could already be resolved with the original trigger still in '​Problem'​ status. Therefore {TRIGGER.STATUS} has now been removed from default notification messages.
 +
 +Instead, accurate problem status can now be acquired by using {EVENT.VALUE} and {EVENT.STATUS} macros. These macros have been changed and now return (for trigger and internal events):
 +
 +  * '​Problem'​ value if the original event is still in problem state;
 +  * '​OK'​ value if the original event has been resolved.
 +
 +=== Syntax for selecting nested host groups ===
 +
 +If upgrading from Zabbix 3.2.0 and 3.2.1, note that the syntax for including nested subgroups has changed.
 +
 +In Zabbix 3.2.0 and 3.2.1 nested host groups are included with the parent host group, it the parent group is specified as ''​hostgroup/​*''​. Since [[https://​www.zabbix.com/​documentation/​3.2/​manual/​introduction/​whatsnew322|Zabbix 3.2.2]] and in Zabbix 3.4.0, the '/​*'​ syntax is dropped. Instead, nested host groups are included if simply the parent host group is specified as is. This means that a host group that is set, for example, in action conditions, now **silently** includes all its nested host groups.
 +
 +=== Protocol changes ===
 +
 +Communication protocol between the frontend side and server side has been changed. A new "​sid"​ parameter has been added to the request from frontend to server for script execution. This parameter takes the ID of session (authentication token) and it is used to check the user permissions to execute scripts. Also, an additional check for host permissions (READ/​WRITE,​ READ and DENY) in the script has been added to this request. If the necessary access rights to the host are missing, the server will return a response that access to execute the script is denied.
 +
 +=== API changes ===
 +
 +  * Deprecated ''​isreadable()''​ and ''​iswritable()''​ methods as well as the ''​proxy.interfaces''​ parameter have been removed.
 +  * Validation of "​period"​ field has been added disallowing a trailing semicolon. All existing trailing semicolons will be removed by proxy/​server during upgrade.  ​
 +
 +=== Changed housekeeper defaults ===
 +
 +The default data storage period for internal, discovery and agent auto-registration events has been decreased from 365 days to 1 day. When upgrading from previous versions, it is recommended to decrease these values to 1 day manually as it can improve Zabbix server performance.
 +
 +=== Possible issues with SELinux ===
 +
 +Socket-based inter-process communication has been added in Zabbix 3.4. On systems where SELinux is enabled it may be required to add SELinux rules to allow Zabbix create/use UNIX domain sockets in the ''​SocketDir''​ directory. Currently socket files are used by server (alerter, preprocessing,​ IPMI) and proxy (IPMI). Socket files are persistent, meaning are present while the process is running.
 +
 +==== See also ====
 +
 +  * [[:​manual/​installation/​template_changes|Template changes]]