Purpose

This guide serves as a simple step-by-step procedure for configuring the Unified System CLI in a customer environment. The goal is to increase awareness of the CLI and push this serviceability tool out to as many deployments as possible. System Mode will make tasks such as setting tracing and grabbing logs significantly easier, and the “show tech-support” command will be an excellent first step to troubleshooting any problem scenario.
The Serviceability Best Practices Guide has complete details on all commands available in the System CLI once configured.

This wiki article also contains some commonly-used command examples after the two deployment options.

Deployment Options

The Unified System CLI is automatically installed on all UCCE components. Out of the box, the CLI will only connect to the local machine. This guide will walk through the minor configuration required to enter “System Mode” and access all devices in your deployment from a single System CLI console window. The CLI supports the following devices:

All UCCE servers (Routers, Loggers, PGs, ADS, etc.)

CVP

CUPS

Gateways

UCM

IP IVR

CUIC

There are two methods to configuring System Mode in the CLI. The method used will depend on whether or not the environment contains CVP OAMP, which is the preferred method for the following reasons:

All devices are centrally added to and stored in CVP OAMP. One update on OAMP will be reflected in all CLI clients.

Passwords for devices are encrypted in OAMP

CVP Remote Operations can be installed on any Windows machine, such as a personal laptop, simplifying setup and access to all devices. Note: This is not allowed in the CVP 9.0 installer due to CSCub56442 but will be addressed in a future release. In the interim, use the CVP 8.x installer for Remote Operations.

Customers without CVP can still utilize the CLI using a CSV file for connection information. See “Deployment Option 2: Devices.csv”

Deployment Option 1: System CLI Configuration with CVP OAMP

The first step for setting up System Mode is to add all of the devices in your deployment to CVP OAMP.

Log in to CVP Operations Console from a web browser and navigate to Device Management > Unified ICM.

Check the box for Enable Serviceability. Populate the Username and Password fields with login credentials for that particular device. Leave the default port 7890.

Click the Device Pool tab and associate the device with a Group if desired. (Tip: Create a “UCCE-SideA” group for all devices on the A-side!)

Click Save.

Repeat the above process for all other devices: UCCE, CUIC, UCM, Gateways, etc.

Confirm or Add a user to CVP OAMP for the System CLI

By default on installation, the user “wsmadmin” is created with the same password as the OAMP Administrator user. If you wish to modify the password for this user, or create a new user, follow these steps.

In the CVP Operations Console, click User Management > Users.

To modify the existing user, click wsmadmin in the List of Users.

To add a new user, click “Add New.”

Once the new username and password have been entered, click the “User Groups” tab and add the “ServiceabilityAdministrationUserGroup” to the “Selected” bucket on the right side.

Click Save to complete any updates or additions.

Install CVP Remote Operations

Once all devices are added to OAMP, you then need to install the CLI on the system from which you intend to access them. The CVP Installer’s “Remote Operations” package automatically includes the System CLI.

Run the CVP 8.5 Installer and select the Remote Operations checkbox.

If installing on Windows 7, ignore the “Unsupported OS” warning and click OK.

Apply Security Hardening if desired, then complete installation.

Add Remote Operations machines to CVP Operations Console

Open a web browser and log in to the CVP Operations Console. Navigate to System > Web Services. Click the “Remote Operations Deployment” tab on the subsequent screen.

Enter the IP Address and Hostname of the machine where CVP Remote Operations was just installed. Include a description if desired and click Add.

Repeat for any additional Remote Operations machines, then click “Save & Deploy” to make this device available for Remote Operations.

You will be informed that the Web Services configuration deployment is in progress. Click the “Deployment Status” button to verify the status of the newly-added machine(s). Click the “Refresh” button until the status changes to “Success.”

This should have been taken care of by the CVP Remote Operations installation but intermittently fails, so it is important to verify before attempting to connect to the CLI.

On the Remote Operations machine, click Start > Run and enter “systempropertiesadvanced”

Click “Environment Variables”

Confirm the System Variable WSC_CLI_DIR is set to “C:\Cisco\CVP\wsm\CLI”

Confirm the Path variable contains “C:\Cisco\CVP\wsm\CLI;”

Start Using the Unified System CLI with CVP OAMP

Now that the configuration is finished, we’re ready to log in to the CLI and enter System Mode

Open the Unified System CLI on the new Remote Operations machine from Start > Programs > Cisco Unified Customer Voice Portal > Unified System CLI.

Log in with user wsmadmin (or different if a new user was created).

Enter System Mode by typing “system”. Observe successful servers discovered (indicated by a ‘.’) and those that cannot be reached (indicated by “Unable to connect”).

Once initial connection is complete, (system) will be displayed in the command prompt. All commands entered while in System Mode will be run against all reachable devices defined in CVP OAMP.

Any changes made in OAMP while a CLI session is active will not be reflected immediately. There are two options for receiving the updates:

