User Guide for Internetwork Performance Monitor 4.1(With LMS 3.1)
Chapter 10 : IPM CLI Command References

Table Of Contents

IPM CLI Command Reference-

Using IPM CLI Command

Setting CWCLIFILE Environment Variable

Running IPM

Arguments

Mandatory Arguments

Function-independent Arguments

Function-dependent Arguments

Function-specific Arguments

Input List File Format

IPM Commands

Viewing IPM CLI Help

Managing Collectors

Listing Collectors

Importing Collectors

Exporting Collector Components and Collector Statistics

Exporting Collector Components

Exporting Collector Statistics

Managing System Reports

Generating System Reports

Deleting System Reports

Adding Adhoc Devices

Deleting Devices

Baseline

Viewing IPM CLI Version


IPM CLI Command Reference-


This section describes the command line interface (CLI) commands that you can use to manage Internetwork Performance Monitor (IPM).

The commands described in this section are:

ipm -help

ipm addadhoctarget

ipm baseline

ipm deletedevice

ipm export

ipm exportstats

ipm importcollector

ipm controlcollector

ipm deletereports

ipm genreports

ipm listcollectors

ipm -v

Some IPM commands are run only by the root user while the others are run by the root user and also by members of the casusers group.

Using IPM CLI Command

In addition to using the graphical-based device configuration functions, you can use the ipm command-line utility to perform tasks on the devices, collectors, or on both.

For more details, see these topics:

Setting CWCLIFILE Environment Variable

Running IPM

Examples of ipm Commands

On all supported platforms, the files that are created by IPM are owned by casuser. They belong to the same group as the user (casuser) who created the files, and have read-write access for both casuser and the group.


Note Your login determines whether you can use this argument.


Setting CWCLIFILE Environment Variable

You can store your username and password in a file and set an environment variable CWCLIFILE which points to the file, if you want to avoid the -p argument which will reveal the password in clear text in CLI.

You should maintain this file and control access permissions to prevent unauthorized access. If CWCLIFILE is set only to filename instead of full path, IPM framework looks for the current working directory.

If you use the -p argument, even after setting the CWCLIFILE variable, the password is taken from the command line instead of CWCLIFILE. This is not secure and usage of this argument is not recommended.

The password must be provided in the file in the following format:

username password

Where username and password are the CiscoWorks login credentials. The delimiter between the username and password is a single space.

You must enter a comma as the delimiter if the password is blank. Otherwise, IPM framework cannot validate the password.

Example

To run the ipm command with the CWCLIFILE file on Windows, enter the following at the command prompt:

C:\Program Files\CSCOpx\bin>set CWCLIFILE=D:\ciscoworks\password.txt

Where the file, password.txt contains the username and password for CiscoWorks server.

Running IPM

The ipm command is located in the following directories, where install_dir is the directory in which IPM is installed:

On Solaris systems: /opt/CSCOpx/bin

On Windows systems: install_dir\CSCOpx\bin

The default install directory is C:\Program Files.

If you install IPM on Windows on an NTFS partition, only users in the administrator or casuser group can access IPM.

Users with read-write access to the CSCOpx\files\archive directory and the directories under that can also use IPM.

Examples of ipm Commands

1. ipm exportstats

ipm exportstats -u admin -p admin -m user@domain.com -coll C3_DHCP -start '2006-12-29 01:47:37.000'-end '2006-12-30 01:47:37.000' -granularity h -reportType a

Output

Successful: ipm exportstats: /var/adm/CSCOpx/files/ipm/export/statistics/AVAILABILITY_HOURLY_2006-12-29_2006-12-30_Fri_Jan_05_21:21:43_IST_2007.csv is exported Successfully

This result occurs when the collector statistics is successfully exported.

2. ipm deletedevice

ipm deletedevice -u admin -p admin -device 255.255.255.255

Output

<ipm> INFO - Done with the execution of the command.

This result occurs when the device is successfully deleted.

Arguments

Many of the arguments are common to all commands. These arguments can be broadly classified as those that are expected by every command (function independent) and those that are specific to the context of a command.

This section explains:

Mandatory Arguments

Function-independent Arguments

Function-dependent Arguments

Function-specific Arguments

Input List File Format

Mandatory Arguments

You must use the following arguments with all commands.

-u userid

