> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/installation/rpm/rpm-upgrade/major-upgrade.md).

# Major upgrade

Crossing from the 4.2.1 line onto the 2026 line — a supported upgrade with a database migration script, run against a single node or a three-node cluster.

## What this is, and when you need it

A move from any **4.2.1.x** release onto the **2026** line. It applies to both **single-node** and **three-node** RPM deployments; where the two differ, the cluster form is called out.

The worked target below is **2026.8.2**. Support confirms the correct target for your starting version — it is not always the newest release.

This is a supported upgrade rather than a self-service one — the database migration script is issued to you, so the support case is part of the procedure and not a formality.

{% hint style="warning" %}
**Open a support case before you begin.** OpenIAM supplies the Groovy database initialisation script for your database type in the upgrade ticket, and confirms the path from your specific starting version.
{% endhint %}

## What changes, coming from 4.2.1.x

Fifteen releases sit between 4.2.1.x and 2026.8.2. Four of those changes alter how the deployment is operated, and are worth reading before you plan the window.

### Your deployment goes from two databases to eight

4.2.1.x ran on `openiam` and `activiti`. Across this span the platform broke six subsystems out into their own services, each owning its own database:

<table><thead><tr><th width="127.99993896484375">Arrived in</th><th width="148.199951171875">Database</th><th>What it holds</th></tr></thead><tbody><tr><td>4.2.2</td><td><code>groovy</code></td><td>Groovy scripts, which stop being files on disk and become rows</td></tr><tr><td>2026.3.1</td><td><code>auditlog</code></td><td>The audit log</td></tr><tr><td>2026.5.2</td><td><code>batchtasks</code></td><td>Batch task configuration and scheduling</td></tr><tr><td>2026.6.1</td><td><code>certification</code></td><td>Certifications, campaigns and review items</td></tr><tr><td>2026.7.1</td><td><code>pbac</code></td><td>Policy-based access control policies and decisions</td></tr><tr><td>2026.8.1</td><td><code>privacy</code></td><td>Consent ledger, purpose registry and privacy events</td></tr></tbody></table>

**Each has to exist before you upgrade, and each service has to be deployed after.** This upgrade crosses all six — take every set of steps in [*Release-specific steps*](/installation/rpm/rpm-upgrade/release-specific-steps.md).

{% hint style="danger" %}
**This changes what a backup has to cover.** A backup of `openiam` and `activiti` was a complete rollback position on 4.2.1.x. On 2026.8.2 it captures two databases out of eight — it will still complete, still report success, and leave the other six on the post-upgrade schema in a state no version expects.
{% endhint %}

### Custom Groovy scripts that extend certification or batch tasks must be updated

Base classes moved package as each subsystem was extracted — twice, in the case of the certification helper. The shipped scripts under `conf/iamscripts/` were updated for you. Anything you have customised was not: find those imports before you upgrade, not after a campaign fails to initialise.

