Table of Contents

11 Upgrade notes for 7.0.0

11 Upgrade notes for 7.0.0

These notes are for upgrading from Zabbix 6.4.x to Zabbix 7.0.0.

All notes are grouped into:

Breaking changes - changes that may break existing installations and other critical information related to the upgrade process
Other - all remaining information describing the changes in Zabbix functionality

Upgrade process

To complete a successful Zabbix server upgrade on MySQL/MariaDB, you may require to set GLOBAL log_bin_trust_function_creators = 1 in MySQL if binary logging is enabled, there are no superuser privileges and log_bin_trust_function_creators = 1 is not set in MySQL configuration file.

To set the variable using the MySQL console, run:

mysql> SET GLOBAL log_bin_trust_function_creators = 1;

Once the upgrade has been successfully completed, this option can be disabled:

mysql> SET GLOBAL log_bin_trust_function_creators = 0;

Breaking changes

Server crash with TimescaleDB after upgrade to 7.0.1 from 7.0.0

Upgrading to Zabbix 7.0.1 (or later) from Zabbix 7.0.0 with TimescaleDB results in a server crash. This issue is caused by a workaround to a compression job issue in the auditlog table in Zabbix 7.0 that irreversibly changes the compression policy of the auditlog table.

See known issues for details of fixing the auditlog table manually.

If you have not upgraded to Zabbix 7.0.0 yet, note that there should be no such issues for upgrades from pre-7.0 Zabbix versions to 7.0.1. For upgrade instructions, see Upgrading TimescaleDB schema.

Database restore error with PostgreSQL/TimescaleDB after upgrade from 7.0.0-7.0.4

Using pg_restore to restore a PostgreSQL or TimescaleDB backup created in Zabbix 7.0.0-7.0.4 will result in a missing base36_decode function error, causing the restore to fail. This error occurs when restoring a backup created with pg_dump.

See known issues for details on fixing this issue manually before creating the backup.

If you have not upgraded to Zabbix 7.0.0 yet, note that there should be no such issues for upgrades from pre-7.0 Zabbix versions to 7.0.5. For upgrade instructions, see Upgrading TimescaleDB schema.

Escaping of backslashes in history function parameters

Proper escaping of backslashes has been added in history function string parameters.

As additional backslashes are added during the upgrade from pre-7.0 Zabbix versions, this leads to longer parameters which may result in broken trigger functions if the parameter length exceeds the maximum data size of 255 characters.

To avoid this problem it is suggested to manually move long parameters into user macros before the upgrade.

Note that since Zabbix 7.0.11 additional checks for the resulting parameter length have been added for upgrades from pre-7.0 Zabbix versions. If the resulting length exceeds the maximum size, such parameters are not upgraded while printing a warning in the logs asking users to fix the listed parameters manually.

Minimum required PHP version

The minimum required PHP version has been raised from 7.4.0 to 8.0.0.

Default location for Windows agent configuration file

The default location where Zabbix agent on Windows looks for the configuration file has been changed. Now the agent searches for it in the directory where the agent binary zabbix_agentd.exe is located (instead of C:\zabbix_agentd.conf, as previously).

Zabbix agent 2 on Windows already searched for the default configuration file in the directory where the binary zabbix_agent2.exe is located. However, in the new version the agent 2 expects the configuration file to be named zabbix_agent2.conf (instead of zabbix_agent2.win.conf)

Empty values allowed in agent 2 plugin configuration

Empty values are now allowed in plugin-related configuration parameters on Zabbix agent 2.

TimescaleDB 1.x no longer supported

Support of TimescaleDB 1.x has been removed.

Double precision data types on TimescaleDB

Before upgrading to Zabbix 7.0.0, it is necessary to manually upgrade TimescaleDB to use double precision data types if TimescaleDB is used with compression. You can tell if TimescaleDB is not using double precision data types by the warning in the System information frontend section or Zabbix server log: "Database is not upgraded to use double precision values. Support for the old numeric type will be removed in future versions."

For more information, see Upgrading to numeric values of extended range.

Auditlog converted to hypertable on TimescaleDB

The auditlog table has been converted to hypertable on TimescaleDB in new installations to benefit from automatic partitioning on time (7 days by default) and better performance.

To successfully upgrade existing installations, see Upgrading TimescaleDB schema.

Separate database table for proxies

Proxy records have been moved out of the hosts table and are now stored in the new proxy table.

Also, operational data of proxies (such as last access, version, compatibility) have been moved out of the host_rtdata table and is now stored in the new proxy_rtdata table.

There is also a new proxy object in API. All operations with proxies should be updated to be done via this new proxy object.