Specifies the CiscoWorks username. You must define an environment variable ipm CWCLIFILE with value set to a filename, which will contain the corresponding password.

You should maintain the file. You can control the access permissions of this file to prevent unauthorized access. ipm looks for current working directory if ipm CWCLIFILE is set to only file name instead of full path.

If -u argument is used along with -p argument, the password is taken from the command line instead of ipm CWCLIFILE. This is not secure and we recommend that you do not use this argument.

The password must be provided in the file in the following format:

username password

Where username is the CiscoWorks user name given in command line. The delimiter between username and password is single blank space.

You must provide the delimiter if the password is blank. Otherwise, ipm will not validate the password. The password file can contain multiple entries with different user names. The password of the first match is considered in case of duplicate entries.

For more information, see Setting CWCLIFILE Environment Variable.

Function-independent Arguments

You can use the following arguments without any commands:

-help

When you run the -help argument, ipm displays a list of all supported commands and a one-line description of the command.

-v

When you run the -v argument, ipm displays the IPM CLI version.

Function-dependent Arguments

You can use the following arguments only with commands:

-p password

Specifies the password for the CiscoWorks username.


Warning If -p password is not used, the password is read from the command ipm CWCLIFILE. This is highly insecure and *not* recommended. See -u argument for more details. For more information, see Setting CWCLIFILE Environment Variable.


-m mailbox

Mails the results of the ipm command to the specified e-mail address.

Function-specific Arguments

You can use the following arguments only with specific commands:

-coll—Used with stop, start, delete, controlcollector functions.

-start—Used with controlcollector function.

-end—Used with exportstats function.

Example 1

ipm controlcollector -u userid -p password -start -coll collector name

Use the above command to start the stopped collectors.

Example 2

ipm exportstats -u userid -p password [-m email] [-delimiter delimiter]

[-coll collectorname] {-start starttime} {-end endtime} {-granularity d|w|m|h|min}

{-reportType a|l|j|h|i|p|r|e}

Use the above command to export collectors.