The full table of moves is in [*Release-specific steps*](/installation/rpm/rpm-upgrade/release-specific-steps.md#custom-groovy-scripts-must-be-re-pointed).

### Two infrastructure components were replaced

Moving onto the 2026 line replaces two components: **Elasticsearch with OpenSearch**, and **ETCD with Consul**. Both are handled by the upgrade, but they change what you are monitoring and what appears in the port list.

### Custom Groovy scripts that reach outside their sandbox will stop working

2026.8.2 runs Groovy scripts inside a sandboxed engine instead of an unrestricted shell. A script that touches system properties, arbitrary classes, the filesystem or the network directly will fail once this upgrade completes. Review your customised scripts for these before you upgrade — a script that only reads its own parameters and calls approved APIs is unaffected.

### What you gain

<table><thead><tr><th width="165.60003662109375">Area</th><th>What arrives between 4.2.1.x and 2026.8.2</th></tr></thead><tbody><tr><td><strong>Segregation of duties</strong></td><td>The whole subsystem — policy management, enforcement during access requests, continuous violation monitoring, mitigating controls and a violations report. Then a <strong>Rule Set Catalog</strong> of pre-built libraries for Manufacturing, HR and Payroll, Financial Services, Plant Maintenance and SAP Basis in US and EU variants, with drift detection, re-sync, rule set comparison, and scheduled detection runs that email a digest</td></tr><tr><td><strong>Access certification</strong></td><td>Rewritten, then rebuilt again. Event-driven campaigns, <strong>campaign preview</strong> — the full scope and reviewer calculation against real data, with every exclusion and its reason, promoted to launch from the snapshot — <strong>extended user search</strong> for building campaign populations without SQL, launch history, bulk approval, side-by-side entitlement comparison against a peer or a previous campaign, entitlement descriptions in the reviewer's view, and a pending-review-only filter. Campaign History, preview and report downloads were substantially reworked for large campaigns in 2026.8.2</td></tr><tr><td><strong>Identity risk</strong></td><td>New. Risk-driven campaign scope with a minimum-risk threshold, live risk that updates mid-campaign with drift indicators and a factor breakdown, a <strong>User Risk</strong> page showing the grant path for every access row, and a Risk Score Configuration screen</td></tr><tr><td><strong>Privacy management</strong></td><td>New in 2026.8.1: an event-sourced <strong>consent ledger</strong> with a live current-state projection, a registry of processing purposes, activities and lawful authorities with governed versioning, a durable privacy event backbone with reconciliation, evidence records for every state change, and a Privacy Administration Console. 2026.8.2 adds <strong>notice authoring</strong> — versioned per language, with a draft-to-publish approval chain — and a self-service <strong>Privacy Center</strong> where users manage their own consent and preferences</td></tr><tr><td><strong>Access control</strong></td><td>A <strong>PBAC console</strong> with shadow, percentage and full rollout modes, a simulation runner that shows what a policy would decide without changing anything, and a decision log recording which policies applied. Delegated access requests can be disabled per application</td></tr><tr><td><strong>Authentication</strong></td><td>Compromised-password detection against Have I Been Pwned, passwordless sign-in with FIDO2 and the OpenIAM Auth App, and risk-based authentication with device intelligence</td></tr><tr><td><strong>Administration scope</strong></td><td>Virtual tenants — organization administrators can be scoped so they see only their own organizations, in both the Webconsole and SelfService</td></tr><tr><td><strong>Operations</strong></td><td>Prometheus monitoring, a descriptive analytics dashboard, a redesigned Groovy Manager with bulk import and export, RequestId enrichment across logs, a redesigned SelfService portal, and CJIS and STIG deployment profiles on RHEL</td></tr><tr><td><strong>Connectors</strong></td><td>Multi-instance Windows installer for .NET v6, PowerShell connectors shareable between production and non-production, and connector-level query-injection protection</td></tr><tr><td><strong>Security</strong></td><td>2026.8.2 closes a reflected XSS path on password reset, sandboxes Groovy script execution, parameterizes Oracle and PostgreSQL DDL against injection, and restores proper TLS verification in the Tableau, SAP UME, Thales and Salesforce connectors — see the Groovy sandbox note above before you upgrade</td></tr></tbody></table>

## Before you begin

Take the backups and checks in [*Upgrading OpenIAM*](/installation/rpm/rpm-upgrade.md#before-any-upgrade) first, then work through the following.

### Back up everything, not just the application

* A full snapshot of **every** Linux host in the deployment — all three, for a cluster.
* A full backup of the OpenIAM and Activiti databases from the external database instance, **and every other database your release uses**.

### Platform

The upgrade is supported on **Enterprise Linux 8, 9 and 10**. Only the dependency archive differs between them; the RPM and both binaries are the same file on every platform.

### Disk space

Roughly **50 GB free**, verified against current utilisation of the `/root` partition rather than the disk as a whole.

### Access

* Admin-privileged credentials for every Linux host taking part.
* Admin-privileged credentials for the external database instance.

### Network and firewall

The following must be open between cluster nodes and services:

| Host                  | Port                                                                           | What uses it                                                   |
| --------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| OpenIAM cluster nodes | 8500/TCP, 8503/TCP, 8301/TCP, 8301/UDP, 8302/UDP, 8300/TCP, 8600/TCP, 8600/UDP | Between Consul agents — server and client — and other services |
|                       | 8081                                                                           | IdP                                                            |
|                       | 8082                                                                           | `WEBCONSOLE_PORT`                                              |
|                       | 8083                                                                           | `SELFSERVICE_PORT`                                             |
|                       | 8084                                                                           | `SELFSERVICE_EXT_PORT`                                         |
|                       | 8085                                                                           | `REPORTVIEWER_PORT`                                            |
|                       | 8086                                                                           | `UI_STATIC_PORT`                                               |
|                       | 8087                                                                           | HAProxy                                                        |

The complete list for a three-node cluster is in [Ports](/installation/rpm/rpm-ha/ports.md).

### Audit log

{% hint style="info" %}
**If your audit log is larger than 3 GB, export it before upgrading.** The upgrade script carries procedures for both online and offline export. Skipping this on a large log lengthens the maintenance window considerably.
{% endhint %}

## Upgrade with internet access

{% stepper %}
{% step %}

### Fetch the upgrade script

For a single node:

{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/infra/upgrade.sh --output /usr/src/upgrade.sh
```

{% endcode %}

For a three-node cluster:

{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/infra/ha_upgrade.sh --output ha_upgrade.sh
```

{% endcode %}
{% endstep %}

{% step %}

### Run the upgrade

{% code overflow="wrap" %}

```bash
openiam-cli upgrade
```

{% endcode %}
{% endstep %}
{% endstepper %}

## Upgrade without internet access

Stage the script and every artifact under `/usr/src/` first.

{% stepper %}
{% step %}

### Prepare the upgrade script

Single node:

{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/infra/upgrade.sh --output /usr/src/upgrade.sh
chmod +x /usr/src/upgrade.sh
cp /usr/src/upgrade.sh /usr/local/openiam/utils/
```

{% endcode %}

Three-node cluster — copy `ha_upgrade.sh` into the `openiam-cluster-rpm` folder, fill in its **CONFIGURATION** section, then run it:

{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/infra/ha_upgrade.sh --output ha_upgrade.sh
chmod +x ha_upgrade.sh
```

{% endcode %}
{% endstep %}

{% step %}

### Download the shared artifact

{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/infra/elasticdump-offlines.tar.gz --output /usr/src/elasticdump-offlines.tar.gz
```

{% endcode %}
{% endstep %}

{% step %}

### Download the release artifacts for your platform

{% tabs %}
{% tab title="Enterprise Linux 9" %}
{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/2026.8.2/rpm/openiam-2026.8.2.noarch.x86_64.rpm --output /usr/src/openiam-2026.8.2.noarch.x86_64.rpm
curl https://download.openiam.com/release/enterprise/2026.8.2/dependencies/el9/openiamrepo.tar.gz --output /usr/src/openiamrepo.tar.gz
curl https://download.openiam.com/release/enterprise/2026.8.2/binaries/frontend.tar.gz --output /usr/src/frontend.tar.gz
curl https://download.openiam.com/release/enterprise/2026.8.2/binaries/backend.tar.gz --output /usr/src/backend.tar.gz
```

{% endcode %}
{% endtab %}

{% tab title="Enterprise Linux 10" %}
{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/2026.8.2/rpm/openiam-2026.8.2.noarch.x86_64.rpm --output /usr/src/openiam-2026.8.2.noarch.x86_64.rpm
curl https://download.openiam.com/release/enterprise/2026.8.2/dependencies/el10/openiamrepo.tar.gz --output /usr/src/openiamrepo.tar.gz
curl https://download.openiam.com/release/enterprise/2026.8.2/binaries/frontend.tar.gz --output /usr/src/frontend.tar.gz
curl https://download.openiam.com/release/enterprise/2026.8.2/binaries/backend.tar.gz --output /usr/src/backend.tar.gz
```

{% endcode %}
{% endtab %}

{% tab title="Enterprise Linux 8" %}
{% code overflow="wrap" %}

```bash
curl https://download.openiam.com/release/enterprise/2026.8.2/rpm/openiam-2026.8.2.noarch.x86_64.rpm --output /usr/src/openiam-2026.8.2.noarch.x86_64.rpm
curl https://download.openiam.com/release/enterprise/2026.8.2/dependencies/el8/openiamrepo.tar.gz --output /usr/src/openiamrepo.tar.gz
curl https://download.openiam.com/release/enterprise/2026.8.2/binaries/frontend.tar.gz --output /usr/src/frontend.tar.gz
curl https://download.openiam.com/release/enterprise/2026.8.2/binaries/backend.tar.gz --output /usr/src/backend.tar.gz
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Run the upgrade

{% code overflow="wrap" %}

```bash
openiam-cli upgrade
```

{% endcode %}
{% endstep %}
{% endstepper %}

## Related

* [Release-specific steps](/installation/rpm/rpm-upgrade/release-specific-steps.md) — the databases and services this upgrade crosses
* [After a major upgrade](/installation/rpm/rpm-upgrade/after-a-major-upgrade.md) — what to put right once it completes
* [Minor upgrade](/installation/rpm/rpm-upgrade/minor-upgrade.md) — staying on the line you are already on
* [Major upgrade — Kubernetes](/installation/kubernetes/kubernetes-upgrade/major-upgrade.md) — the same move, on a cluster
* [RPM — three nodes](/installation/rpm/rpm-ha.md) — the clustered shape this upgrade also covers

*Worked against OpenIAM 2026.8.2. Last reviewed 9 September 2026.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/installation/rpm/rpm-upgrade/major-upgrade.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.