Query execution timeout for database monitor items

Based on the changes to item timeout configuration, both ODBC login timeout and query execution timeout for database monitor items are now limited to the Timeout parameter value set in the item configuration form.

Updated agent/agent2 items

wmi.get and wmi.getall, when used with Zabbix agent 2, now return a JSON with boolean values represented as strings (for example, "RealTimeProtectionEnabled": "True" instead of "RealTimeProtectionEnabled": true returned previously) to match the output format of these items on Zabbix agent;
oracle.ts.stats has a new conname parameter to specify the target container name. The JSON format of the returned data has been updated. When no tablespace, type, or conname is specified in the key parameters, the returned data will include an additional JSON level with the container name, allowing differentiation between containers.
net.dns.* items can no longer be configured without the name parameter. Although always listed as mandatory, the name parameter, if omitted, would previously resolve to a default value (zabbix.com), which is no longer the case.

For the list of item changes that do no break compatibility, see What's new in Zabbix 7.0.0.

SNMP traps with Zabbix high availability

Zabbix now can read SNMP trap files from the correct place in case the active node is switched in a high-availability setup.

However, for this functionality to work it is required to update the time format in any bash, perl and SNMPTT scripts to "%Y-%m-%dT%H:%M:%S%z" (i.e. 2024-01-10T11:56:14+0300).

Increased maximum size and number of dashboard widgets

The default width has been increased 3 times for all widgets. Note that if you are using custom widgets, you may have to update the respective parameters of the manifest.json file (for example, when configuring a customized Clock widget, width is to be changed from 4 to 12).

A widget may now be up to 72 columns in width (previously 24) and 1 to 64 rows in height (previously 2 to 32). The dashboard can therefore now hold up to 72 widgets horizontally.

Item history and Plain text widgets

The new Item history dashboard widget has replaced the Plain text widget, offering several improvements.

Unlike the Plain Text widget, which only displayed the latest item data in plain text, the Item History widget supports various display options for multiple item types (numeric, character, log, text, and binary). For example, it can show progress bars or indicators, images for binary data types (useful for browser items), and highlight text values (useful for log file monitoring).

After the upgrade, all previously configured Plain text widgets will be automatically replaced with Item history widgets, retaining the same configuration settings. However, any API scripts referencing the Plain Text widget must be updated manually.

Changes in the resolution of certain built-in macros after upgrade to 7.0.4

In Zabbix 7.0.4, the behavior of resolving the macros {HOST.CONN}, {HOST.DNS}, {HOST.IP}, {EVENT.CAUSE.*}, {EVENT.TAGS.*}, and {EVENT.SYMPTOMS} has been corrected for consistency with other built-in macros. Now, they will resolve to *UNKNOWN* if an error occurs while evaluating their value.

As a result of this change, to ensure proper functionality, it is necessary to update the media types for the following integrations: iTop, Jira Service Desk, ManageEngine ServiceDesk, SolarWinds Service Desk.

This change may also affect any custom scripts or integrations using the abovementioned macros.

API changes

See the list of API changes in Zabbix 7.0.0.

Other

Oracle DB deprecated

The support for Oracle as a backend database has been deprecated since Zabbix 7.0 and is expected to be completely removed in future versions.

Software update check

A software update check is now added by default to new and existing installations - Zabbix frontend will communicate to the public Zabbix endpoint to check for updates.

You can disable this check by setting AllowSoftwareUpdateCheck=0 in server configuration.

Floating point values trimmed for integer items

Now, if a floating point value is received for an unsigned integer item, the value will be trimmed from the decimal part and saved as an integer. Previously a floating point value would make an integer item unsupported.

US time format

Time and date displays in the frontend now conform to the US standard time/date display when the default (en_US) frontend language is used.

Before	Now

Asynchronous pollers

After the upgrade all agent, HTTP agent and walk[OID] SNMP checks will be moved to asynchronous pollers.

Detecting cURL library features at runtime

Previously cURL library features were detected at build time of Zabbix server, proxy or agent. If cURL features were upgraded, to make use of them the respective Zabbix component had to be recompiled.

Now only a restart is required for upgraded cURL library features to become available in Zabbix. Recompilation is no longer required. This is true for Zabbix server, proxy or agent.

In addition:

Minimum required build-time cURL version was raised to 7.19.1;
When being built Zabbix just checks if the cURL library is available (if requested) and satisfies the version requirement;
When issuing a runtime cURL library error the version being in use will be added (e.g. "cURL library does not support SSL/TLS (using version 7.88.1)");
When Zabbix server is started and SMTP authentication is logged it will write the availability of SMTP authentication of cURL library being used.