delimiter—Separates the fields in the exported file. By default, `,' is used as a delimiter, where the exported file is in .xls format.

coll—Specify the name of the collectors separated by comma.

start—Specify the Start Time of your report.

end—Specify the End Time of your report.

granularity—Specify the granularity for the report. The granularity available are min-Minute, h-Hourly, d-Daily, w-Weekly, and m-Monthly.

reportType—Specify the report type. The report types available are a-Availability, l-Latency, j-Jitter, h-HTTP, i-ICMP, p-PathEcho, r-RTP, and e-EthernetJitter.

Input List File Format

You can create Input List File Format for entering a list of arguments and its parameters.

The contents of the input list file are a sequence of lines. Each line specifies command arguments and the input parameters. The arguments must be specific to the function. You can include comments in the input list file by starting the each commented line with #.

In IPM, you can use input list file format in the following commands:

ipm export

ipm exportstats

ipm deletedevicce

ipm controlcollector

ipm addadhoctarget

ipm importcollector

Example

ipm addadhoctarget -u userid -p password -input file

input fileContains [-m email] {-device deviceip | hostname} information.

IPM Commands

The section describes the command line interface (CLI) commands that you use in Internetwork Performance Monitor (IPM).

Viewing IPM CLI Help

Managing Collectors

Listing Collectors

Importing Collectors

Exporting Collector Components and Collector Statistics

Managing System Reports

Adding Adhoc Devices

Deleting Devices

Baseline

Viewing IPM CLI Version

Viewing IPM CLI Help

This section explains how to view all the IPM CLI commands and view help for a specific command. It also explains how to list the commands and subcommands for IPM.

ipm -help

ipm <command> -help

ipm ?

Command

ipm -help

Use this command to view all the IPM CLI commands.

Syntax Description

ipm -help

help—Allows you to view the list of all IPM supported CLI commands.

Command

ipm command -help

Use this command to view help for a specific command.

Syntax Description

ipm command -help

help—Allows you to view the help for the command you have specified.

command—Specify the command.

Example

ipm controlcollector -help

controlcollector : To stop or start or delete for given collector.

Usage : ipm controlcollector -you userid -p password [-m email] {-start | -stop | -delete} {-coll collectorname} [-input argumentFile]

-you : specifies the CiscoWorks user name

-p : specifies the password for the CiscoWorks user name

-m : specifies an email address to send the results

-start : To start collector

-stop : To stop collector

-delete : To delete collector

-coll : Collector names

-input : text file containing arguments to the command

Command

ipm ?

Use this command to list the commands and subcommands for IPM.


Note You cannot use this command for Solaris as it does not accept wildcard characters (?).


Syntax Description

ipm ?

?—Lists the commands and subcommands for IPM.

Example 1

ipm ?

- addadhoctarget

- baseline

- controlcollector

- deletedevice

- deletereports

- export

- exportstats

- generatereports

- help

- importcollector

- listcollectors

This result occurs when there are commands and subcommands for IPM.

Example 2

ipm baseline ?

<ipm> - No valid commands or sub-commands found.

This results when there are no commands and subcommands for IPM baseline.

Managing Collectors

Use the following command to start, stop, or delete collectors.

Ethernet Jitter and Ethernet Ping collectors created by an Auto IP SLA collector cannot be started, stopped, or deleted individually. You need to start, stop, or delete the Auto IP SLA group collector to automatically start, stop, or delete its Ethernet Jitter and Ethernet Ping collectors.

Command

ipm controlcollector

Syntax Description

ipm controlcollector -u userid -p password [-m email] {-start | -stop | -delete} {-coll collectorname} | {-coll all -deleteAllInSource} [-input argumentFile]

start—Starts the stopped collectors.

stop—Stops the collectors in Running status.

delete—Deletes the collectors in Stopped status.

coll—Specify the collector name.

deleteAllInSource—Deletes all collectors from all the source in IPM.

input—Text file that contains arguments for the command.

Stopping Collectors

ipm controlcollector -u admin -p admin -stop -coll Coll4_Default_IPECHo

<ipm> INFO - Done with the execution of the command.

Successful: ipm controlcollector

This result occurs when the collector is stopped successfully.

Starting Collectors

ipm controlcollector -u admin -p admin -start -coll findpath_10.77.203.159_DefaultIpPathEcho

<ipm> INFO - Done with the execution of the command.

Successful: ipm controlcollector

This result occurs when the collector is started successfully.

Deleting Collectors

ipm controlcollector -u admin -p admin -delete -coll findpath_10.77.203.159_DefaultIpPathEcho

INFO - Done with the execution of the command.

Successful: ipm controlcollector

This result occurs when the collector is deleted successfully.

Deleting all Collectors from all the source in IPM

ipm controlcollector -u admin -p admin -coll all -deleteAllInSource

Successful: ipm controlcollector: - Deletion of all probes in source devices.

Listing Collectors

Use the following command to list the collectors.

Command

ipm listcollectors

Syntax Description

ipm listcollectors -u userid -p password

Example

ipm listcollectors -u admin -p admin

<ipm> INFO - Done with the execution of the command.

This result occurs when the collectors are listed successfully.

Importing Collectors

Use the following command to import collectors into IPM.

Command

ipm importcollector

Syntax Description

ipm importcollector -u userid -p password [-m email] {-file filename| -source (sourceDisplayNames|All) [-oper (operationRttTypeName|All)]} [-input argumentFile]

u—Specifies the CiscoWorks user name.

p—Specifies the password for the CiscoWorks user name.

m—Specifies an email address to send the results.

file—Contains the details of the collector to be imported.

source—Specifies one or more source display names separated by comma.

oper—Specifies one or more operation names of RttType separated by comma.

input—Text file that contains arguments for the command.


Note If you import a collector using file, only the Auto IP SLA collector is imported and not its individual Ethernet Jitter and Ethernet Ping collectors.


Example

ipm importcollector -u admin -p admin -file '/var/adm/CSCOpx/files/ipm/export/collectors/collector_Fri_Jan_05_21:31:08_IST_2007.csv'

Successful: ipm importcollector: Successfully imported the collectors.

This result occurs when the collector is imported successfully.

File format for Importing a collector using File option


Note The lines starting with ; (semicolon) are considered as comments and the examples given below are the information about each column.


;

; Here are the columns of the file.

; Columns 1, 3,5,6, 8-14 are required.

; Columns 2 and 7 are optional.

; Column 4 is not applicable for DHCP, GatekeeperRegistrationDelay,

; CallSetupPostDialDelay, EthernetPingAutoIPSLA, EthernetJitterAutoIPSLA

; Operation types and should be left empty.

; For the Operations Ethernetjitter,Ethernetping represents MEPID.

; Col# = 1: Collector Name

; Col# = 2: Description of the collector

; Col# = 3: Source dispaly name

; Col# = 4: Target display name

; Col# = 5: Operation name

; Col# = 6: Operation Type [1 - Echo, 2 - PathEcho, 9 - UDP Jitter]

; Col# = 7: Vrf Name

; Col# = 8: Source Interface Address

; Col# = 9: Collector type [1 - Historical, 2 - Realtime]

; Col# = 10: Start date (must be in MM/DD/YYYY)

; Col# = 11: End date (must be in MM/DD/YYYY)

; Col# = 12: Poll Start time (hh:mm:ss)

; Col# = 13: Poll End time (hh:mm:ss)

; Col# = 14: Days of week (must be between 1-127)

; Col# = 15: Poll Interval (must be in milliseconds)

;

; Example for Echo Collector:

; test_Echo_Collector, ,1.7.20.9,1.7.9.106-NAM2,Test_Echo_Operation,1,blue, ,1,07/29/2008,01/31/2021,00:00:00,00:00:00,127,3600000

;

; Example for DHCP Collector:

; test_DHCP_collector, ,1.7.20.9, ,Test_DHCP_Operation,11, , ,1,07/29/2008,01/31/2021,00:00:00,00:00:00,127,3600000

;

; Here are the rows of data.

;

test_Echo_Collector, ,1.7.20.9,1.7.9.106-NAM2,Test_Echo_Operation,1,blue, ,1,07/29/2008,01/31/2021,00:00:00,00:00:00,127,3600000

test_DHCP_collector, ,1.7.20.9, ,Test_DHCP_Operation,11, , ,1,07/29/2008,01/31/2021,00:00:00,00:00:00,127,3600000

If you exceed the license limit, the imported collectors are considered as real-time collectors and not as historical collectors. This applies only to collectors imported from a device and not file.


Note If you exceed the license limit, the imported collectors are considered as real-time collectors and not as historical collectors. This applies only to collectors imported from a device and not file.


Importing a collector from the source device

To import all collectors from the source devices 1.1.1.1 and 2.2.2.2 of the Operation type Echo use the following command:

ipm importcollector -u userid -p password -source 1.1.1.1,2.2.2.2 -oper Echo

This will import all the collectors from the source devices 1.1.1.1 and 2.2.2.2 of the Operation type Echo.

To import all the below given operation types, use the following command:

ipm importcollector -u userid -p password -source 1.1.1.1,2.2.2.2 -oper All

You can use any of the following operation name as input to -oper

Echo — To Import Echo Operations

PathEcho— To Import PathEcho Operations

UDPEcho— To Import UDPEcho Operations

TCPConnect— To Import TCPConnect Operations

UDPJitter— To Import UDPJitter Operations

DLSW— To Import DLSW Operations

DHCP— To Import DHCP Operations

FTP — To Import FTP Operations

VOIP— To Import GatekeeperRegistrationDelay and CallSetpuPostDialDelay Operations

RTP— To Import RTP Operations

ICMPJitter— To Import ICMPJitter Operations

EthernetPing— To Import EthernetPing Operations

EthernetPingAutoIPSLA— To Import EthernetPingAutoIPSLA Operationsns

EthernetJitter— To Import EthernetJitter Operations

EthernetJitterAutoIPSLA— To Import EthernetJitterAutoIPSLA Operations

HTTP— To Import HTTP Operations

DNS— To Import DNS Operations

For example, find below a sample report:

Total Number of Collectors Imported: 24

Total Number of Collectors Not Imported:3

Total Number of Collectors Filtered: 1

Total Number of New Adhoc devices( Target) added: 15

Table 10-1 lists the sample report details.

Table 10-1 Sample Report

Number of Collectors Imported
Number of Collectors Not Imported
Number of Collectors Filtered

24

The 24 collectors have been successfully imported.

3

The three collectors are not in the running state or are already available in IPM (duplicate).

1

The collectors are of different operational type.

(This single collector is of the operational type UDP Echo)


Exporting Collector Components and Collector Statistics

This section explains how to export collector components and collector statistics using CLI commands.

Exporting Collector Components

Exporting Collector Statistics

Exporting Collector Components

Use the following command to export IPM collectors, target devices, source devices, or operations to a CSV file. They are exported in the .xls format by default.

The exported file is stored at the following location:

Solaris

/var/adm/CSCOpx/files/ipm/export/collectors

/var/adm/CSCOpx/files/ipm/export/source

/var/adm/CSCOpx/files/ipm/export/target

/var/adm/CSCOpx/files/ipm/export/operations

Windows

<NMSROOT>/CSCOpx/files/ipm/export/collectors

<NMSROOT>/CSCOpx/files/ipm/export/source

<NMSROOT>/CSCOpx/files/ipm/export/target

<NMSROOT>/CSCOpx/files/ipm/export/operations

Command

ipm export

Syntax Description

ipm export -u userid -p password [-m email] [-delimiter delimiter] [-file filename][-coll (collectorname|all)] [-source (sourceDisplayNames|all)] [-target (targetDisplayNames|all)] [-oper (operationNames|all)] [-input argumentFile]

delimiter—Separates the fields in the exported file. By default, `,' is used as delimiter, where the exported file is in .xls format.

