How to apply patches to Mule 4.x

GOAL

To apply patches to the Mule 4 runtime.
IMPORTANT: Patches are created for a specific release of a product. Don't try to use a patch for a version with another product version. That could lead to instabilities and hard to debug issues.
Note: As of now, even after successfully applying new runtime patch, the version is not reflected in Runtime Manager - Hybrid runtimes. Here is the KB <New runtime patch version is not reflected in Runtime Manager - Hybrid runtimes> to explain this.

PROCEDURE

Patching standalone Mule Runtime (4.1.x and 4.2.x)

Partial patches (SE-NNN-X.Y.Z.jar / MULE-NNN-X.Y.Z,jar) 

1. Copy the patch jar file to {MULE_HOME}/lib/patches
2. Restart the mule runtime instance to make it pick up the patch.

Note: Please consider that the patch naming convention that starts with MULE-NNNN*.jar(where N is a numeric value) such as MULE-19140-4.2.2-1.0.jar is a partial patch.

Full module patches (mule-AAA-BBB-X.Y.Z.jar)

1. Stop the Mule runtime.
2. Back up the original jar file from {MULE_HOME}/lib/mule and remove it.
3. Copy the new patches in the folder {MULE_HOME}/lib/mule
4. Restart the mule runtime instance to make it pick up the patch.

Notes:

• Please consider that the patch naming convention that starts with MULE-NNNN*.jar(where N is a numeric value) such as MULE-19140-4.2.2-1.0.jar are "partial patches".
• Whereas the full module patch will have a naming convention such as mule-AAA-BBB-X.Y.Z.jar and the patch file name(other than version) matches with existing jar files in {MULE_HOME}/lib.  example:- mule-module-batch-ee-4.2.0-20200518.jar is an updated full module for {MULE_HOME}/lib/patches/mule-module-batch-ee-4.2.0.jar

Patching standalone Mule Runtime (4.1.5 onwards, 4.2.x, 4.3.x and 4.4.x)

Cumulative patch (i.e. mule-ee-patch-4.4.0-YYYYMMDD-MONTH.zip) 

1. Stop the Mule runtime.
2. Extract the content of the cumulative-patch ZIP file
3. Read the extracted README.TXT file to understand the necessary steps to install the patch
4. Backup the original content of the {MULE_HOME}/lib/patches folder
5. Remove any previous patch files from {MULE_HOME}/lib/patches
   • IMPORTANT: Do not remove the patches inside {MULE_HOME}/lib/patches/mule-artifact-patches folder
6. Copy the new mule-ee-distribution-standalone-X.Y.Z-YYYYMMDD-patch.jar into {MULE_HOME}/lib/patches. At the end, MULE_HOME/lib/patches folder only keep mule-ee-distribution-standalone-{version}-patch.jar and MULE_HOME/lib/patches/mule-artifact-patches dir should stay.
7. The cumulative patch may require additional steps like patching a service or adding a system property, please refer to the README.TXT file for further details.
   • If a service update is required, this same article explains how to install the new service version (see section "Patching a Mule Service" below)
   • And in case a new property is required, please check: How can I set Mule and Java system properties at startup?
8. Restart the mule runtime instance to make it pick up the patch

Patching a Mule Plugin

Note: Ensure that the instance was successfully started at least once before executing this procedure

1. Stop the Mule runtime.
2. Backup the directory {MULE_HOME}/plugins/mule-plugin-AAAA_NNNN-X.Y.Z and remove it (current expanded directory of the plugin).
3. Paste the new patched plugin as it is (e.g.:mule-plugin-weave_A.AA-X.Y.Z-SE-NNNN-dist.zip) into  {MULE_HOME}/plugins/ . When Mule starts it will expand that directory.
4. Restart the Mule runtime.

Patching a Mule Service

For Mule Runtime 4.2.x, 4.3.x and 4.4.x  * IMPORTANT: If instructions in README.TXT is different from this knowledge article, follow instructions in the README.TXT

