NiFi Upgrade Standalone Toolkit — Usage Guide

This guide walks customers through using the Acceldata NiFi Upgrade Toolkit to move from ODP NiFi 1.28.1 → ODP NiFi 2.7.2 and the matching upgrade for NiFi Registry 1.x → 2.7.2.

The toolkit covers three stages:

  1. Pre-upgrade check — assesses your current install and flow for blockers.

  2. Pre-upgrade backup + install — captures a backup, then installs the 2.7.2 binaries with automatic rollback on failure.

  3. Post-upgrade check — validates the upgraded service over its REST API.

Scope

The toolkit handles assessment, backup, install, and post-cutover validation. It does not rewrite flow.json.gz (processor replacement, bundle edits) — that work is done in the NiFi UI, in NiFi Registry, or via your own migration tooling.

Clustered NiFi: run the installer node-by-node (stop all nodes → install on each in turn → start nodes one at a time). The installer warns if it detects clustering but does not orchestrate across nodes.

Prerequisites (both sections)

  • Python 3.6+ on the NiFi / Registry host

  • Java 21 available on the host (required by NiFi 2 / Registry 2)

  • Shell access (root/sudo for install stage)

  • The toolkit tarball extracted on the host:

wget https://mirror.odp.acceldata.dev/ODP/standalone/3.3.6.4-1/nifi-upgrade-toolkit.tar.gz tar -xzf nifi-upgrade-toolkit.tar.gz cd nifi-upgrade-toolkit ./install_deps.sh # one-time per host: installs ijson for streaming flow.json

Section 1 - NiFi

1.1 Stage 1: Pre-upgrade check

Assesses your NiFi 1.28.1 install and flow for anything that will break under NiFi 2.

Run:

# Auto-discover NiFi home from the running process or common install paths ./pre_upgrade_check.sh # Or pass it explicitly, with Java 21 for the version check ./pre_upgrade_check.sh \ --nifi-home /usr/odp/current/nifi \ --java-home /usr/lib/jvm/java-21

NIFI_HOME and JAVA_HOME environment variables are accepted in place of the flags.

What it Checks

No.

Check

Flags

1

Java version

Java 21 must be available for NiFi 2

2

Removed / deprecated components

Kafka 1/2/2.6, HBase, Hive, Solr, GetTCP, etc.

3

Removed scripting languages

Ruby, Python (Jython), ECMAScript, Lua

4

Process group variables

Must migrate to Parameter Contexts

5

EVENT_DRIVEN scheduling

Removed in NiFi 2

6

Templates

Removed in NiFi 2

7

Legacy Kerberos

Principal/keytab/password patterns to move to Kerberos User Services

8

Bundle coordinate changes

NAR moves/renames (Jolt, FileParameterProvider, …)

9

Sensitive properties

Missing nifi.sensitive.props.key; PBE algorithms dropped in NiFi 2

10

Controller service wiring

Dangling refs, disabled dependencies, circular graphs

11

Expression Language

EL functions removed in NiFi 2 (none on the 1.28.1 → 2.7.2 path)

12

Third-party NARs

Non-org.apache.nifi bundles

13

Groovy compatibility

Groovy scripted components (manual validation)

14

Cluster configuration

ZK connect string, TLS/S2S vs NiFi 2 behavior

15

Parameter Context conflicts

Duplicates / empty contexts

16

Authorization

FileAuthorizer (removed in 2.7.1+); Ranger major version

17

Connector architecture

Processors that need new controller services in NiFi 2

Output

Two files are produced in the working directory:

File

Contents

nifi-pre-upgrade-report-<timestamp>.json

Machine-readable report

nifi-pre-upgrade-report-<timestamp>.txt

Human-readable log of the run

Prefix

Meaning

OK

No issues found

WARN

Advisory — review, not a hard blocker

ERROR

Must be resolved before upgrading

Exit codes: 0 = clean (OK / WARN), 2 = one or more ERROR items, 1 = script error.

Resolve every ERROR in the report before continuing.

1.2 Stage 2a: Pre-upgrade backup

Captures conf/, the flow, and the content/provenance repository paths referenced in nifi.properties into a timestamped tarball under /var/tmp/nifi-upgrade-backups/.

The installer in Stage 2b refuses to run without a backup archive from this step.

# Dry run — lists paths that would be archived ./upgrade_pre_activity_nifi.sh --nifi-home /usr/odp/current/nifi # Create the backup ./upgrade_pre_activity_nifi.sh --nifi-home /usr/odp/current/nifi --execute

1.3 Stage 2b: Install NiFi 2.7.2

Fetches the NiFi 2.7.2 tarball from the Acceldata repo, verifies its sha256, stops the running 1.x service, extracts the new version, merges configuration from the Stage 2a backup, flips the /usr/odp/current/nifi symlink, and starts the service. On any failure after service stop, the script automatically rolls back — symlinks revert, conf/ is restored from the backup, and the 1.x service is started again.

Supported Operating Systems: RHEL 8, RHEL 9, Debian, Ubuntu (auto-detected).

# Standard ODP layout (installs NiFi + Registry together) ./upgrade_nifi.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry # NiFi only ./upgrade_nifi.sh --nifi-home /usr/odp/current/nifi --skip-registry # Preview without making changes ./upgrade_nifi.sh --nifi-home /usr/odp/current/nifi --dry-run

