The Shell Tool

The Shell Tool was introduced in XperienCentral version 10.12.0 and removed in version R43.

This topic explains how to use the Shell Tool which provides command line access to the Apache framework in which XperienCentral runs. This makes it possible to manage plugins, users and website settings from outside the XperienCentral GUI. The Shell Tool works for both local installations of XperienCentral as well as cloud installations. It is an extension of the Apache Felix GoGo shell. This topic only covers the XperienCentral-specific commands that you can execute from the Shell Tool. Documentation for the Apache Felix GoGo shell itself can be found at http://felix.apache.org/documentation/subprojects/apache-felix-framework/apache-felix-framework-usage-documentation.html .

In This Topic

1 Setting up the Shell Tool
2 Generating Keys
3 Managing Plugins from the Shell Tool
4 Managing Website Settings from the Shell Tool
5 Managing User Passwords from the Shell Tool
6 General Commands

Setting up the Shell Tool

Installing the Felix GoGo Extensions Plugin

The Felix Shell commands extension plugin is not installed by default — You have to install it manually. You can find the plugin in the XperienCentral SDK archive in the maven2-repository/nl/gx/webmanager/tools/webmanager-felix-shellcommands/<xperiencentral-version> directory. Add it by either copying the webmanager-felix-shellcommands-<xperiencentral version>.jar file to the <xperiencentral-root>/work/deploy directory or add it using the Plugins Management Console.

Configuring SSH

The Shell Tool requires SSH in order to allow access to the XperienCentral settings. To enable SSH, keys should be generated (version 2 RSA or DSA) and added to the XperienCentral SSH server configuration. You then have two options for pointing to the location of the keys:

Create the following folder and copy the keys to this location:
<xperiencentral-root>/work/config/ssh/ (the name of the file should be authorized_keys2).
Create a directory, copy the keys into it and point to it using the Java property webmanager.config.directory=<dir>.

For security reasons, SSH is enabled by default only on the internal network and can only be accessed by localhost on the default port 7009. To change this port, the system property osgi.console.ssh should be added to the Java system properties (-Dosgi.console.ssh=localhost:<port> or -Dosgi.console.ssh=127.0.0.1:<port>). To enable access from another host, set this to -Dosgi.console.ssh=<port>.

Back to Top

Generating Keys

There are different ways to generate the keys. Creating the keys according to the steps below will enable access from Linux systems (using SSH) as well as from Windows systems using PuTTY.

Generate Key Pair

Linux machine

Generate a key using ssh-keygen -t rsa on a Linux machine.

Windows machine

Putty KeyGen

Generate a key with the tool. The private key can be used by saving the key to file, The public key (for the authorized_keys2 file) must be copied/pasted from the PuTTY Keygen tool.

Configure the Server

Copy the public key to <xperiencentral-root>/work\config\ssh\authorized_keys2 on the installation
Start Tomcat with the extra environment variable:

CATALINA_OPTS="-Dosgi.console.ssh=<port number>"

Connect from the Linux Machine

ssh -i my_key_file -p <port number> thehostname

Connect from Windows using PuTTY

When the private key is generated via linux: Open the private key in PuTTYgen and save it as a PuTTY key. This conversion is needed because PuTTY does not accept OpenSSH keys.
Add this PuTTY private key to the putty session configuration by loading it (if the entry is not new), adding the key to
Connection > SSH > Auth > "Private key for authentication"
...and saving the configuration.
Open the connection (to <hostname>:<port number>, (using the PuTTY private key) and log in. If a username is requested, simply press [Enter] enter since the value will be ignored. Use the password chosen as pass phrase when the key pair was generated.

If you use PUTTYgen to generate the private/public keys, they might not work in the Linux environment with SSH.

Back to Top

Managing Plugins from the Shell Tool

In addition to the functionality available for managing plugins from the XperienCentral Plugins Management Console, there are equivalent commands available in the Shell Tool that you can invoke directly from the command line. To use the commands on a plugin in the Shell Tool, you must first determine the ID of a plugin by issuing the lb command in the Tomcat window. After you issue the lb command, you will see a list of the plugins and their IDs. For example:

Unknown Attachment

(click image to enlarge)

The following commands can be used on plugins running in XperienCentral from the Shell Tool:

Command	Description

Command	Description
`wmstart`	Registers services that each component within the bundle exposes if all required service dependencies are available. For each component, at the very least a component service is registered. Usage: `wmstart [id]` where `[id]` is the plugin identifier.
`wmstop`	Stops all services registered by the component. Usage `wmstop [id]` where `[id]` is the plugin identifier.
`wmupdate`	Updates the plugin to a newer version. If a problem is encountered during the update, the plugin is automatically rolled back to the existing version. The following describes a typical plugin update scenario: The plugin developer creates a 1.1 version of a plugin and gives it to a system administrator. The system administrator copies the updated plugin to the machine running XperienCentral. If XperienCentral is running in a clustered environment, the updated plugin is copied to the machine running the read/write node XperienCentral instance. The system administrator determines the ID of the plugin in the Felix GoGo shell. The system administrator executes the `wmupdate` method, specifying the ID of the plugin to update and the absolute path of the JAR file containing the updated plugin. For example: `wmupdate 59 file:/home/deploy/helloworld_1_1.jar` The plugin is updated to the new version and is set to the active state. In a clustered environment, the plugin is also automatically updated on all read-only nodes.
`wmpurge`	Removes all content that was created during and after the installation of the plugin. Usage: `wmpurge [id]` where `[id]` is the plugin identifier. A plugin must be in the active state before you can purge it.
`wmuninstall`	Removes all content that was created during the installation of the plugin. Usage: `wmuninstall [id]` where `[id]` is the plugin identifier. Notes: A plugin must be in the active state before you can uninstall it. If other plugins depend on the plugin you want to uninstall, you must first uninstall those plugins.