Item timeout configuration changes

Upon upgrade, global timeouts for all supported item types will be set based on the Timeout parameter value from the server configuration file. If a proxy is configured, then, by default, it will use the server's global timeout settings.

When using an upgraded server (version 7.0.0 or newer) with an older proxy or agent, the proxy or agent will work as before:

the proxy will use the Timeout parameter from the proxy configuration file;
the agent will use the Timeout parameter from the agent configuration file.

The timeout parameters have been removed from the configuration files of Modbus and MQTT plugins. The request execution timeouts can now be set using the item configuration form.

Browser items

A new item type - Browser item - has been added to Zabbix, enabling the monitoring of complex websites and web applications using a browser. Browser items allow the execution of user-defined JavaScript code to simulate browser-related actions such as clicking, entering text, navigating through web pages, etc.

Additionally, this feature adds the following changes:

Website by Browser template has been added to templates out of the box;
ITEM_TYPE_BROWSER (22) item type has been added to template or host item, low-level discovery rule, and item prototype configuration export/import;
StartBrowserPollers and WebDriverURL Zabbix server/proxy configuration file parameters have been added;
Browser item timeout has been added to proxy timeouts or global timeouts (if a proxy is not used);
-w <webdriver url> command-line parameter for enabling browser monitoring has been added to the zabbix_js command-line utility.

Concurrency in network discovery

In the new version the network discovery process has been reworked to allow concurrency between service checks. A new discovery manager process has been added along with a configurable number of discovery workers (or threads). The discovery manager processes discovery rules and creates a discovery job per each rule with tasks (service checks). The service checks are picked up and performed by the discovery workers.

The StartDiscoverers parameter now determines the total number of available discovery workers for discovery. The default number of StartDiscoverers has been upped from 1 to 5, and the range from 0-250 to 0-1000. The discoverer processes from previous Zabbix versions have been dropped.

Additionally, the number of available workers per each rule is now configurable in the frontend. This parameter is optional. During the upgrade it will be set to "One" as in previous Zabbix versions.

Icons replaced by fonts

All icons in the frontend have been switched from icon image sheets to fonts.

Latest data filter

In Monitoring → Latest data, the subfilter and data are no longer displayed by default if the filter is not set. Note, however, that previously saved filters that were set using only the subfilter remain unaffected. In such cases, the subfilter will remain visible, and data will be displayed even without the main filter being set.

Configuration parameters

The default value for several configuration parameters has been changed:

BufferSize configuration parameter for Zabbix agent 2 has been increased from 100 to 1000;
Plugins.<PluginName>.System.Capacity configuration parameter for Zabbix agent 2 has been increased from 100 to 1000 (maximum). Note that the parameter Plugins.<PluginName>.Capacity, deprecated in Zabbix 6.0, has been removed completely;
StartAgents configuration parameter for Zabbix agent has been increased from 3 to 10. Note in packaging that for smaller systems (i.e. Raspberry Pi) the default value may remain 3.

These changes do not affect existing installations where these parameters are explicitly set.

Aggregate calculations

Several aggregate functions have been updated. Now:

Aggregate functions now also support non-numeric types for calculation. This may be useful, for example, with the count and count_foreach functions.
The count and count_foreach aggregate functions support optional parameters operator and pattern, which can be used to fine-tune item filtering and only count values that match given criteria.
All foreach functions no longer include unsupported items in the count.
The function last_foreach, previously configured to ignore the time period argument, accepts it as an optional parameter.

Old numeric (float) value type dropped

Since Zabbix 5.0, numeric (float) data type supports precision of approximately 15 digits and range from approximately -1.79E+308 to 1.79E+308. The old numeric type was disabled but still supported. As of Zabbix 6.4, it was deprecated, and starting with Zabbix 7.0, it has been fully removed.

If your installation has not been upgraded to use numeric values of extended range, the following warning is displayed in Reports → System information: "Database history tables upgraded: No. Support for the old numeric type is deprecated. Please upgrade to numeric values of extended range".

When upgrading to Zabbix 7.0, the following databases are upgraded automatically:

MySQL
PostgreSQL/TimescaleDB (without compression)
Oracle

However, for Oracle, older MySQL versions, and large installations, it is recommended to upgrade the data type manually before upgrading to Zabbix 7.0.

For TimescaleDB with compression, the database must be upgraded manually.

For upgrade details, see Upgrading to numeric values of extended range.

Setting Windows agent service startup type

The option to set the startup type of the Zabbix agent/agent 2 Windows service (-S --startup-type) has been added. This option allows configuring the agent/agent 2 service to start automatically at Windows startup (automatic), after the automatically started services have completed startup (delayed), when started manually by a user or application (manual) or to disable the service entirely (disabled).