Common overrides

Flag

Default

Purpose

--install-root

/usr/odp

Base directory under which the new version is extracted

--current-symlink-nifi

/usr/odp/current/nifi

Symlink that is flipped to the new version

--java21-home

/usr/lib/jvm/java-21

Java 21 location for NiFi 2

--backup-root

/var/tmp/nifi-upgrade-backups

Where Stage 2a archives are read from

--tarball-url

Acceldata repo URL

Override for air-gapped installs

Checksum: every tarball is fetched with its .sha256 and verified via sha256sum -c before anything is extracted. A mismatch aborts before any state is mutated.

1.4 Stage 3: Post-upgrade check (NiFi)

Calls the NiFi 2 REST API and validates the upgrade landed cleanly.

# Local, self-signed TLS ./post_upgrade_check.sh --base-url https://127.0.0.1:8443/nifi-api --insecure # Remote with basic auth ./post_upgrade_check.sh \ --base-url https://nifi.example:8443/nifi-api \ --user nifi --password "$NIFI_PASSWORD"


Check

What it Verifies

1

NiFi version

Reports 2.x

2

Invalid processors

invalidCount == 0 across all process groups

3

Controller services

None in validationStatus=INVALID

4

Cluster node health

All nodes CONNECTED (skipped for standalone)

5

System diagnostics

NiFi reachable; versionInfo present

6

Bulletin board

No ERROR-level bulletins

Exit 2 if the version is not 2.x, any processor or controller service is INVALID, any cluster node is not CONNECTED, or ERROR-level bulletins are present.

Section 2 - NiFi Registry

The Registry upgrade follows the same three-stage flow. If you run NiFi and Registry on the same host, you can combine the pre-check and post-check invocations as shown at the bottom of this section.

2.1 Stage 1: Pre-upgrade Check

Validates Registry 1.x configuration before moving to Registry 2.x: Java 21, nifi-registry.properties, bootstrap.conf, authorizers, identity providers.

./registry_pre_upgrade_check.sh \ --nifi-registry-home /usr/odp/current/nifi-registry ./registry_pre_upgrade_check.sh \ --nifi-registry-home /opt/nifi-registry \ --java-home /usr/lib/jvm/java-21 \ --output /tmp/reg-report.json

NIFI_REGISTRY_HOME can be set instead of --nifi-registry-home. Exit codes match the NiFi pre-check: 0 for clean, 2 if any ERROR is reported.

2.2 Stage 2a: Pre-upgrade Backup

The Stage 2a script for NiFi also captures Registry state when --nifi-registry-home is supplied to the installer; for a Registry-only or standalone Registry host, back up the conf/ directory and any database/flow-storage directory referenced by nifi-registry.properties before running Stage 2b.

Registry is installed by the same upgrade_nifi.sh script when --nifi-registry-home is passed. The same checksum verification and automatic rollback apply.

# NiFi + Registry together sudo ./upgrade_nifi.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry # Override the Registry tarball source (air-gapped, etc.) sudo ./upgrade_nifi.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry \ --registry-tarball-url https://repo.acceldata.io/odp/nifi/2.7.2/nifi-registry-2.7.2-odp-bin.tar.gz

Registry symlink default: --current-symlink-registry /usr/odp/current/nifi-registry.

Validates the Registry REST API after cutover.

./registry_post_upgrade_check.sh \ --base-url https://host:18443/nifi-registry-api

Check

What it Verifies

/about

Reports 2.x

/buckets

Reachable

/access/config

Responds

2.5 Running NiFi + Registry Together

Both checks can be combined in a single invocation:

# Pre-upgrade — NiFi + Registry in one run ./pre_upgrade_check.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry # Post-upgrade — NiFi + Registry in one run ./post_upgrade_check.sh \ --base-url https://nifi.example:8443/nifi-api \ --registry-base-url https://nifi.example:18443/nifi-registry-api \ --user admin --password "$PW"

Aggregate exit codes follow the strictest result across the two checks.

Recommended workflow

  1. Run the pre-upgrade check for NiFi (and Registry, if applicable). Resolve every ERROR in the report.

  2. Run the pre-upgrade backup with --execute.

  3. Run the installer (upgrade_nifi.sh) on each host. For clusters, do this node-by-node.

  4. Run the post-upgrade check against the upgraded service URLs.

  5. Verify your flows in the NiFi UI and your buckets in the Registry UI.

Support

This toolkit is shipped by Acceldata. For production upgrade runbooks and assistance, contact your Acceldata or ODP distribution support channel.

  Last updated on May 15, 2026
Next to read:
3-Node NiFi 2.7.2 Standalone Cluster Setup Guide
null
On This Page
NiFi Upgrade Standalone Toolkit — Usage GuidePrerequisites (both sections)Section 1 - NiFiSection 2 - NiFi RegistryRecommended workflowSupport1.1 Stage 1: Pre-upgrade check1.2 Stage 2a: Pre-upgrade backup1.3 Stage 2b: Install NiFi 2.7.21.4 Stage 3: Post-upgrade check (NiFi)2.1 Stage 1: Pre-upgrade Check2.2 Stage 2a: Pre-upgrade Backup2.3 Stage 2b: Install NiFi Registry 2.7.22.5 Running NiFi + Registry Together