LCS Preconfiguration

Note: The following LCS features have been deprecated and removed in March 2020: Page Analytics, Fix Pack Management, and Portal Properties. Please read the LCS Feature Deprecation Update to learn more about how you can prepare for these upcoming changes.

Before registering your server with LCS, there are a few things you must configure. The sections in this guide walk you through these steps:

1. Downloading the LCS Client App
2. Preconfiguring LCS to Connect Through a Proxy
3. Ensuring Access to LCS
4. NTP Server Synchronization
5. Configuring the Patching Tool
6. Configuring WebSphere: This is only necessary if you’re running Liferay DXP on the WebSphere application server.
7. 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.

Note: You must use LCS for activation of Elastic subscriptions. Otherwise, you don’t have to use LCS for activation. You can instead request an XML activation key from Liferay Support.

Downloading the LCS Client App

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.

Note: Even though Liferay Marketplace and this guide use the term purchase, the LCS client app is free of charge. The purchase process for a free app in Liferay Marketplace adds the app to your Liferay project, much like downloading a free app in a mobile app store adds the app to your account.

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):

1. Navigate to the LCS client app in Liferay Marketplace. Sign in to Marketplace, then click the LCS client app’s Free button.

   

   Figure 1: Click the app's *Free* button to begin the purchase process.

2. Select your project, accept the license agreement, and then click the Purchase button. Marketplace then displays your receipt.

   

   Figure 2: Liferay Marketplace displays your receipt for the LCS client app.

3. 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.

   Note: If you must download the LCS client app later, such as when upgrading it, select Purchased Apps from the User menu at the top-right of Liferay Marketplace. On the Purchased Apps screen, select the project you associated with the LCS client app and then select the app. This takes you to the same downloads page shown in the screenshot.

   

   Figure 3: Click the *App* button next to the version of the app you want to download.

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.

Note: If your server connects to the Internet through a proxy, you must configure your server or the LCS client app before deploying the app. The following section contains instructions on this. If your server doesn’t connect through a proxy, skip this section.

Preconfiguring LCS to Connect Through a Proxy

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:

1. As JVM app server arguments.

2. As LCS client app properties (LCS client app versions 6+).

3. As LCS client app properties (earlier versions of the LCS client app).

Note: Use only one of these methods to configure your server to connect through a proxy.

JVM App Server Arguments

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 user, password, and https properties are only needed if your proxy requires authentication.

LCS Client App Properties: Versions 6+

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:

1. 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.

2. Set these proxy* properties to the appropriate values for your proxy:

   proxyHostName=""
   proxyHostPort=""
   

3. If your proxy requires authentication, pass the credentials via these properties:

   proxyHostLogin=""
   proxyHostPassword=""
   

4. If your proxy requires NTLM authentication, you must also populate these properties:

   proxyAuthType="ntlm"
   proxyDomain=""
   proxyWorkstation=""
   

   Be sure to set proxyDomain and proxyWorkstation to the appropriate values for your proxy. Note that you can leave proxyWorkstation blank if you don’t need it.

5. Deploy the config file to osgi/configs.

LCS Client App Properties: Earlier Versions

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:

1. 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: lcs-portlet-[version].war.

2. In the LCS client’s WAR file, create the file WEB-INF/classes/portlet-ext.properties (or open this file if it already exists).

3. Add the following properties at the end of portlet-ext.properties and set them to the appropriate values for your proxy:

   proxy.host.name=
   proxy.host.port=
   

4. If your proxy requires authentication, you should also add the following properties and set them to the appropriate values for your proxy:

   proxy.host.login=
   proxy.host.password=
   

5. 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.domain and proxy.workstation to the appropriate values for your proxy. Note that you can leave proxy.workstation blank if you don’t need it.

6. Repackage the LCS client WAR with the modified portlet-ext.properties file, 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.

Ensuring Access to LCS

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:

• lcs.liferay.com
• lcs-gateway.liferay.com

As an added security measure, you can also restrict traffic to HTTPS.

The next section discusses NTP server synchronization.

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.

Configuring the Patching Tool

LCS uses Liferay DXP’s patching tool to apply updates. In bundles, the patching tool is pre-installed. If you’re not running a bundle, you must download and install the patching tool separately.

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.

1. Navigate to the patching-tool directory 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.

2. To let the patching tool discover your Liferay DXP installation, run this command:

   patching-tool.sh auto-discovery
   

3. To configure the patching tool, run this command:

   patching-tool.sh setup
   

4. 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 javaagent property 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:

   -javaagent:../../patching-tool/lib/patching-tool-agent.jar
   

5. If your patching tool is installed in a location other than the Liferay Home folder, you must also specify the patching-tool folder’s path as an app server JVM argument. Do this with the patching.tool.home property:

   -Dpatching.tool.home=/opt/liferay-dxp-digital-enterprise-7.0/patching-tool/
   

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 patching.tool.agent.jvm.opts property.

-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 patching.tool.agent.jvm.opts property:

-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:

-Dpatching.tool.agent.properties=debug,nohalt

Configuring WebSphere

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:

1. Shut down the application server.

2. Add the following in a portal-ext.properties file:

   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.*
   

3. In your Liferay DXP installation, delete the osgi/state folder.

4. Start the application server.

5. Navigate to the WebSphere console in a browser.

6. Select your server and navigate to Java and Process Management → Process Definition → Additional Properties.

7. Select Java Virtual Machine → Custom Properties.

8. Click New, and enter the following:

   • Name: com.ibm.crypto.provider.DoRSATypeChecking
   • Value: false

9. 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 IBMJCE:

digital.signature.algorithm.provider=IBMJCE

Installing the LCS Client App

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:

1. 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
   

2. Place the new Liferay Connected Services Client.lpkg in osgi/marketplace.

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.

Upgrading the LCS Client 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:

1. 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.

   Note: If you choose this method and have a clustered environment, you must perform the upgrade separately on each node in your cluster. Therefore, you may prefer to upgrade manually as detailed in the next step to ensure that all your nodes are running the exact same version of the LCS client app.

   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.

2. 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.

   Note: If you used JVM app server arguments to configure your server to connect through a proxy, then you don’t need to pre-configure the LCS client app to connect through the same 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]/deploy as you would any other app.

Contact Liferay Support if you need additional assistance with the upgrade process.