coll—Specify the name of the collectors separated by comma. To export all collectors, specify all.

source—Specify the source devices display name separated by comma.

target—Specify the target devices display name separated by comma.

oper—Specify the operation names separated by comma.

file—Specify a filename to export the data. This option is not applicable for exporting operations.

input—Text file that contains arguments for the command.

It is mandatory to specify at least one value for arguments collector, source, target, or operation.


Note To export all collectors, source devices, target devices, and operations, give all as the input for the argument. Example: To export all the source devices, give [-source (all)]


Examples for Exporting Collectors

This section consists of examples.

Example 1: Exporting Collectors

ipm export -u admin -p admin -coll C3_DHCP

Successful: ipm export: /var/adm/CSCOpx/files/ipm/export/collectors/collector_Fri_Jan_05_21:31:08_IST_2007.csv is exported Successfully

This result occurs when the collectors are exported successfully.


Note If you export a collector by file, only the Auto IP SLA collector is exported and not its individual Ethernet Jitter and Ethernet Ping collectors.


Example 2: Exporting Target Devices

ipm export -u admin -p admin -target 10.77.203.87

Successful: ipm export: /var/adm/CSCOpx/files/ipm/export/target/target_Fri_Jan_05_21:33:42_IST_2007.csv is exported Successfully

