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

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.

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:

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.

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:

Parameter	Description
`<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

Command	Description
`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:

Command Description

wmfinduser

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

Parameter	Description
`<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.

Parameter	Description
`<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.

Parameter	Description
`<username>`	The name of the user to set to active/inactive.
`true`	The user is set to active.
`false`	The user is set to inactive.

Example

wmlockunlockuser johns false

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

Back to Top

General Commands

Parameter	Description
`lb`	This 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`
`wmloglevel`	Sets the j`ava.util.logging` level.
`wmretrieveversion`	Returns 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