1.22.x to 1.22.8 Upgrade Guide

Prev Next

This guide explains how to plan, perform and verify an upgrade from an existing N3uron installation to N3uron 1.22.8. It covers standalone systems, distributed architectures using N3uron Links and redundant deployments, including installations currently running N3uron 1.21 or an earlier 1.22 release. Follow the installation instructions for your operating system or deployment platform and the version-specific migration checks in this article.

Important: check the complete upgrade path

Upgrading directly from N3uron 1.21.x or an earlier 1.22.x release to N3uron 1.22.8 does not require installing intermediate releases. Before upgrading, verify that your operating system and architecture are supported by 1.22.8, confirm that Support and Maintenance (S&M) is active, review the 1.22 release notes and complete any applicable configuration, module and topology checks described below.

1. Plan Your Upgrade

Identify the source and target versions on every node, and record installed bootstrap and module versions. Some module versions can change independently of the platform version; therefore, compare the actual module inventory with the target release rather than checking only the main N3uron version.

Review item

What to check

Source and target versions

Record the installed N3uron and module versions. Read the N3uron 1.22 Release Notes for changes introduced since the currently installed release, including the target version.

System compatibility

Verify the supported operating system, architecture, and resource requirements for the target version.

Installed modules

Identify modules in use, configuration changes, deprecated features, certificates and dependencies.

Licensing

Confirm an active Support and Maintenance (S&M) entitlement for the target version, as described in the platform upgrade instructions.

Topology

Record standalone nodes, central and remote Links, redundant node pairs, databases and third-party clients.

Recovery

Define a maintenance window, tested backup/restore procedure and operational acceptance criteria.

Read the official N3uron 1.22 Release Notes before upgrading. Review all relevant 1.22 changes between your current version and 1.22.8, particularly module migrations, security changes and supported operating systems.

Direct upgrade from 1.21.x or an earlier 1.22.x version

A direct upgrade is supported without installing intermediate 1.22 releases. Before upgrading, perform the compatibility checks in this guide. In distributed systems, the Links compatibility rules depend on which node is central, and a redundant pair must have matching module and bootstrap versions.

Upgrading from N3uron 1.21.x or an earlier 1.22 release

N3uron 1.21.x and prior 1.22.x releases can be upgraded directly to 1.22.8 without passing through other software versions. Follow the platform-specific upgrade instructions after verifying the supported operating system, CPU architecture, target license coverage and relevant module migration requirements.

The user and role migration warning in the installation documentation applies only when upgrading from versions earlier than 1.21. It does not apply to upgrades from 1.21 to 1.22. However, since N3uron 1.22 introduces two-factor authentication (2FA) using time-based one-time passwords (TOTP), review the authentication settings and verify user access, roles, permissions, and 2FA functionality after upgrading.

2. Before You Upgrade

Back up the node and external data

  • Create and export a configuration backup using Node Backup and Restore. Save the backup outside the node being upgraded.

  • Back up assets that are excluded from a node backup, including external Scripting libraries, embedded MongoDB data, and certificates. Follow the database vendor or infrastructure procedure for external databases.

  • Preserve a record of node identity, licensing, module configuration, TLS certificate trust, data sources, alarm and historian configuration, and deployed HMI applications.

  • Confirm there is sufficient disk space and that the original installation package and all required recovery materials are available.

Node backup does not cover every asset

N3uron node backups include the configuration folder but exclude external Scripting libraries, the embedded MongoDB database, certificates and pending Store & Forward data. Use separate backups and data-preservation procedures for these items.

Validate the target environment

  • Check the supported operating systems, installation prerequisites and runtime dependencies of the target version. Do not use the compatibility list of your current version as evidence for the target version.

  • Review TLS certificate validity, trust, cryptographic algorithms, endpoints, firewall rules and integration dependencies that could change during the upgrade.

  • Test the upgrade with a representative copy of the configuration and connected services before scheduling production downtime.

  • Confirm any release-specific changes that require manual configuration or service reinstallation before the upgrade.

3. Compatibility and Breaking Changes in N3uron 1.22.8

Review the following requirements before running the upgrade. Changes to the runtime, TLS settings and individual modules may require configuration updates or compatibility testing.

Supported operating systems and runtime

N3uron 1.22.8 updates the Node.js runtime to version 26.13.1 and removes support for some operating systems that were supported by earlier versions. Before upgrading, validate the target node against the Windows and Linux installation requirements. This is especially important for older Windows Server, Debian, RHEL-family, Amazon Linux and Raspberry Pi OS installations.