This result occurs when the target devices are exported successfully.

Example 3: Exporting Source Devices

ipm export -u admin -p admin -source 10.77.203.87

Successful: ipm export: /var/adm/CSCOpx/files/ipm/export/source/source_Fri_Jan_05_21:33:42_IST_2007.csv is exported Successfully

This result occurs when the source device is exported successfully.

Example 4: Exporting Operations

ipm export -u admin -p admin -operation DefaultSMTP

Successful: ipm export: /var/adm/CSCOpx/files/ipm/export/source/source_Fri_Jan_05_21:33:42_IST_2007.csv is exported Successfully

This result occurs when the operations are exported successfully.

Example 5: Exporting Collectors in .txt format

ipm export -u admin -p admin -coll C3_DHCP -delimiter '~'

Successful: ipm export: /var/adm/CSCOpx/files/ipm/export/collectors/collector_Fri_Jan_05_21:31:49_IST_2007.txt is exported Successfully

This result occurs when the collectors is exported successfully.

Exporting Collector Statistics

Use the following command to export collector statistics to a CSV file. The exported file is in .xls format by default. If you want the exported file in .txt format specify the delimiter. Example: `~'.

The exported file is stored at the following location:

Solaris: /var/adm/CSCOpx/files/ipm/export/statistics

Windows: C:/Program Files/CSCOpx/files/ipm/export/statistics

Command

ipm exportstats

Syntax Description

ipm exportstats -u userid -p password [-m email] [-delimiter delimiter] [-coll collectorname] {-start starttime} {-end endtime} {-granularity d|w|m|h|min} {-reportType a|l|j|h|i|p|r|e} [-input argumentFile]

delimiter—Separates the fields in the exported file. By default, `,' is used as delimiter, where the exported file is in .xls format.

coll—Specify the name of the collectors separated by comma.

start—Specify the Start Time of your report in this yyyy-mm-dd format.

