The Shell Tool was introduced in XperienCentral version 10.12.0.


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


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:

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

    Do not use the "Save as Public Key" option when pasting the content of the file to the authorized_keys file.

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:


 

(click image to enlarge)


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


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

  1. The plugin developer creates a 1.1 version of a plugin and gives it to a system administrator.
  2. 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.
  3. The system administrator determines the ID of the plugin in the Felix GoGo shell.
  4. 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

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


Back to Top


Managing Website Settings from the Shell Tool

From the Shell Tool, you can modify website settings. The settings are the same ones that you can configure/modify using the XperienCentral Setup Tool. The commands below are available for doing so. The following parameters can be used in the commands:


ParameterDescription
<defname>The name of the category when there is only one website (application_settings, for example).
<entryname>The entry within the configuration set (password_banned_words, for example).
<entryvalue>The value to be assigned to the specified entry.
<hostname>The name of the host running the XperienCentral instance to retrieve/update/modify.
<index>When a configuration entry can have multiple values, this is a pointer to the value (<index=3> for example). The index count begins at 0, so to remove the first of multiple entries you would use <index=0>,<index=1> for the second value and so forth.
<setname>The name of the configuration set when multiple websites are defined. Each set has a unique name, for example, application_settings (website1), application_settings (website2) and so forth.


Website Commands


CommandDescription
wmaddconfigvalue

Adds a configuration value to an entry.

Syntax
wmaddconfigvalue <defname.setname.entryname> <entryvalue>

wmaddwebsitesettingvalue

Adds a value to the specified website setting.

Syntax
wmaddwebsitesettingvalue <hostname> <entryname> <entryvalue>

wmfindconfigvalue

Some of the parameters described for this command are only available in XperienCentral versions 10.18.0 and higher.

Returns the value(s) of the specified configuration setting.

Syntax
wmfindconfigvalue <config set definition> <entryname>

<defname> and <setname> are optional. You can use wildcards in the <entryname> parameter. Searching for "*" returns all configuration entries and their options for all channels.

Examples


wmfindconfigvalue <config set definition> <configset (wildcard)> <entryname (wildcard)>
returns entryname from configsetdefinition for all webinitiatives
wmfindconfigvalue website_settings * backend_hostname

wmfindconfigvalue <configset (wildcard)> <entryname (wildcard)>
returns entryname from given configset

wmfindconfigvalue DEFAULT backend_hostname

 
wmfindconfigvalue <entryname (wildcard)>
returns entryname from DEFAULT configset

wmfindconfigvalue backend_hostname

wmfindwebsitesettingvalue

Retrieves the value of the specified website setting.

Syntax
wmfindwebsitesettingvalue <hostname> <entryname>

wmremoveconfigvalue

Removes the specified value from the specified configuration setting.

Syntax
wmremoveconfigvalue <defname.setname.entryname> <index>

wmupdateconfigvalue

Updates the specified configuration setting with the specified value(s).

Syntax
wmupdateconfigvalue <defname.setname.entryname> <entryvalue>

If <entryvalue> is not specified, the website setting will be updated with its default value. If the website can have multiple values, use <index> to specify which entry to update. If the website setting is a checkbox, use true to select it and false to clear it.

wmupdatewebsitesettingvalue

Updates the specified website setting with the specified value.

Syntax
wmupdatewebsitesettingvalue <hostname> <entryname> <entryvalue>

If the website setting is a checkbox, use true to select it and false to clear it.



Back to Top


Managing User Passwords from the Shell Tool

From the Shell Tool you can change user passwords. The following commands are available for doing so:


CommandDescription
wmfinduser

Finds an XperienCentral user or users. This method takes the following parameters:

ParameterDescription
<hostname>The name of the host where the XperienCentral installation is running. This method will search all the hosts configured in the XperienCentral Setup Tool for the user(s), namely the hosts defined in the properties backend_hostname, backend_server_alias, frontend_hostname and frontend_server_alias.
<username>The login name of the user to find. You can use both wildcards and regular expression to widen or narrow the search.

Examples

wmfinduser gx.test.com john returns the user with the login name "John".

wmfinduser gx.test.com joh* returns all users whose login name begins with "joh" (John, Johan, and so forth).

wmfinduser gx.test.com /b[ao]*/ returns all users whose login name begins with "ba" and "bo" (Bart, Bob, and so forth).

wmsetpassword

Assigns the specified password to the specified user.

ParameterDescription
<username>The name of the user whose password will be set.
<password>The password to set for the specified user.

Example

wmsetpassword testuser Ut3&bP8

This command will return an error message if the password is not strong enough. See User Authorization for information on how XperienCentral enforces password strength.

wmlockunlockuser

This command is only available in XperienCentral versions 10.18.0 and higher.

Sets a user to an active/inactive state.

ParameterDescription
<username>The name of the user to set to active/inactive.
trueThe user is set to active.
falseThe user is set to inactive.

Example

wmlockunlockuser johns false

This command sets the user "JohnS" to an inactive state.



Back to Top


General Commands


ParameterDescription
lbThis is a standard Felix command used to find all installed bundles matching the specified substring.
wmcall

Calls the specified service (must be registered as an OSGi bundle). The possible parameters are:

  • string
  • int
  • boolean

Example
wmcall nl.gx.webmanager.services.upgrade.UpgradeService upgrade true

wmloglevelSets the java.util.logging level.
wmretrieveversionReturns the version of XperienCentral that is running.
wmtruncatetables

Truncates the specified list of XperienCentral tables. This is sometimes necessary when you copy a database from one environment to another and want to start with a clean version of it. The tables that can be truncated are:

  • wmLocalRevision
  • wmLocalFullIndexStatus
  • wmGlobalIndexEventQueue
  • ClusterLock
  • rtindex_items
  • rtindex_Revision
  • WM9_CLUSTER_JOURNAL
  • WM9_CLUSTER_LOCAL_REVISIONS

To truncate all the tables above, use allDefinedTables.



Back to Top