Important: Operating-system and architecture compatibility

N3uron 1.22.8 no longer supports Windows Server 2012/2012 R2, Debian 10, RHEL 8 and its AlmaLinux/Rocky Linux/Oracle Linux equivalents, Amazon Linux 2 or Raspberry Pi OS Buster.

When upgrading from N3uron 1.21, also note that ARM32 is not supported by the 1.22 series. If the current environment does not meet the target requirements, upgrade the operating system or hardware before upgrading N3uron. Check the Windows and Linux installation guides for the complete supported-platform lists.

TLS certificate and endpoint requirements

N3uron 1.22.8 uses OpenSSL 3.5 security level 2. RSA, DSA and DH keys shorter than 2048 bits, ECC keys shorter than 224 bits, and RC4 cipher suites are rejected. Verify certificates used by N3uron and by connected devices, brokers, databases and other TLS peers.

For TLS connections, configure hosts using a canonical dotted-decimal IP address or a hostname. Non-canonical representations such as 127.1, 0x7f.0.0.1, 2130706433 or 192.168.001.010 are now rejected with ERR_TLS_CERT_ALTNAME_INVALID.

Scripting and npm compatibility

Review custom Scripting code and npm dependencies for compatibility with the Node.js 26 runtime introduced in N3uron 1.22.8. Removed APIs include util.is*, util._extend(), util.log(), process.assert(), SlowBuffer, fs.F_OK/R_OK/W_OK/X_OK (use fs.constants), dirent.path (use dirent.parentPath), and private _stream_* modules. Additionally, url.parse() and timers with negative delays now generate deprecation warnings.

Note:
Update affected code and test critical scripts in a staging environment before upgrading production nodes.

Linux service registration

Required action for manual Linux upgrades

When upgrading an existing Linux installation to N3uron 1.22.8 without using the official installation script, reinstall the N3uron systemd service to apply the updated out-of-memory (OOM) handling. This step is performed automatically when using the installation script. For manual instructions, refer to the Linux installation and upgrade article.

Major-Version Module Upgrades and Breaking Changes

Before upgrading, compare the installed version of each module with the version included in the target release. The following module major-version changes are introduced with N3uron 1.22.8. Review the relevant breaking changes when upgrading any of these modules from an earlier major version.

Data Diode 2.0.0 — Sender and Receiver Compatibility

Breaking change — introduced with N3uron 1.22.8

Data Diode 2.0.0 changes its internal encryption algorithm to ChaCha20-Poly1305 and is incompatible with earlier versions. Both the Sender and Receiver must be upgraded to version 2.0.0 to maintain communication. Coordinate both endpoints during the maintenance window and verify communication after the upgrade.

Scripting 2.0.0 — Removed Methods

Breaking change — introduced with N3uron 1.22.8

The log.export, log.cancel and log.subscribe methods were removed in Scripting 2.0.0. Scripts using these methods will fail until they are updated. Calls under the system namespace were also deprecated in favor of the node namespace. Review custom scripts and test affected methods before upgrading.

MCP Server 2.0.0 — Protocol and Permissions Migration

Breaking changes — introduced with N3uron 1.22.8

MCP Server 2.0.0 adopts the MCP 2026-07-28 stateless protocol revision and removes the previous Sessions settings. Resource subscriptions require compatible 2026-07-28 clients, and clients using that revision must send the MCP-Protocol-Version header. Category-based access levels are replaced by per-token selections of built-in tools, module methods, and user-defined tools, prompts and resources. Review and re-select access permissions, update clients as needed, and check calls that relied on removed built-in tools, including system_status, system_errorCount, system_restartService and system_generateNewUID. Validate tool discovery, authorization and resource subscriptions after upgrading.

SQL Client 2.0.0 — Configuration and Transaction Migration

Major-version migration — introduced with N3uron 1.22.8

SQL Client 2.0.0 changes connection management, query execution and History transaction handling. Previous timing options and per-database timeout settings have been removed. Connection pooling and Store & Forward for History transactions are introduced, alongside changes to retry settings, query and module methods. Before upgrading, review existing SQL Client channels, History transactions, connection parameters, SSL and Azure AD authentication, and custom scripts. After upgrading, verify database connectivity, query execution and historical data delivery, including buffered data where Store & Forward is used. Test critical workflows in a staging environment before upgrading production nodes.

For the full release history, see the N3uron 1.22 Release Notes.

