> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/maintain/upgrade-20232/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Upgrade Platform 2023.2 > How to upgrade Itential Platform using the BIN installer for on-premises deployments in legacy release versions (2022.1, 2023.1, 2023.2), including rollback procedures. This guide assists users in upgrading Itential Platform using the **BIN install** method for **on-premises** software in legacy release versions. If you encounter any blocking issues while upgrading, see the [Rollback procedure](#rollback-procedure) below. To upgrade from Itential 2023.x or 2022.x to Platform 6.x, see [Upgrade to Platform 6.x](/guide/upgrade/upgrade-platform). ## Prerequisites Before taking any action: * Review this document in full and establish a complete upgrade plan. * Review all [release notes](/itential-platform/release-notes/overview) related to the Platform version you are targeting. This ensures you are informed of any new features, deprecations, and breaking changes. Pay particular attention to breaking change notices to avoid service disruption. * Ensure that `bash` and `tar` are installed on the system. If you need help establishing an upgrade plan, contact your Itential Account Manager. ## Upgrade support * Itential provides support for previous releases of the Platform according to its [Version Lifecycle](/itential-platform/version-lifecycle). * If your current version is out of support, you may need to contact your Itential Account Manager for additional upgrade instructions. * Itential strongly advises that you **do not skip major versions** when upgrading. ## Upgrade procedure ### Before starting * Obtain an installer for the target version of the Platform. * Review the official documentation for the `mongodump` and `mongorestore` utilities on the [MongoDB Database Tools](https://www.mongodb.com/docs/database-tools/) site. * The Itential installer creates a systemd service for the Platform named `pronghorn`. Ensure you are familiar with `systemctl` and `journalctl` for managing and monitoring system services. * Review all [release notes](/itential-platform/release-notes/overview) related to your target version and audit your system for any potential impact. * Ensure that `bash` and `tar` are installed on the system. ### Warnings and precautions * During any major version upgrade, all jobs must be in a **completed** or **canceled** state. In-flight jobs are not supported across major version upgrades. * Upgrading the Platform writes to your current database to migrate data. Back up your database before upgrading to allow rollback in the event of a failure. * Upgrading the Platform requires a period of downtime. ### Upgrade steps #### Ensure all jobs are complete or canceled All jobs must be in a **completed** or **canceled** state before the upgrade can be performed. #### Prevent new jobs from starting With the current version of the Platform running, prevent Itential Platform from starting new jobs: * **2023.1 and above:** From the Admin Essentials UI homepage, go to **Admin Essentials > Server Information > Accept New Jobs**. * **2022.1:** Individually disable job sources: 1. Automation Catalog Automations 2. Operations Manager Automation Triggers 3. Any non-Itential product using the `startJobWithOptions` API from Workflow Engine. #### Confirm all jobs are complete or canceled Verify all jobs are in the appropriate state. #### Shut down Itential Platform Once all jobs are in the appropriate state, shut down Itential Platform. #### Back up the database Create a database backup using the `mongodump` utility. Refer to the `properties.json` file to identify the correct logical database name. If using `adapter-local_aaa` for any purpose, create a backup of its database as well. `mongodump` includes all logical databases by default if you do not specify `--db`. #### Verify dependency versions Ensure all dependencies align with the [version requirements](/itential-platform/install/platform) of the target version of Itential Platform. In the **2023.2** release, the Platform uses **Redis** for message brokering previously handled by RabbitMQ. This requires new Redis configuration settings. See the [Install Platform](/itential-platform/install/platform) section for details. #### Run the upgrade installer Set permissive mode and use the installer to upgrade to the new version of Itential Platform. ```bash sudo setenforce permissive sudo bash ./itential-_.linux.x86_64.bin --upgrade ``` Change `` and `` in the installer binary above to match the version being installed. The installer will: 1. Leave the existing version of Itential Platform in place. 2. Install the new version alongside the existing version. 3. Link `/opt/pronghorn/current` to the newly installed version. ### Start the new Platform version By default, the `pronghorn` systemd service uses `/opt/pronghorn/current` to determine which version to start. ```bash sudo systemctl start itential-platform ``` If you used AGManager in your previous Platform version, run the `discoverAll` method after starting the upgraded Platform version. This restores AGManager tasks from your Gateway adapters. See [Automatic discovery in Gateway](/itential-gateway/automatic-discovery#discoverall) for more information. ### Verify the upgrade After starting the new version, audit the following: * **Roles, accounts, groups, and permissions:** If new applications or adapters were added as part of the upgrade, you may need to assign additional roles to users or groups. Verify that admin users and groups contain all newly added roles, such as "SSO" and "SSOGroupMappings" permissions required to access and configure Identity Providers. * **Database indexes:** These are visible in the Admin Essentials application under the Active Profile. The Platform also automatically detects missing indexes and displays them under **Alerts** on the Admin Essentials dashboard. * **Workflows:** Audit your workflows for deprecated tasks and altered input schemas. Your organization may require additional verification steps, such as checking adapter configuration and health. After verifying the correctness of the new install, enable new jobs on the system from the Admin Essentials UI. ## Rollback procedure ### Warnings and precautions The database must be restored to a previous state to ensure feature compatibility. Any data changes made after your latest backup from the rollback-target version will be lost. ### Rollback steps #### Prevent new jobs from starting If the new version is live, prevent it from starting new jobs: * **2023.1 and above:** From Admin Essentials, go to **Server Information > Accept New Jobs**. * **2022.1:** Individually disable job sources: 1. Automation Catalog Automations 2. Operations Manager Automation Triggers 3. Any non-Itential product using the `startJobWithOptions` API from Workflow Engine. #### Burn down in-flight jobs if needed If the new version has been live for any length of time, burn down in-flight jobs if needed. Note that regardless of job burn-down, you will not have access to post-upgrade jobs after completing the rollback. #### Shut down the Platform Once all jobs are in the appropriate state, shut down the Platform. #### Back up the post-upgrade database Create a database backup using the `mongodump` utility. This preserves post-upgrade data changes for reference purposes only — this backup cannot be used in the Platform version targeted by the rollback. #### Verify rollback-target dependency versions Ensure all dependency versions satisfy the [requirements](/itential-platform/install/platform) of the Platform version targeted by the rollback. #### Restore the pre-upgrade database Restore the previous database state from the archive created before upgrading, using the `mongorestore` utility. Use the `--drop` flag to ensure all collections are cleared before importing the archived contents. This deletes any data changes made after the upgrade was completed. #### Link the previous Platform version ```bash ln -s /opt/pronghorn/ /opt/pronghorn/current ``` #### Start the Platform Start the Platform. At this point, Itential Platform should be rolled back to the previous version with the database as it was prior to upgrading. ## Troubleshooting Refer to [Common Errors](/itential-platform/maintain/upgrade/common-upgrade-errors) to help identify and resolve frequent errors encountered during an upgrade. If unable to resolve, contact the [Itential Service Desk](https://itential.atlassian.net/servicedesk/customer/portal/14). > How to upgrade Itential Platform using the BIN installer for on-premises deployments in legacy release versions (2022.1, 2023.1, 2023.2), including rollback procedures.