Close the console window and start a new connection.

Type “exit” to leave System Mode and then “system init”

Deployment Option 2: Devices.csv

When CVP is not present, Unified System CLI requires a devices.csv file to be configured on the local machine in order to enter System mode. This file contains connection information for all devices in the deployment that should be reachable by that single CLI window.
We will use the ADS as our main machine for running the System CLI.

Create Devices.csv from Sample file

Navigate to C:\icm\serviceability\wsccli\conf\. Make a copy of devices-sample.csv and save it as devices.csv.

Populate New devices.csv with connection information

Each device must be added on its own line at the bottom of the devices.csv file. Within each line you must specify the following required fields:

IP Address/Hostname

Device Type (from the options listed at the top of the file)

Username

Password – this is typically the deal-breaker for most customers as it will be stored in plaintext.

Port Number (leave the default 23 in most cases)

In addition, the following fields are recommended to make usage easier:

Description

Group (i.e. UCCE-SideA)

Save the devices.csv when complete. An example is below:

Designate User(s) for Diagnostic Framework

Users must be a part of the Local Group “ICMDiagnosticFrameworkUsers” in order to initially log in to the CLI when using devices.csv. To validate and add users to this group:

Start Using the Unified System CLI with Devices.csv

On the ADS, click Start > Programs > Cisco Unified CCE Tools > Unified System CLI. (If this shortcut is missing for some reason, run C:\icm\serviceability\wsccli\runwsccli.bat)

Log in with a member of the ICMDiagnosticFrameworkUsers group

If you receive an immediate “Unable to connect to localhost:7890(icm)” error, the Diagnostic Framework service may not be running. Click Start > run and enter “services.msc”. Ensure “Cisco ICM Diagnostic Framework” is started.

Once successfully logged into the local machine, enter System Mode by typing “system”. Observe successful servers discovered (indicated by a ‘.’) and those that cannot be reached (indicated by “Unable to connect”).

Once initial connection is complete, (system) will be displayed in the command prompt. All commands entered while in System Mode will be run against all reachable devices defined in devices.csv

Running the System CLI from Multiple Machines with Devices.csv

If you intend to run the System CLI on another machine, such as a second ADS, the devices.csv must be copied to that second machine. Any changes made to one devices.csv will need to be manually made on the additional machines as well.

Command Examples

Now that the System CLI is configured, let's run some commands! There is an excellent Support Forums post on using the CLI for individual servers. This wiki article will expand on that post with System Mode commands.

Enter System Mode

admin:system

Initializing system mode ...
Retrieving device list. This process may take a few minutes to complete.
.....

Command Modifiers

Once in System Mode, commands can be run against a targeted list of devices. Below are examples of setting debug level 1 with various subsets of devices. Note that these modifiers can be used for commands other than setting tracing!

Setting Tracing on a Device Component

A "component" is the equivalent of an entire service - i.e. Router A, Logger A, PG1A, etc.

Setting Tracing on a Device Component's Subcomponent

Warning: Because running this command can affect system performance,
Cisco recommends that you run the command during off-peak hours.
Do you want to continue? [y/n]: y
Retrieving [debug_level] data from device [10.10.10.30] ProductType [icm] ...
Component: icm:Peripheral Gateway 1A, subcomponent: icm:pim1
Debug level is set successfully

Setting Tracing on a Group

Group membership is defined with each device's connection information in CVP OAMP->Device Pool or devices.csv. Groups can be created with any combination of devices and device types - IOS, ICM, CVP, UCM, etc.

Collecting Logs & System Snapshot with Show tech-support

By default, the show tech-support command collects a 24-hour snapshot of ALL defined server component logs (including OPC Capture), ICM config, dumpcfg, versions, registries, OS info, PerfMon, debug levels, etc. To adjust this command to capture more or less than 24 hours, use the "absdatetime" parameter.

Troubleshooting

Environment Variables

Depending on the Deployment Type used, the WSC_CLI_DIR and PATH variables on the machine running the CLI (i.e. personal laptop, ADS) must contain specific directories.

Click Start, type systempropertiesadvanced and hit Enter.

Click Environment Variables

Check the system variable WSC_CLI_DIR

If using CVP Remote Operations, this should be set to C:\Cisco\CVP\wsm\CLI

If using devices.csv, this should be set to C:\icm\serviceability\wsccli

Check the Path variable

If using CVP Remote Operations, this should be set to C:\Cisco\CVP\wsm\CLI

If using devices.csv, C:\icm\serviceability\wsccli; should be included in the full string of the Path variable. Ensure C:\Cisco\CVP\wsm\CLI; is NOT present.

Unable to Access IOS Devices

Note that OAMP requires telnet access to the voice gateways in order for the IOS-specific System CLI commands to work. If telnet access to network devices is restricted, the CLI may not work properly for IOS devices.