Module Changes Requiring Attention

Module

Upgrade impact

MCP Server 2.0.0

Update clients for the MCP 2026-07-28 stateless protocol where applicable. Review per-token permissions, changed/removed built-in tools, the protocol-version header and new HTTP/argument/batch limits.

SQL Client 2.0.0

Review existing channel settings, connection pooling, removed timing and per-database timeout settings, retry attempts, queries, module methods, History transactions and custom scripts. Verify database connectivity, SSL and Azure AD authentication, and buffered data delivery after upgrading.

Data Exporter 1.11.0

For SFTP authentication using private keys, re-select the key file in existing configurations to store it encrypted. Validate exported ISO 8601 timestamps (including milliseconds and the UTC Z suffix), aggregation formatting, and CSV escaping if downstream applications parse these files. If the previous timestamp style is required, use the Custom format YYYY-MM-DDTHH:mm:ssZ.

BACnet Client 1.3.0

Check existing device/object identifiers and routed network, MAC and property identifier values against the new validation rules (object and Device ID range: 0–4194303). Verify read-only property mappings, including Priority_Array, and test COV subscriptions if used.

SNMP Client 1.3.3

DES is no longer accepted for SNMPv3 privacy; reconfigure devices still using this protocol.

MQTT Client 1.16.0

Review broker certificate verification, prohibited publish topic wildcards, packet-size handling, persistent sessions and related Store & Forward behavior.

Siemens Client 1.8.5

Remove leading zeros from zero-padded PLC IPv4 addresses.

ICCP Server 1.0.2

Remove Next_DSTransfer_Set as a member of configured or client-defined data sets.

REST API Server 1.10.0

Verify subscriptions under the user/token identity that created them and recheck permission-filtered event delivery.

Sparkplug Host App 1.0.3

Verify Tag quality and downstream alarms when processing Ignition quality codes or when the broker is unavailable. The module now maps disconnected brokers to BAD_COMM_FAILURE, disabled host apps to BAD_CONFIG_ERROR and uses the DDEATH timestamp when a device dies.

Web Vision 1.13.0

Review representative operator screens and Designer workflows after the interface update. Verify navigation, templates, charts and CSV export actions; check root-template and popup subscription settings if used. Validate representative projects before returning the HMI to production.

Encrypted certificate and private key settings

Review certificate and private-key settings for the modules listed below. For existing configurations that require file re-selection to encrypt stored key material, select the original file again after upgrading. Verify authentication and secure connectivity. Not every module listed requires re-selecting an existing certificate or key.

Module

File or setting to review

CAISO ADS Client 1.5.0

Client PFX certificate.

Data Exporter 1.11.0

SFTP private key.

MQTT Client 1.15.2

Client certificate and JWT private keys.

Sparkplug Client 1.3.3

Client certificate private key.

Sparkplug Host App 1.0.3

Client certificate private key.

OPC UA Server 1.18.0

Review the certificate Type (Autogenerated or Custom), custom certificate files and private-key configuration, where applicable. Verify secure OPC UA connections.

For distributed architectures, review N3uron Links. A central node running N3uron 1.22 can receive Links from remote nodes running 1.21. Remote 1.21 nodes do not need to be upgraded merely because the central node is upgraded. The reverse is not supported: a remote 1.22 node cannot connect to a central node still running 1.21. Therefore, upgrade the central node first when migrating the complete distributed architecture.

Before and after upgrading, record the Link status, configured endpoints, certificates, views, subscriptions, alarms and pending Store & Forward events. Use Links diagnostics to check the connection status and data exchange after reconnecting.

Do not generalize mixed-version support

During a phased rollout, verify the actual direction of every Link and confirm that the central node is not older than its remote 1.22 nodes. Monitor connection status and transmitted data after each node upgrade.

Redundant nodes

When upgrading a redundant N3uron deployment, review Redundancy and coordinate the maintenance of the Primary and Backup nodes. The platform documentation requires the two nodes to use the same bootstrap and module versions for proper redundancy. Do not operate a redundant pair with mismatched bootstrap or module versions.

  • Back up both nodes and verify which node is Primary and which is Backup.

  • Plan the update so that the pair reaches matching supported bootstrap and module versions; include the necessary downtime or controlled failover in the maintenance plan.

  • Check redundancy network connectivity and configuration synchronization after the update. For Historian in redundant nodes, confirm the external database requirements in the Redundancy article.

  • Where Links communicate with a redundant pair, review the Redundancy Agent integration and verify certificate trust for both nodes during failover.