When performing Windows agent installation from MSI, the default startup type on Windows Server 2008/Vista and later versions is now delayed if not specified otherwise in the STARTUPTYPE command-line parameter. This improves the reliability and performance of the Zabbix agent/agent 2 Windows service, particularly during system restarts.

Templates

For new templates and changes to existing templates, see Template changes.

When installing Zabbix from packages and preparing the database schema, the location of database-related files has changed to better correspond to the file structure in the sources:

Base initialization files (schema.sql, data.sql, images.sql) are located at the root of the database directory.
Optional files/patches for upgrading database tables are located in the option-patches directory.
Database extensions and addons are now subdirectories, named after the extension and located in the respective database directory.
TimescaleDB-specific changes:
- The abbreviation tsdb has been replaced by timescaledb.
- The option-patches directory includes with-compression and without-compression subdirectories; these contain optional files/patches for upgrading database tables depending on TimescaleDB compression settings.
- The hypertable schema creation file for TimescaleDB has been moved to database/postgresql/timescaledb/schema.sql.

Additionally, please note the following changes:

All history_pk_*.sql files have been renamed to history_upgrade_*.sql, and a trends_upgrade.sql file has been added to improve database upgrade scripts.
The double.sql file has been removed due to the removal of old numeric (float) value type.

Below is a comparison of the previous and current directory structure for MySQL and PostgreSQL databases.

# Previous:                                         # Current:
       
       database                                            database
       ├── mysql                                           ├── mysql
       │  ├── data.sql                                     │  ├── option-patches
       │  ├── double.sql                                   │  │  └── history_upgrade_prepare.sql
       │  ├── history_pk_prepare.sql                       │  ├── data.sql
       │  ├── images.sql                                   │  ├── images.sql
       │  └── schema.sql                                   │  └── schema.sql
       │                                                   │
       │                                                   │
       ├── postgresql                                      ├── postgresql
       │  ├── tsdb_history_pk_upgrade_no_compression       │  ├── option-patches
       │  │  ├── history_pk.sql                            │  │  └── history_upgrade_prepare.sql
       │  │  ├── history_pk_log.sql                        │  ├── timescaledb
       │  │  ├── history_pk_str.sql                        │  │  ├── option-patches
       │  │  ├── history_pk_text.sql                       │  │  │  ├── with-compression
       │  │  └── history_pk_uint.sql                       │  │  │  │  ├── history_upgrade.sql
       │  ├── tsdb_history_pk_upgrade_with_compression     │  │  │  │  ├── history_upgrade_log.sql
       │  │  ├── history_pk.sql                            │  │  │  │  ├── history_upgrade_str.sql
       │  │  ├── history_pk_log.sql                        │  │  │  │  ├── history_upgrade_text.sql
       │  │  ├── history_pk_str.sql                        │  │  │  │  ├── history_upgrade_uint.sql
       │  │  ├── history_pk_text.sql                       │  │  │  │  └── trends_upgrade.sql
       │  │  └── history_pk_uint.sql                       │  │  │  └── without-compression
       │  ├── data.sql                                     │  │  │     ├── history_upgrade.sql
       │  ├── double.sql                                   │  │  │     ├── history_upgrade_log.sql
       │  ├── history_pk_prepare.sql                       │  │  │     ├── history_upgrade_str.sql
       │  ├── images.sql                                   │  │  │     ├── history_upgrade_text.sql
       │  ├── schema.sql                                   │  │  │     ├── history_upgrade_uint.sql
       │  └── timescaledb.sql                              │  │  │     └── trends_upgrade.sql
       │                                                   │  │  └── schema.sql
       │                                                   │  ├── data.sql
       │                                                   │  ├── images.sql
       │                                                   │  └── schema.sql
       ├── ...                                             ├── ...

Please update your scripts, if any, containing references to the previous directory structure or files.

JSON protocol for passive agent checks

A JSON-based protocol for passive agent checks has been implemented.

For compatibility with older agents, a failover to the old plaintext protocol has been added. If the agent returns "ZBX_NOTSUPPORTED", Zabbix will cache the interface as old protocol and retry the check by sending only the plaintext item key.

Zabbix get can now be run with a new option -P --protocol <value> where "value" is either:

auto - connect using JSON protocol, fall back and retry with plaintext protocol (default);
json - connect using JSON protocol key;
plaintext - connect using plaintext protocol where just the item key is sent.

If an item key is not supported, Zabbix get will now return the exit code 1 instead of 0.

Documentation