Table of Contents

10 Upgrade notes for 7.0.0

10 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:

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 7.0.0 from versions before Zabbix 6.4.0. See the upgrade procedure section for all relevant information about upgrading from previous Zabbix versions.

Upgrade process

To complete 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;

Critical

To complete successful Zabbix server upgrade on MySQL and 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, log_bin_trust_function_creators can be disabled:

mysql> SET GLOBAL log_bin_trust_function_creators = 0;

Server crash with PostgreSQL/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 PostgreSQL/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. Follow the instructions in TimescaleDB setup page configuration section "For existing installations".

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

Using pg_restore to restore a PostgreSQL/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.

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

Prior to 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 Old numeric (float) value type dropped.

Auditlog converted to hypertable on TimescaleDB

The auditlog table has been converted to hypertable on TimescaleDB in new installations.

To successfully upgrade existing installations, you must rerun the `timescaledb.sql`` script, located in database/postgresql, before starting Zabbix server. Zabbix server will log a warning, if started without running this script first.

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.

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.

Concurrency in network discovery

Previously each network discovery rule would be processed by one discoverer process. Thus all service checks within the rule were performed sequentially.

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. Only those checks that have the same IP and port are scheduled sequentially because some devices may not allow concurrent connections on the same port. A new zabbix[discovery_queue] internal item allows to monitor the number of discovery checks in the queue.

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.

API changes

See the list of API changes in Zabbix 7.0.0.

Minimum required PHP version

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

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). For more information, see Item history.

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.

Informational

Asynchronous pollers

After the upgrade all agent and HTTP agent 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.

Oracle DB deprecated

The support for Oracle as a backend database has been deprecated in 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 date/time display when the default (en_US) frontend theme is used.

Before	Now

Icons replaced by fonts

All icons in the frontend have been replaced by 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

Default value of the BufferSize configuration parameter for Zabbix agent 2 has been increased from 100 to 1000. This change does not affect installations where BufferSize is explicitly set.

Aggregate calculations

Several aggregate functions have been updated. Now:

Aggregate functions count and count_foreach 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.0, numeric (float) data type supports precision of approximately 15 digits and range from approximately -1.79E+308 to 1.79E+308. This is implemented by default in new installations. Whereas for upgrading existing installations that had been created before Zabbix 5.0 a database upgrade patch is applied automatically.

The patch will alter data columns of history and trends tables, which usually contain lots of data, therefore it is expected to take some time to complete. Since the exact estimate depends on server performance, database management system configuration and version, and it cannot be predicted, it is recommended to first test the patch outside the production environment, even though with MySQL 8.0 and MariaDB 10.5 configured by default the patch is known to be executed instantly for large tables due to efficient algorithm and the fact that previously the same double type was used but with limited precision, meaning that data itself does not need to be modified.

If you use Oracle database or older version of MySQL database, as well as in case of large installations, the patch execution can take a lot of time, and therefore it is recommended to update the data type manually before starting the upgrade.

Please execute the appropriate patch (SQL file) for your database; you may find these scripts in the Zabbix Git repository for:

Important! Run these scripts for the server database only.

To apply a patch:

Stop Zabbix server.
Run the script for your database.
Start Zabbix server again.

Note that with TimescaleDB the compression support must only be turned on after applying this patch.

Option for 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).

Templates

This section lists the changes to the stock templates that are shipped with Zabbix.

Upgrading to the latest Zabbix version will not automatically upgrade the templates used. It is suggested to modify the templates in existing installations by downloading the latest templates from the Zabbix Git repository and importing them manually into Zabbix. If templates with the same names already exist, the Delete missing options should be checked when importing to achieve a clean import. This way the old items that are no longer in the updated template will be removed (note that it will mean losing history of these old items).

Zabbix server health, Remote Zabbix server health, Zabbix proxy health, and Remote Zabbix proxy health templates have been updated according to the changes in network discovery. The item/trigger for monitoring the discoverer process (now removed) have been replaced by items/triggers to measure the process utilization of discovery manager and discovery worker respectively. A new internal item has been added for monitoring the discovery queue.
MongoDB node by Zabbix agent 2 template item type of mongodb.version has been changed from Dependent item to Zabbix agent.
Oracle by Zabbix agent 2 template item type of oracle.version has been changed from Dependent item to Zabbix agent.
All templates containing dashboard widgets have been updated according to the Communication framework for widgets feature. Template dashboard widget elements have been updated to reflect widget field changes in template dashboards.
Azure by HTTP template has been updated according to the changes to the Plain text widget. The template dashboard widget name and fields elements have been updated to reflect the replacement of the Plain text widget with the Item history widget.

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.

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

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

Please update your scripts, if any, containing the previous directory structure.

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.

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.

Updated items

The wmi.get and wmi.getall used with Zabbix agent 2 now return 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.

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

Documentation