5. Perform the Upgrade

Use the installation and upgrade article corresponding to the actual deployment. The platform-specific instructions provide the authoritative installer commands and procedures.

  1. Review the release-specific checklist. Identify breaking changes, modified modules, certificates and any required manual actions.

  2. Complete and verify backups. Include configuration and external data, as described above.

  3. Schedule and prepare the maintenance window. Inform users and downstream systems that could be affected by the interruption.

  4. Follow the platform-specific upgrade procedure. Use the operating-system or deployment-specific installation guide and the chosen target package or container image.

  5. Apply version-specific migration actions. Reconfigure affected modules, credentials, certificates, services or runtime dependencies as required by the target release.

  6. Validate the node and connected systems. Compare results against the pre-upgrade acceptance criteria before returning the system to normal operation.

6. Post-Upgrade Validation

Area

Verification

Platform

Confirm the installed N3uron and module versions, service startup, CPU and memory consumption, disk space and error logs.

Licensing and access

Verify the expected license state, user access, roles and authentication integrations.

Data acquisition

Verify data source connectivity, representative Tag values and quality, alarms and subscriptions.

Historian and storage

Confirm current and historical data storage, database access and pending Store & Forward data delivery.

Links

Review Links diagnostics, subscriptions, views, alarm exchange, certificate trust and buffered data delivery.

Redundancy

Confirm matching bootstrap and module versions, synchronization, role states and tested failover and recovery.

Applications and integrations

Validate Web Vision screens, scripts, REST/API consumers, MQTT/OPC connections and business-critical workflows in use.

Additional Checks for N3uron 1.22.8

  • Confirm the updated platform and module versions and the required Linux service action where applicable.

  • Validate operating-system compatibility, TLS key sizes, certificates and endpoint hostnames or IP addresses.

  • Test MCP clients, permissions and tool calls; SQL queries, transactions and database connections; and custom Scripting code.

  • Validate protocol clients and servers affected by changes to certificate handling, MQTT, SNMP, Siemens, ICCP and REST API subscriptions.

  • Confirm Links diagnostics, redundant pair operation and Store & Forward buffer drainage before considering recovery or rollback.

  • Where used, verify Data Exporter output formatting and SFTP uploads, BACnet Client configuration validation and COV subscriptions, Sparkplug Host App quality mapping, and Web Vision screens behavior.

7. Rollback and Recovery

Plan recovery before starting the upgrade. Keep a verified backup of the existing configuration and a copy of the previous N3uron installation. Do not assume that an earlier release can read data buffers, module configuration formats or database content produced by a newer release.

Store & Forward Downgrade Restrictions

Important: Prevent loss of pending data

Historian 1.25.1 and MQTT Client 1.16.0 introduce new on-disk Store & Forward buffer formats. Before downgrading either module to an earlier version, make sure its buffer is empty. Older versions discard pending events written in the new format.

For distributed installations, also verify pending data in N3uron Links and the state of the Links connections. For redundant installations, coordinate recovery across both nodes and ensure that bootstrap and module versions remain aligned.

For installations where N3uron is upgraded by replacing its binary folder, we recommend preserving the previous bin directory. This allows the previous executable version to be restored without downloading or reinstalling it.

Before Upgrading

  1. Create and verify a complete pre-upgrade configuration backup. Back up databases, certificates and other files not included in the node backup separately.

  2. Stop the N3uron service.

  3. Copy the existing bin directory and rename the copy to identify the current version, for example, bin_1.22.7.

  4. Proceed with the upgrade to N3uron 1.22.8, keeping the previous binary directory available for recovery.

If a Rollback Is Required

  1. Stop the N3uron service and collect diagnostic logs if the upgrade has caused unexpected behavior.

  2. Rename the current bin directory to bin_1.22.8.

  3. Rename the preserved bin_1.22.7 directory back to bin.

  4. Restore the pre-upgrade configuration backup if the newer version introduced incompatible configuration changes. Restore other backed-up data only when required and after checking compatibility.

  5. Start the N3uron service and verify module status, tag quality, historical data, alarms and external connections before returning the node to production.

Important:

Restoring the previous bin directory only restores the executable files. It does not automatically revert configuration changes, database content or Store & Forward buffers. Always verify backward compatibility before performing a rollback. For Docker and Kubernetes deployments, follow the platform-specific recovery procedures instead of replacing the bin directory.