If you’re using a Liferay DXP bundle, the Patching Tool is already installed. When an update is necessary to install a patch, the Patching Tool automatically asks for an update.
You follow the same procedure whether you’re installing or upgrading the Patching Tool. Once you’ve obtained it from the Customer Portal, unzip it anywhere in the file system. Generally it’s a good idea to keep it together with the Liferay DXP installation.
Upgrading is easy: override the previous Patching Tool with newest one by unzipping it on top of the old version.
The Patching Tool is a Java based application. The distribution contains shell/ .bat scripts to make it easier to use. On Unix systems you can run
On Windows, run
The latter method appears in the examples below. On Unix, replace the name of the executable before running the scripts.
The first thing you must do when installing patches is to shut down your server. On Windows operating systems, files that are in use are locked by the OS, and can’t be patched. On Unix-style systems, you can usually replace files that are running, but that still leaves the old ones loaded in memory. So your best bet is to shut down the application server that’s running Liferay DXP before you install a patch.
Liferay distributes patches as
.zip files, whether they are hotfixes or fix packs. When you receive one, either via a LESA ticket (hotfix) or through downloading a fix pack from the Customer Portal, place it in the Patching Tool’s
patches folder (e.g.,
Home]/patching-tool/patches) without unzipping it. Once you’ve done that, it’s a simple matter to install it. First, execute
This displays a list of patches you’ve already installed, along with a list of patches that can be installed from what’s in the
To install the available patches, use the following steps. First, issue the following command:
To make sure the all changed OSGi bundles replace the existing ones, it is recommended to delete the
osgi/state folder from the Liferay Home folder.
If there are new database indexes created by the patch, the Patching Tool tells you to update them. To get the list, run this command:
Since there’s no database connection at patching time, the indexes must be created at portal startup. To have the indexes created automatically, add the following line to the
portal-ext.properties file if the server has permissions to modify the indexes on the database:
Otherwise, you must create the indexes manually. Check the output of the
patching-tool index-info command for more details.
Once your patches have been installed, you can verify them by using the
patching-tool info command, which now shows your patches in the list of installed patches.
During the installation,
patching-backup.zip files are created and stored in the
ROOT/WEB-INF folder. These files are necessary to restore the Liferay DXP’s original state; removing them would disable further patching.
patching-backup.zip file is necessary for installing future patches, because the Patching Tool reverts the installed fix pack before installing a new one. To revert the installed fix pack, it examines the contents of the
patching-backup.zip to determine the changes that it needs to revert.
Handling Hotfixes and Patches
As stated above, hotfixes are short term fixes provided as quickly as possible, and fix packs are larger bundles of hotfixes provided to all customers at regular intervals. If you already have a hotfix installed and the fix pack that contains that hotfix is released, the Patching Tool can manage this for you. Fix packs always supersede hotfixes, so when you install your fix pack, the hotfix that it contains is uninstalled, and the fix pack version is installed in its place.
Sometimes there can be a fix to a fix pack. This is also handled automatically. If a new version of a fix pack is released, you can use the Patching Tool to install it. The Patching Tool uninstalls the old fix pack and installs the new version in its place.
Including ‘support-info’ in LESA Tickets
To enable Liferay to reproduce subscriber issues, it is critical that the patch level in a given environment be made available to Liferay.
To generate the patch level for your environment, use the following command:
A text file called
patching-tool-support-info-actual-timestamp.txt is created in the patching-tool folder. Please upload this file to the LESA ticket.
Fix Pack Dependencies
Some hotfixes require a fix pack to be installed first. If you attempt to install a hotfix that depends on a fix pack, the Patching Tool notifies you. Go to the customer portal and obtain the hotfix dependency. Once all the necessary patches are available in the
patches folder, the Patching Tool installs them.
The Patching Tool can also remove patches.
Removing or Reverting Patches
Have you noticed that the Patching Tool only seems to have an
install command? This is because patches are managed not by the command, but by what appears in the
patches folder. You manage the patches you have installed by adding or removing patches from this folder. If you currently have a patch installed that you don’t want, remove it from the
patches folder. When you run the
patching-tool install command, and the patch is removed.
If you want to remove all patches you’ve installed, use the
revert command. This removes all patches from your installation.
Prior to Fix Pack 13, the OSGi state folder could retain obsolete bundles in its cache. If you’re running a version prior to Fix Pack 13, delete the osgi/state folder in Liferay Home.
After you’ve performed your patching procedure (whether you’ve installed or removed patches), it’s important to clean up Liferay DXP’s cache of deployed code. This ensures that when you start the server, you’re using the revision you’ve just installed the patches for. This is really easy to do.
In the Liferay Home folder is a folder called
work. Remove the contents of this folder to clear out the cached code. Now you’re ready to start your server.
Comparing Patch Levels
If you’re a developer, the Patching Tool can show you what changed between different versions. These commands show you information about the different patch levels:
patching-tool diff: Prints the differences between two patch levels. At least one stored patch level must be available. This command accepts options for filtering the output:
source: Shows the source differences between the two patch levels.
files: Shows a list of the modified files.
fixed-issues: Shows a list of LPS/LPE issues from our issue tracking system.
For detailed usage information, run
patching-tool help diff.
patching-tool store: Manages patching level information for the
diff command. Your patches must contain source code to store the patch level and to prepare usable information for the
diff command. Here are the
store command options:
info: Prints the list of patches which make up the stored patch level.
add: Stores the patch level that can be found in the patches directory.
update: Adds or updates patch level information.
rm: Removes previously stored patch level information.
For detailed usage information, run
patching-tool help store.
Showing collisions between patches and deployed plugins
Some patches update files you might have customized via a plugin. The
patching-tool list-collisions command lists differences (collisions) between installed patch files and your plugin’s version of them. Here’s the command:
It is an alias for the following diff command:
patching-tool diff collisions files _base
_base is the literal patch level name. Collisions are only listed for installed patches that contain source code files.
Separating the Patches from the Liferay DXP Installation
As of Patching Tool 2.0.6, there’s a feature that helps reduce the patched Liferay DXP bundle size. If the bundle has been patched, you can make it smaller by moving the restore files out of it.
Patched bundles are large because the restore files by default are stored inside the web application’s WEB-INF folder. These files are required for patching the Liferay DXP instance again.
If these files were removed, subsequent patching processes would fail. Because of this, Liferay added an option to separate the patching files from the Liferay DXP bundle while still preserving restoring them safely when new patches arrive. To do this, you use this command:
patching-tool separate [separation_name]
This command produces a
liferay-patching-files-[separation-name].zipfile in the Patching Tool’s
patches folder. It contains the necessary files and metadata for patching, verification, and validation. Once you create this file, the patch files are removed from their default location and are now only available in this file. You can now move the file elsewhere to make the bundle’s size smaller.
WARNING: If the product is separated from its patches in this way, you cannot run most of the Patching Tool commands until the patches are restored.
After the separation process only the following commands can be used:
Any other command returns this:
This installation does not include data for patching. Please copy the liferay-patching-files-[separation-name].zip file into the 'patches' directory and run patching-tool setup.
This is how you restore the patch files to your system. Details below.
Restoring the Separated Patch Files
When you need to patch Liferay DXP again, you must restore the separated patch artifact. To do this, copy the
liferay-patching-files-[separation-name].zip back to the Patching Tool’s
patches folder and run
patching-tool setup command.
If the command finds the necessary patching artifact, it restores the patch files to the bundle. After that, the Patching Tool works like it did prior to separating the patches.