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 OSGI framework to build modular application which comprises of 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 the lifecycle of module, manipulate the configuration and few other things with the help of human readable commands (or script) which is independent of any OSGI implementation.

Apache Felix Gogo Shell in Liferay 7 (DXP)

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

What is Gogo Shell

It is supplied by Apache and sub-project of Apache Felix implementation which provides command line mechanism to interact with OSGI container. It is based on RFC 147 which represents standards way of implementing and run shell commands for any OSGI container.

How to access Gogo Shell

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

  • Apache Felix Gogo Command (0.12.0) – Contains 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 browser.

There are various options to connect the Gogo shell tool in Liferay 7 / DXP as below. 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

Using Telnet

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

Below are the steps to enable it on Window system.

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

enable_gogo_shell - Gogo Shell

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

The next step is to connect it with telnet.

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

gogo_shell_console- Gogo Shell

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 name of host to connect. In case if your Liferay server is running on remote machine, you can connect with remote machine IP.

11311 is the default port to connect Gogo shell.

How to change the port of Gogo Shell

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

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 above property will not work. So simply remove include-and-override=portal-developer.properties if that is present in your portal-ext.properties.

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

In this case connecting Gogo Shell to individual instance is not possible with single Port (in facet you will see error in server log saying 11311 port is in use while running second Liferay 7 / DXP instance). You can use 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).

Connect Gogo Shell with Putty

Another (straight forward) way to connect is with putty. It is a common practice to connect various environment 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 below screenshot

connect_gogo_shell_with_putty- Gogo Shell

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

Connect Gogo Shell from Liferay IDE

You can connect Gogo shell from Liferay IDE as well. The prerequisite for this options is, you need 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 Servers window in eclipse and you will see below context menu in Liferay IDE. If Liferay 7 / DXP server is not up, you will see Open Gogo shell options disabled per below screenshot.

disable_gogo_shell- Gogo Shell

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

enable_gogo_shell - Gogo Shell

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

terminal widows - Gogo Shell

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

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

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

terminal widows - Gogo Shell

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

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

terminal widows - Gogo Shell

  • 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 OK button and you are done.

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

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

Possible reason

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

  • Stop the Liferay 7 / DXP server
  • Double click on server entry from Server console and you will see server configuration page as below.
  • set_developer_mode_off - Gogo Shell
  • 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 help command to see all possible commands. The lb command list down all deployed modules on OSGI container.

Summing Up

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

Share This Post

2 Comments - Write a Comment

Post Comment