end—Specify the End Time of your report in this yyyy-mm-dd format.


Note For more accurate report details, give the start and end in "yyyy-mm-dd hh:mm:ss" and "yyyy-mm-dd hh:mm:ss" format.


granularity—Specify the granularity for the report. The granularity available are min-Minute, h-Hourly, d-Daily, w-Weekly, and m-Monthly.

reportType—Specify the report type. The report types available are a-Availability, l-Latency, j-Jitter, h-HTTP, i-ICMP, p-PathEcho, r-RTP, and e-EthernetJitter.

input—Text file that contains arguments for the command.

Example

ipm exportstats -u admin -p admin -m user@domain.com -coll C3_DHCP -start "2006-12-29 01:47:37.000"-end "2006-12-30 01:47:37.000" -granularity h -reportType a

Successful: ipm exportstats: /var/adm/CSCOpx/files/ipm/export/statistics/AVAILABILITY_HOURLY_2006-12-29_2006-12-30_Fri_Jan_05_21:21:43_IST_2007.csv is exported Successfully

This result occurs when the collector statistics are successfully exported.

Managing System Reports

This section explains how to manage the system reports using CLI commands.

Generating System Reports

Deleting System Reports

Generating System Reports

Use the following command to generate the system reports for all report types and all granularities.

Command

ipm generatereports

Syntax Description

ipm generatereports -u userid -p password

Example

ipm generatereports -u admin -p admin

Successful: ipm generatereports: Successfully generated reports.

This result occurs when the system reports are generated successfully.

Deleting System Reports

Use the following command to delete the system reports.

Command

ipm deletereports

Syntax Description

ipm deletereports -u userid -p password {-noofdays no_of_days} [-input argumentFile]

noofdays—Specify the number of days for which you want to save the report.

input—Text file that contains arguments for the command.

Example

ipm generatereports -u admin -p admin - noofdays 4

Successful: ipm deletereports: Successfully deleted reports.

This result occurs when the system reports are deleted successfully.

Adding Adhoc Devices

Use the following command to add external target devices into IPM.

Command

ipm addadhoctarget

Syntax Description

ipm addadhoctarget -u userid -p password [-m email] {-device deviceip | hostname}[-input argumentFile]

device—Specify the display name or IP address of the device.

input—Text file that contains arguments for the command.

Example 1

ipm addadhoctarget -u admin -p admin -device abc

<ipm> INFO - Done with the execution of the command.

Successful: ipm addadhoctarget

This result occurs when the adhoc device is successfully added.

Example 2

ipm addadhoctarget -u admin -p admin -device abcd

The following target(s)already exist abcd

<ipm> INFO - Done with the execution of the command.

This result occurs when you try to add an existing adhoc target device.

Deleting Devices

Use the following command to delete the devices from IPM.

Command

ipm deletedevice

Syntax Description

ipm deletedevice -u userid -p password [-m email] {-device displayname} [-input argumentFile]

device—Specify the display name of the device.

input—Text file that contains arguments for the command.

Example 1

ipm deletedevice -u admin -p admin -device 255.255.255.255

<ipm> INFO - Done with the execution of the command.

This result occurs when the device is successfully deleted.

Example 2

ipm deletedevice -u admin -p admin -device abc

<ipm> ERROR - Device abc does not exist

This result occurs when you are not able to delete the device.

Baseline

Use the following command to modify the default Rising Threshold value for all collectors that is associated with the specified operation.

For example, if the current average latency is 100 milliseconds and you specify a baseline of 50, the new rising threshold is 150 milliseconds (50% above the current average latency), and the falling threshold is 50 ms (50% below the current average latency).

Command

ipm baseline

Syntax Description

ipm baseline -u userid -p password [-m email] {-percentage value} [-input argumentFile]

percentage—Allows you to modify the Rising Threshold value.

input—Text file that contains arguments for the command.

Example

ipm baseline -u admin -p admin -percentage 90

<ipm> INFO - Baseline value updated successfully

<ipm> INFO - Done with the execution of the command.

This result occurs when the Rising Threshold value is updated successfully.

Viewing IPM CLI Version

Use the following command to view the CiscoWorks IPM command line framework interface version.

Command

ipm -v

Syntax Description

ipm -v

v—Allows you to view the IPM CLI version details.