--- schema_version: "1" id: c6f3f523c140c741d71871ed3f4315ad9dc01dac1f89d5354179c75b27b6e170 title: Upgrading Mule Runtime Engine (Versions 3.x to 3.n) collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/release-notes/mule-runtime/updating-mule-versions.md canonical_url: https://docs.mulesoft.com/release-notes/mule-runtime/updating-mule-versions source_site: docs.mulesoft.com content_type: documentation content_hash: 1c7bf8168c62efc45be3eb1f1f5dd0f27929696b404f05c1187de4aeb4d8d366 description: MuleSoft Documentation Site latest: true --- --- product: Release Notes version: master keywords: mule, runtime, release notes, migration, installation, downtime, uptime, best practices --- # Upgrading Mule Runtime Engine (Versions 3.x to 3.n) > For the full documentation index, see: https://docs.mulesoft.com/llms.txt **Mule 3.x Upgrades Only** (For guidance with migrations from Mule 3.x to Mule 4, see [Mule 4 for Mule 3 Users](https://docs.mulesoft.com/mule-runtime/latest/).) This document describes considerations and best practices when changing the 3.x versions of Mule runtime engine on your on-premises servers in the following deployments: - Mule standalone instances - Mule instances on-premises through [Runtime Manager](https://docs.mulesoft.com/runtime-manager/) > [!TIP] Keep in mind that if you’re deploying your applications to **CloudHub**, then this content > is not relevant to you, with the exception of the steps outlined in the section > [Application Runtime Version](#application-runtime-version). Changing the Mule runtime version of > a Mule application that’s deployed to on CloudHub is simply managed from the > [runtime version drop-down box](https://docs.mulesoft.com/cloudhub/deploying-to-cloudhub#runtime-tab) in the > application settings deployment configuration page. ## Application Runtime Version > [!NOTE] Mule runtimes use semantic versioning, therefore please note that Mule applications: > > - Are most likely not compatible between major runtime versions releases (e.g. **z**.0.0) > > - Are potentially compatible between minor runtime version releases (e.g: 3.**y**.0), but MuleSoft > recommends executing a regression test cycle to validate this. > > - Are assured to be fully compatible for patch releases of the Mule runtime (e.g: 3.8.**x**) Before you begin, read the [release notes](https://docs.mulesoft.com/release-notes/mule-runtime/mule-esb) for the Mule Runtime version you wish to upgrade to (which we will call the target version, from here on), to know if you must make any necessary changes to your applications to ensure compatibility. For example, if you migrate from a version that’s older than 3.6 to a version that’s newer, you might want to change all HTTP connectors to the newer version of this connector as the old one is deprecated as of Mule Runtime 3.6. If there are no relevant changes between the Mule Runtime version in which the application is developed and the target Mule Runtime version to which you’re migrating, then you shouldn’t need to modify your application. Mule Runtimes support having applications that are built with older Mule versions deployed to them. If you do decide to change your Mule application’s version, you must: 1. [Install Mule Runtime Engine in Anypoint Studio](https://docs.mulesoft.com/studio/install-mule-runtime-versions) to handle that version in the IDE. 2. For every application that you update: 1. [Import the application](https://docs.mulesoft.com/studio/import-export-packages) to Anypoint Studio as a Mule project. 2. Navigate the package explorer on the left to find its `mule-project.xml` file and open it. Change the Mule version by selecting it from the **Server Runtime** dropdown menu. ![updating mule versions 364d6](/mulesoft/current/en-us/release-notes/_images/mule-runtime/updating-mule-versions-364d6.png) 3. Make any other changes to your Mule project that may be necessary depending on the version gap you’re transitioning. 4. Export your project as a Mule Deployable Archive (.zip file). If you use Maven to build your application, edit its **pom.xml** file to change the `muleVersion` property value, so that it matches the target version. Once the Mule Deployable Archives (.zip files) are in versions that you’re sure are compatible with the target runtime version and you’ve also validated that any other necessary changes that ensure compatibility have been applied, you can move on to installing the corresponding Mule Runtime on your servers. ## Mule Standalone Runtime Version > [!TIP] To ensure that you have faster downtime and an easier backup route, we recommend that you > initially install your new Mule Runtime on a separate server from where you have your current Mule > Runtime installed. 1. Download the new Mule version from the Customer Portal and install it (preferably on a different server or virtual machine). 2. If any of your applications use shared custom libraries, make sure you copy those .jar files to the `/lib/user` directory of the new version. > [!NOTE] If any of your previous applications rely on a full or a partial custom patch in order > to work properly (these would be found in the folder `/lib/user`), please verify > that the fix is included in this target release by reviewing the corresponding > [release notes](https://docs.mulesoft.com/release-notes/mule-runtime/mule-esb) page. > > Otherwise, please contact MuleSoft Support by creating a new support case, to request a new > patch compatible with the target version. Patch files are version specific and MUST NOT be > used in a different runtime version. 3. Download a new copy of your license from the Customer Portal and install it on the target version, by following the instructions described at Installing an Entrerprise License. 4. If you have set any custom configurations to your runtime instance – for example: if you defined a different maximum heap size in the `wrapper.conf` file – you might want to replicate these settings manually. 5. Run your new Mule Server to verify your installation is working as expected. 6. Depending on the circumstances and your current infrastructure, you might want to consider shutting down your previous Mule Server at this point. Please evaluate the impact of this action before proceeding. 7. If you have previously set any environment variables, such as `MULE_HOME` or `PATH`, make sure that they are now pointing to the new Runtime’s installation path. 8. Deploy your applications to your new Mule Server. ## Mule Runtime Version on Runtime Manager > [!NOTE] To migrate following these steps, you must have the > [Runtime Management Agent](https://docs.mulesoft.com/runtime-manager/runtime-manager-agent) installed. The agent comes > bundled with Mule runtime as of version 3.6.0 and later. In case you’re migrating from a Mule > runtime version that is older than that, you must do this migration manually. > [!TIP] To ensure that you’ll have less downtime and an easier backup route, we recommend that you > initially install your new Mule Runtime on a separate server from where you have your current Mule > Runtime installed. That way you can set everything up and only then decouple the old server and > initiate the new one. To migrate your Mule servers on-premises that are being managed through Runtime Manager, you must perform these steps on each: 1. Go through steps 1 through to 5 of the previous section, [Mule Standalone Runtime Version](#mule-standalone-runtime-version) 2. Copy the following three files from the path `/conf` from your old Mule installation into the same on the new installation: - `mule-agent.yml` - `mule-agent.jks` - `truststore.jks` and/or `anypoint-truststore.jks` 3. Copy the mule-agent-plugin folder from the path `/plugins` from your old Mule installation into the same on the new installation. 4. Open a terminal window and navigate to the `/bin` of your new Mule installation. Once there, run the following command: amc\_setup -U Through executing this command, you’re installing the latest version of the Runtime Manager Agent on your Mule runtime, which is assured to be compatible with your target runtime version. The files you copied from your old installation hold all of the configuration information that registers the Mule instance on Runtime Manager, so no further steps should be needed. Even when you’re installing your new Mule runtime version on another server or VM, the copied configuration files should suffice to smoothly transition the Mule instance’s identity on the Runtime Manager. If your origin server had apps that were deployed to it through the Runtime Manager, there’s no need to manually copy these, as they automatically upload to your new server when instructed to deploy them through Runtime Manager. > [!CAUTION] Applications must be running and showing as `Started` in Runtime Manager. This > process does not migrate stopped Applications. 5. At this point the Mule server is already updated to the target version. Updating the Mule applications that are deployed to it is optional. If wish to do so to take full advantage of the features of the target runtime, then you must also: 1. Follow the steps in [Application Runtime Version](#application-runtime-version) to update your application. 2. Find the application on the **Applications** tab on Runtime Manager and click **Choose File** to [upload](https://docs.mulesoft.com/runtime-manager/managing-deployed-applications#updating-your-application) the new Mule Deployable Archive (.zip file). ## Upgrade the Mule Runtime Version in a Runtime Manager Server Group Follow these steps to upgrade the Mule version in a Runtime Manager server group: 1. Go to Anypoint Runtime Manager. 2. Switch to the corresponding environment. 3. Select **Servers** in the navigation menu. 4. Select the server group to update. 1. In the server group dashboard, select the **Servers** tab and select the server to upgrade. 2. In the actions dropdown menu, select **Shutdown**. 3. Repeat the previous two steps for each server in your server group. 5. Open a terminal in the local machine that hosts your Mule instance. 6. If your Runtime Manager agent version is earlier than 1.12.0, upgrade to the latest version. Go to the current Mule Home directory and run the following commands: `cd ${MULE-3.8.4_HOME}/bin` `cp ~/Downloads/agent-setup-1.15.3.zip .` `unzip agent-setup-1.15.3.zip` `./amc_setup -U` 7. Go to the target directory for the new Mule runtime version and install it: `cd ${MULE-3.9.5_DIRECTORY}` `cp ~/Downloads/mule-ee-distribution-standalone-3.9.5.zip .` `unzip mule-ee-distribution-standalone-3.9.5.zip` 8. Install the latest agent version: `cd mule-enterprise-standalone-3.9.5/bin` `cp ~/Downloads/agent-setup-1.15.3.zip .` `unzip agent-setup-1.15.3.zip` `./amc_setup -I` `rm ../conf/mule-agent.yml` 9. Copy the following files from the previous Mule runtime `/conf` directory to the new Mule runtime `/conf` directory: - All YAML files (`*.yml`) - All keystore files (`*.jks`) 10. Confirm that the DNS configured in `mule-agent.yml` has the following values: websocket.transport: consoleUri: wss://runtime-manager.anypoint.mulesoft.com:443/mule authenticationProxy: endpoint: https://data-authenticator.anypoint.mulesoft.com 11. If you installed domains in your previous Mule instance, copy those domains to your new Mule instance: `cp -R ${MULE-3.8.4_HOME}/domains${MULE-3.9.5_HOME}/domains` 12. Start Mule: `cd ${MULE-3.9.5_HOME}/bin` `./mule start` 13. Go to Runtime Manager to confirm that your Mule applications are deployed and displayed as **Running**. ## Upgrading a Runtime Manager Cluster > [!NOTE] Copy the `mule-cluster.properties` file located in the `$MULE_HOME/.mule/` directory from > your old Mule installation in the same folder on the new installation to configure the Mule > runtime instance to work as a cluster node. Zero downtime cannot be guaranteed when migrating clusters to another version. At some point during the migration the cluster is in a mixed state, with coexisting nodes running two different versions. This might lead to incompatible communication protocols between Hazelcast instances. When such errors occur, every node in the cluster must be shut down to proceed with the migration. ## Mule Management Console Versions > [!NOTE] Note that unless instructed otherwise, you need to upgrade your MMC version to handle the > corresponding Mule Runtime. See our > [policies](https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf) > regarding MMC versioning. Keep in mind that Mule versions prior to 3.5 aren’t supported on MMC. For each of the servers that you manage through MMC, go through steps 1 through to 5 of the section, [Mule Standalone Runtime Version](#mule-standalone-runtime-version) If you use default persistence on MMC, the recommended way to migrate to a newer MMC version is to perform a clean install of MMC and then register your existing Mule Servers to this new version. In that case, before installing the new version you must: 1. Disband any existing cluster (if any). 2. Unregister all your servers from the old MMC version. 3. Undeploy the previous MMC version from your servlet `container/application` server. 4. Delete the `mmc-data` folder (after making a backup of it) On the other hand, if you prefer to perform an upgrade directly, once you have the latest copy of the MMC `.war` file (available for download through our Support Center), you must then follow these steps: 1. Stop your application server (E.g: Tomcat). 2. In case you have enabled LDAP support and/or configured an External Database, you must backup all the custom configuration files ( see the [Backing up MMC Configuration Files](#backing-up-mmc-configuration-files) section below). 3. Uncompress the recently downloaded MMC .war file (you can simply manually change the .war extension to .zip and it can then be handled by any software that supports the .zip extension). 4. Replace the configuration files on this new MMC version with the files that you backed up from the older version in the previous step. 5. Pack/Compress the folder contents back, and make sure its extension is `.war` (simply rename the file’s extension, if necessary). 6. Start you application server and undeploy the previously installed MMC version. 7. Restart your application server and deploy the new version of MMC. ### Backing up MMC Configuration Files > [!NOTE] The following information applies to MMC versions 3.4.2 and 3.5.x onwards to the latest. The following files need to be backed up from your current MMC installation in order to preserve any custom configuration it may have, such as LDAP support and External Database configurations: 1. `/WEB-INF/web.xml` 2. `/WEB-INF/classes/META-INF/mmc-ldap.properties` 3. `/WEB-INF/classes/META-INF/databases/-.properties` > [!TIP] The `` path could either refer to the copy of your `custom/"already configured"` > MMC .war file you are currenlty deploying, or to the current exploded MMC’s application folder at > your application server `application` directory. > [!NOTE] Please note that these are only configuration files, by backing them up you are NOT > preserving the current state of your MMC. > > Make sure that MMC and the application servers are not running at the moment you back these files > up ### MMC Agent Version Also, for earlier MMC versions than 3.4.0, make sure the version of the Mule Agent you use is also compatible with your target Runtime version. For MMC Agent versions, the rule of thumb is the following: For Mule versions 3.4.0 and later: - The MMC Console (or Server) version should be greater or equal to the ESB version. - Since the MMC Agent comes bundled with the Mule Runtime, there is no need to download it separately. If the MMC version is later than the ESB version, the bundled agent works transparently and there is no need to download it separately. For Mule versions earlier than 3.4.0: - The MMC Agent version should be the same as the Mule Runtime version. - The MMC Console (or Server) version should be greater or equal to the Runtime version. ### Upgrading an MMC Cluster With Zero Downtime > [!NOTE] These steps are valid only for clusters created with MMC. To achieve a zero downtime upgrade you need to have an external load balancer and set up two different clusters (it is not possible to have a cluster with mixed Mule Runtime versions). You need to implement the following procedure: 1. Install the new Mule Runtime in all of the servers. 2. Configure these new Mule instances as members of a different cluster. 3. Node by node, do the following: 1. Remove the old Mule instance from the load balancer so it won’t receive new invocations. 2. Shut down the old Mule instance. 3. Start up the new Mule instance. 4. Deploy all the applications to this new Mule instance. 5. Register the new Mule instance to the load balancer. ## See Also - [Known Issues](https://help.salesforce.com/s/issues)