For lower versions:

1. Stop the Mule runtime.
2. Back up the existing instance of the service jar file. For example {MULE_HOME}/services/mule-service-weave-ee-2.1.3-mule-service.jar, and then remove it.
3. Paste the new patched service jar as-is into the same directory (e.g.mule-service-weave-ee-2.1.3-SE-8608-mule-service).
4. Restart the Mule runtime.

Patching a Mule runtime in Anypoint Studio 7.x

[RECOMMENDED] For Mule Runtime 4.3.x and 4.4.x 

For Mule Runtime 4.4.x, 4.3.x, 4.2.x and 4.1.x:

1. Identify the directory within the Studio installation where your runtime is installed. It will follow the pattern {STUDIO_HOME}/plugins/org.mule.tooling.server.{MULE_VERSION}.ee_n.n.n.nnnnnnnnnnnn , where {STUDIO_HOME} is where Studio is installed, {MULE_VERSION} is the Mule Runtime version (eg 4.1.1), n.n.n.nnnnnnnnnnnn is a release tag. If there are more than one directory with the same {MULE_VERSION} but different release tags, then select the one with the greatest release tag. Example: org.mule.tooling.server.4.1.1.ee_7.1.2.201803261303
2. Copy the patch jar file to  {STUDIO_HOME}/plugins/org.mule.tooling.server.{MULE_VERSION}.ee_n.n.n.nnnnnnnnnnnn/mule/lib/patches
3. If it's a Mule service, then back up the existing mule service jar from {STUDIO_HOME}/plugins/org.mule.tooling.server.{MULE_VERSION}.ee_n.n.n.nnnnnnnnnnnn/mule/services and then replace with the patched jar. (Note: Starting from Mule 4.2.0 only for services, proceed as an on-prem runtime (explained before) considering {STUDIO_HOME}/plugins/org.mule.tooling.server.{MULE_VERSION}.ee_n.n.n.nnnnnnnnnnnn as the mule home location)
4. Restart Studio

Setting MUnit to run with a patched version of the runtime
If you need for MUnit to run on a patched version of the runtime, this does not happen automatically once you patch the runtime itself and you need to make changes to either your Maven configuration or your Studio Run configuration for this to happen. For details on how to do this, please consult How to patch runtimes for MUnit.

Rollback Mule Runtime patches

Partial patches (SE-NNN-X.Y.Z.jar)

1. Stop the mule runtime instance.
2. Remove the patch jar files from {MULE_HOME}/lib/patches
3. Restart the mule runtime instance.

Full module patches (mule-AAA-BBB-X.Y.Z.jar) / Mule Service Patches / Mule Plugin Patches

1. Stop the mule runtime instance.
2. Remove the new applied patch and put back the backed up jar files in the same directory.
3. Restart the mule runtime instance.

Rollback Studio Runtime patches

1. Identify the directory within the Studio installation where your runtime is installed. It will follow the pattern {STUDIO_HOME}/plugins/org.mule.tooling.server.{MULE_VERSION}.ee_n.n.n.nnnnnnnnnnnn , where {STUDIO_HOME} is where Studio is installed, {MULE_VERSION} is the Mule Runtime version (eg 4.1.1), n.n.n.nnnnnnnnnnnn is a release tag. If there are more than one directory with the same {MULE_VERSION} but different release tags, then select the one with the greatest release tag. Example: org.mule.tooling.server.4.1.1.ee_7.1.2.201803261303
2. Remove the patch jar file from {STUDIO_HOME}/plugins/org.mule.tooling.server.{MULE_VERSION}.ee_n.n.n.nnnnnnnnnnnn/mule/lib/patches
3. If it's a Mule service, then delete the patched service jars from {STUDIO_HOME}/plugins/org.mule.tooling.server.{MULE_VERSION}.ee_n.n.n.nnnnnnnnnnnn/mule/services and then put back the original service jars from backup.
4. Restart Studio