Before registering your server with LCS, there are a few things you must configure. The sections in this guide walk you through these steps:
- Downloading the LCS Client App
- Preconfiguring LCS to Connect Through a Proxy
- Ensuring Access to LCS
- NTP Server Synchronization
- Configuring the Patching Tool
- Configuring WebSphere: This is only necessary if you’re running Liferay DXP on the WebSphere application server.
- Installing the LCS Client App
The last section in this guide shows you how to upgrade the LCS client app once your server is registered with LCS. We highly recommend that you upgrade the app whenever Liferay releases a new version of it.
The LCS client app is included in each Liferay DXP bundle and autodeploys when the bundle starts. The included version of the app, however, may be outdated. To get the latest version of the LCS client app, you must first download it via Liferay Marketplace.
Use these steps to purchase and download the app (if you’ve already purchased the app, you can skip to step 3 to download it):
Navigate to the LCS client app in Liferay Marketplace. Sign in to Marketplace, then click the LCS client app’s Free button.
Select your project, accept the license agreement, and then click the Purchase button. Marketplace then displays your receipt.
On the receipt, click See Purchased. This shows where you can download the LCS client app. To download the app, click the App button next to the latest version of the app.
Great! You’ve successfully downloaded the LCS client app. Before installing it, however, there are a few additional pre-configuration steps you should complete. These appear next; then you’ll learn how to install the app.
If your server connects to the Internet through a proxy, you must set some properties before deploying the LCS client app. There are three ways to do so—chose only one:
To set the proxy properties in your server, set them as JVM app server arguments. Set these properties to the appropriate values for your proxy:
-Dhttp.proxyHost= -Dhttp.proxyPort= -Dhttp.proxyUser= -Dhttp.proxyPassword= -Dhttps.proxyHost= -Dhttps.proxyPort=
Note that the
https properties are only needed if your
proxy requires authentication.
To set the proxy properties via versions 6+ of the LCS client app, you must create and deploy a config file containing the properties. Follow these steps to do so:
Create the config file
com.liferay.lcs.client.configuration.LCSConfiguration.config. In the steps that follow, you’ll set the proxy properties in this file.
proxy*properties to the appropriate values for your proxy:
If your proxy requires authentication, pass the credentials via these properties:
If your proxy requires NTLM authentication, you must also populate these properties:
proxyAuthType="ntlm" proxyDomain="" proxyWorkstation=""
Be sure to set
proxyWorkstationto the appropriate values for your proxy. Note that you can leave
proxyWorkstationblank if you don’t need it.
Deploy the config file to
Versions of the LCS client app prior to version 6 were distributed as a WAR file. To configure these versions of the app to connect through a proxy, you must therefore set their properties in that WAR file. Follow these steps to do so:
Extract the LCS client app’s WAR file from the app’s LPKG file (the app downloads from Liferay Marketplace as an LPKG file). Expand the LPKG file, then locate and expand the client’s WAR file:
In the LCS client’s WAR file, create the file
WEB-INF/classes/portlet-ext.properties(or open this file if it already exists).
Add the following properties at the end of
portlet-ext.propertiesand set them to the appropriate values for your proxy:
If your proxy requires authentication, you should also add the following properties and set them to the appropriate values for your proxy:
If your proxy requires NTLM authentication, you must also add the following properties:
proxy.auth.type=ntlm proxy.domain= proxy.workstation=
Be sure to set
proxy.workstationto the appropriate values for your proxy. Note that you can leave
proxy.workstationblank if you don’t need it.
Repackage the LCS client WAR with the modified
portlet-ext.propertiesfile, then repackage the LPKG file with the LCS client WAR. Make sure the repackaged LPKG file has the same name as the original LPKG file downloaded from Liferay Marketplace.
For the LCS client app to work, it must be able to access the following DNS names. If your server is behind a proxy and/or a firewall, then you must open access to these:
As an added security measure, you can also restrict traffic to HTTPS.
The next section discusses NTP server synchronization.
For LCS to work properly, the application server running Liferay DXP should be synchronized with a time server. If it’s not, you may get log errors similar to these:
ERROR [pool-6-thread-3][HandshakeTask:68] java.lang.RuntimeException: Handshake expired. Check that the server is synchronized with an NTP server. WARN [liferay/hot_deploy-1][LCSHotDeployMessageListener:186] LCS portlet is not connected java.lang.RuntimeException: com.liferay.jsonwebserviceclient.JSONWebServiceInvocationException: com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'oauth_problem': was expecting ('true', 'false' or 'null')_ at [Source: oauth_problem=timestamp_refused&oauth_acceptable_timestamps=1477311475-1477312075; line: 1, column: 14] [Sanitized]
For information on how to synchronize your application server with a time server, see your application server’s documentation.
Next, you’ll learn how to configure Liferay DXP’s patching tool.
Once installed, there are a few steps you must complete before LCS can use the
patching tool. Note that the commands below apply to Linux, Unix, and Mac. If
you’re running Windows, drop the
.sh from each command that has it.
Navigate to the
patching-tooldirectory on the command line. It’s typically located in the Liferay Home folder. Liferay Home is usually the parent folder of the application server’s folder.
To let the patching tool discover your Liferay DXP installation, run this command:
To configure the patching tool, run this command:
On server startup, the patching tool agent installs the patches downloaded by LCS. For the agent to start with your server, you must set the
javaagentproperty in the JVM options to point to your patching tool installation’s
patching-tool-agent.jar. Be sure to specify the correct path to this file:
If your patching tool is installed in a location other than the Liferay Home folder, you must also specify the
patching-toolfolder’s path as an app server JVM argument. Do this with the
There are also a few other things to consider when using the agent. Due to class
loading issues, the agent starts in a separate JVM. You can specify options for
it with the
-Dpatching.tool.agent.jvm.opts="-Xmx1024m -Xms512m -Dfile.encoding=UTF-8"
You may also experience issues on Windows if the user starting the app server doesn’t have administrator privileges. Here are some examples of the errors you may see:
java.nio.file.FileSystemException: ..\webapps\ROOT\WEB-INF\lib\util-java.jar: Not a file! java.io.FileNotFoundException: java.io.IOException: Access refused
To solve this, set the
java.io.tmpdir system property as follows in the
-Dpatching.tool.agent.jvm.opts="-Xmx1024m -Xms512m -Dfile.encoding=UTF-8 -Djava.io.tmpdir=%TMP%"
The agent also has some flags you can set to control how it behaves:
debug: Provides verbose output in the console.
nohalt: Starts the portal even if the agent encounters an issue.
You can specify these as follows:
IBM ® WebSphere ® is a trademark of International Business Machines Corporation, registered in many jurisdictions worldwide.
If you’re running the WebSphere application server, then there are some additional configuration steps you must take before deploying the LCS client app:
Shut down the application server.
Add the following in a
module.framework.properties.org.osgi.framework.bootdelegation=\ __redirected,\ com.sun.ccpp,\ com.sun.ccpp.*,\ com.liferay.aspectj,\ com.liferay.aspectj.*,\ com.liferay.portal.servlet.delegate,\ com.liferay.portal.servlet.delegate*,\ com.sun.crypto.*,\ com.sun.image.*,\ com.sun.jmx.*,\ com.sun.jna,\ com.sun.jndi.*,\ com.sun.mail.*,\ com.sun.management.*,\ com.sun.media.*,\ com.sun.msv.*,\ com.sun.org.*,\ com.sun.syndication,\ com.sun.tools.*,\ com.sun.xml.*,\ com.yourkit.*,\ com.ibm.*,\ sun.*
In your Liferay DXP installation, delete the
Start the application server.
Navigate to the WebSphere console in a browser.
Select your server and navigate to Java and Process Management → Process Definition → Additional Properties.
Select Java Virtual Machine → Custom Properties.
Click New, and enter the following:
Click Save, then OK to apply changes to the master configuration.
Note that for LCS client app versions prior to 5.0.0, you must also change the
value of the
digital.signature.algorithm.provider property in the app’s
portlet.properties file to
Once you’ve addressed the above pre-configuration steps, you’re ready to install the LCS client app. Follow these steps to install the app:
In your Liferay Home folder (usually the parent folder of the application server’s folder), delete this file:
osgi/marketplace/Liferay Connected Services Client.lpkg
Place the new
Liferay Connected Services Client.lpkgin
Great! Now you’re all set to register your server with LCS.
The next section shows you how to upgrade the LCS client app. We highly recommend that you do this whenever Liferay releases a new version of the app.
Your server should always be running the latest version of the LCS client app. There are two ways to upgrade the app, depending on the exact LCS pre-configuration steps you followed:
Via Liferay Marketplace inside Liferay DXP. Use this method if you don’t need to configure the LCS client app (e.g., to connect through a proxy) before it deploys.
To perform the upgrade, first navigate to Control Panel → Apps → Purchased. Apps needing an update are listed first. Click Update next to the LCS client app. Note that you may need to restart your server for the upgrade to complete.
Manually, after downloading the LCS client app’s LPKG file to your machine. Use this method if you must pre-configure the LCS client app to connect through a proxy.
To update the LCS client app manually, follow the previous sections in this guide for downloading and pre-configuring the app. Then deploy it to
[Liferay Home]/deployas you would any other app.
Contact Liferay Support if you need additional assistance with the upgrade process.