How to connect Apache Gogo shell in Liferay 7 (DXP)

Gogo Shell provides an interface to interact with OSGI modules in Liferay 7

Liferay 7 uses the OSGi framework to build a modular application that comprises various modules. OSGi supports a standard way to interact with underlying modules. Any external system or portal administrators can use this mechanism to deal with Liferay 7 modules at runtime.

Apparently, you can control a module’s lifecycle, manipulate the configuration, and few other things with human-readable commands (or script), which is independent of any OSGI implementation.

The name of the tool which provides this functionality is Gogo Shell. It is a command-line interface (CLI) used to interact with bundles (or modules) deployed in an OSGi container. In this article, we will explore important points about it.

1. What is Gogo Shell

Apache supplies Gogo Shell, and it is a subproject of Apache Felix implementation, which provides a command-line mechanism to interact with the OSGi container. It is based on RFC 147, representing the standards way of implementing and running shell commands for any OSGi container.

2. How to access Gogo Shell

Liferay 7 provides Felix Gogo shell implementation in the form of (predefined) bundles (or modules). When the Liferay 7 / DXP server starts, you will see the following modules are available. They represent Felix Gogo Shell’s implementation.

• Apache Felix Gogo Command (0.12.0) – Contains a set of basic commands
• Apache Felix Gogo Runtime (0.10.0)  – Represents core command processing capability.
• Apache Felix Gogo Shell (0.10.0)– Textual presentation to interact with command processor.
• CE Foundation – Liferay CE Gogo Shell – Impl (1.0.0)  – Implementation of underlying Gogo shell interface.
• Liferay Gogo Shell Web (2.0.1) – Provides a web interface to execute Gogo commands from the browser.

There are various options to connect it in Liferay 7 / DXP as follows. You can choose either of them to interact with OSGI bundles. We will see each of them in detail.

1. Using Telnet
2. With Putty
3. From Liferay IDE

2.1 Using Telnet

I will be showing the option to connect the Gogo shell with telnet on a Windows machine. Telnet may not be enabled on your system by default. Open a command prompt and type telnet, and if you see the below error, then telnet is not activated on your system.

'telnet' is not recognized as an internal or external command,
operable program or batch file.

Below are the steps to enable it on the Windows system.

• Go to Control panel –>Programs and Features.
• Click on Turn Windows features on or off, and you will see separate windows like the below screenshot.

• Search and select Telnet Client. Click on the OK button. Allow some time to make it enable.

The next step is to connect it with telnet.

Open a command prompt. type the command – telnet localhost 11311, and you will see the following output in the console

Congratulation …!! You are ready to fire Gogo shell commands.

Note:- Since Gogo shell is part of Liferay 7 bundles, if Liferay 7 / DXP server is not running, you can not connect to it. In short, Liferay, 7 / DXP server must be up and running to work with it.

As this is my local machine, I have used localhost as the host’s name to connect. If your Liferay server is running on a remote machine, you can connect with remote machine IP.

11311 is the default port to connect the Gogo shell.

2.2 How to change the port of Gogo Shell

You can change the default port if you wish. For that, you need to define the following property in portal-ext.properties

module.framework.properties.osgi.console=11312

Note:- Make sure the property include-and-override=portal-developer.properties is not present in your portal-ext.properties file, or else, the custom port you set with the above property will not work. So simply remove include-and-override=portal-developer.properties if that is present in your portal-ext.properties.

Setting a custom telnet port to connect the Gogo shell is useful for running two separate Liferay 7 / DXP instances on a single physical machine. For example, you have your DEV and QA environment on a single Unix box.

In this case, connecting Gogo Shell to an individual instance is impossible with a single Port (in facet, you will see an error in the server log saying 11311 port is in use while running the second Liferay 7 / DXP instance). You can use the above property to change the Gogo shell port.

On setting above property, you can access it on 11312 port. (You can use any custom port which is not in use).

2.3 Connect with Putty

Another (straightforward) way to connect is with putty. It is common to connect various environments like DEV, QA, UAT, or Production with Putty. Below are the steps to connect it with Putty

• Start Putty and give the inputs as per the below screenshot

• Give Host Name as localhost. In case if you are connecting a remote machine, you can give the remote machine IP.
• Set the port as 11312 (as we set in portal-ext.properties, if not, the default would be 11311).
• Choose the Connection type as Telnet.
• Click on the Open button, and you will see Gogo shell in Putty.

2.4 Connect from Liferay IDE

You can connect Gogo shell from Liferay IDE as well. The prerequisite for these options is to run your Liferay 7 / DXP server within Liferay DXP only. So first, you should follow the steps to configure Liferay 7 within Liferay IDE.

Once configured, right-click on Liferay 7.x from the Servers window in eclipse, and you will see below the context menu in Liferay IDE. If Liferay 7 / DXP server is not up, you will see the Open Gogo shell option disabled per the below screenshot.

Once Liferay 7 (DXP) server is started, you will see this option enabled as per the below screenshot.

Click on it, and you will see the Terminal window as below.

Well done … !! You are connected to the Gogo shell from Liferay IDE.

Alternatively, you can open the Gogo Shell terminal window in Liferay IDE by following the below steps.

• Go to the Window menu of Liferay IDE (Eclipse) and click on Show View and choose Others…
• In the search text box on top, just type Terminal as per the below screenshot.

• Just click on the Open button, and you will see Terminal windows as per the below screenshot.

• Click on the small monitor icon on the right side, and Liferay IDE opens separate windows as below.

• Give the value as below.
  • Host: localhost
  • Port: 11312 (as we set in portal-ext.properties, if not, default would be 11311)
  • Encoding: UTF-8
• Click the OK button, and you are done.

2.5 Custom Gogo shell port does not in effect for embedded Liferay 7 / DXP server within Liferay IDE

Problem:  You may encounter the problem of the Gogo shell being connected to 11311 port only for embedded Liferay Server within Liferay IDE. Even though you mentioned a custom port, it is connected to the 11311 port only.

2.5.1 Possible reason

While connecting Gogo shell from Liferay IDE (with embedded server), I observed that if the Liferay server starts in developer mode, it is only connected on 11311 port irrespective of setting custom port in portal-ext.properties file. So if you face a similar issue, you can follow the below steps.

• Stop the Liferay 7 / DXP server.
• Double click on server entry from Server console, and you will see the server configuration page as below.
• 
• Just un-select Use developer mode checkbox and start the server. Now you can connect with your desire custom port (other than 11311)

Once you connect, just type the help command to see all possible commands. The lb command list down all deployed modules on the OSGI container.

3. Summing Up

• Apache Gogo shell is a command-line interface to connect bundles that are installed on the OSGi container.
• You can connect with it with either Telnet, Putty, or from Liferay IDE.
• Once connected, you can execute various commands from there.