Managing the Collection Manager

Table Of Contents

Managing the Collection Manager

Using Utility Scripts

Configuring the CM

Activating the Servers

Controlling the Adapters

Enabling the Adapters

Controlling the Database

Dropping an SCE Connection

Configuring the Categorizer

Information About Monitoring System Health

Installing the Periodic Checker

Information About the Periodic Checker Script

Managing Users

Managing Virtual Links

How to Monitor the CM

Checking the Database Capacity

Checking the RDR Rate

Checking the SCE Connection

Verifying that the Server is Operational

Managing the Collection Manager

This module explains how to use utility scripts to view and update Collection Manager parameters.

Any machine connected to the CM via, for example, Telnet or SSH can use utility scripts to monitor and manage the CM. The utility scripts are located in the installation directory of the CM.

For information on managing the database and the CSV repository, see Managing Databases and the CSV Repository, page 5-1.

• Using Utility Scripts

• Configuring the CM

• Configuring the Categorizer

• Information About Monitoring System Health

• Managing Users

• Managing Virtual Links

• How to Monitor the CM

Using Utility Scripts

The following are general instructions for using the utility scripts:

•To invoke any script, log in as the scmscm user, except where otherwise noted. An attempt to run these scripts as the root user will result in an error.

•To display a description of the script, with an explanation of all flags and parameters, invoke the script with the help flag.

Note There is a slight variation in the help flag. Scripts for managing the CM use --help; scripts for managing the database use -h. Consult the specific script definition.

The following example shows how to display a description of the dbperiodic.py script.

>~scmscm/scripts/dbperiodic.py --helpUsage: ~scmscm/scripts/dbperiodic.py --load load configuration from /export/home/scmscm/db_maint/dbperiodic.conf ~scmscm/scripts/dbperiodic.py --loadfile=FILE load configuration from FILE ~scmscm/scripts/dbperiodic.py --dump print the current configuration in INI format to standard output ~scmscm/scripts/dbperiodic.py --help print this help message

Note Some of the scripts used to control and monitor the data-collector software use the Python scripting language. For more information about Python, go to http://www.python.org.

Configuring the CM

Use utility scripts to:

•Specify which servers are to be activated at startup

•Start or stop the database

•Start or stop an adapter

•Drop a Service Control Engine (SCE) connection

The following scripts are used to configure the CM:

•~scmscm/setup/on-boot.py

•~scmscm/scripts/adapterconf.py

•~scmscm/scripts/dbconf.sh

•~scmscm/scripts/sceconf.py

For information about scripts for managing the database and the CSV repository, see Managing Databases and the CSV Repository, page 5-1.

The following files are also used to configure the CM:

•cm.conf —General configuration of the CM, including which adapters will be turned on when the CM starts. See Enabling the Adapters.

•queue.conf —Configuration of the adapter queues, including which RDR tags will be associated with a specific adapter. See Configuring the Categorizer.

Activating the Servers

To set which servers (CM or Sybase) are activated at startup, use the on-boot.py script:

~scmscm/setup/on-boot.py--cm=flag--sybase=flag
Changes take effect the next time the system restarts.

Note Run the script with no parameters to see the current startup status of each component.

Run the following script as the scmscm to restart the Collection Manager:

~scmscm/cm/bin/cm restart
Table 4-1 on-boot.py Options --cm={ on | off} Activate/do not activate the CM at startup. --sybase={ on | off } Activate/do not activate the Sybase server at startup.

The following example shows how to set the CM and Sybase servers to be activated at startup. (This is the default setting of the script.)

>~scmscm/setup/on-boot.py --cm=on --sybase=on
Controlling the Adapters

To shut down or bring up a configured adapter, or to list the currently running CM adapters, use the adapterconf.py script:

~scmscm/scripts/adapterconf.py--op=action[--adapter=adapter name]
Table 4-2 adapterconf.py Options --op=start Bring up the adapter specified in the adapter parameter. --op=stop Shut down the adapter specified in the adapter parameter. --op=list List the currently running CM adapters. adapter=adapter name Identify the adapter to be operated on. Use only with start and stop actions. --help Display these options.

To shut down an adapter, as the scmscm user, run the following script:

~scmscm/scripts/adapterconf.py--op=stop--adapter=adapter name
To bring up an adapter, as the scmscm user, run the following script:

~scmscm/scripts/adapterconf.py--op=start--adapter=adapter name
Enabling the Adapters

An adapter can be defined to turn on when the CM starts by removing the remark character at the start of the appropriate line in the cm.conf file.

The following example defines the RAG adapter to turn on when the CM starts.

adapter.4 = com.cisco.scmscm.adapters.rag.RAGAdapter
The following example defines the CSV adapter to remain off when the CM starts.

#adapter.2 = com.cisco.scmscm.adapters.CSVAdapter

Note The value of the adapter.<number>must match the adapter_id parameter value defined in the queue.conf file for the corresponding adapter.

Controlling the Database

To shut down or start the CM database, or to show the operational status of the database, use the dbconf.sh script:

~scmscm/scripts/dbconf.sh--op=action
The script can only be used with a bundled database.

Note This script only operates when the sudo package is installed. If you did not install sudo, you must log in as the root user and run the /etc/init.d/sybase script to start or stop Sybase.

Table 4-3 dbconf.sh Options

--op=start

Start the CM database.

--op=stop

Shut down the CM database.

--op=status

Display the current operational status of the database.

To shut down the CM database, as the scmscm user, run the following command:

~scmscm/scripts/dbconf.sh--op=stop
To start the CM database, as the scmscm user, run the following command:

~scmscm/scripts/dbconf.sh--op=start
Dropping an SCE Connection

To drop a connection to a particular SCE, use the sceconf.py script:

~scmscm/scripts/sceconf.py--op=drop--ip=IP address
This script can be used only if the HTTP Adaptor of the CM is running.

This script is also used to display information about the SCE connection. (See Checking the SCE Connection )

Table 4-4 sceconf.py Options

Adapter=IP address

Drop the connection at the specified IP address.

--help

Display these options.

To drop an SCE connection, as the scmscm user, run the following command:

~scmscm/scripts/sceconf.py--op=drop--ip=IP address

Configuring the Categorizer

The Categorizer classifies each RDR according to its RDR tag. An RDR can be routed to a specific adapter by adding its RDR tag to the tags parameter (a comma-separated list of RDR tags) of the adapter. This configuration is contained in the queue.conf file.

The following example configures the RDR tags 4042321920 and 4042321922 to be sent to the Topper/Aggregator Adapter.

# Topper/Aggregator Adapter [topper-hi] adapter_id=3 priority=3 warning_size=40000 maximum_size=50000 tags=4042321920,4042321922

Note The value of the adapter_id parameter must match the adapter.<number>defined in the cm.conf file for the corresponding adapter.

Information About Monitoring System Health

The CM contains a small, expandable framework that monitors the system and issues alerts for predefined, potentially problematic conditions.

The following scripts are used to monitor the CM:

•~scmscm/setup/monitor/setup-monitor.sh

•~scmscm/setup/monitor/monitor.sh

• Installing the Periodic Checker

• Information About the Periodic Checker Script

Installing the Periodic Checker

To make (or remove) an entry for monitor.sh , the periodic checker script, in the cron (periodic scheduler) subsystem, use the setup-monitor.sh script:

~scmscm/setup/monitor/setup-monitor.sh-a flag[-i flag]
Table 4-5 setup-monitor.sh Options -a{ install| uninstall} Make/remove an entry for monitor.sh in the cron. -i{ 30m| 1h| 12h| 24h} Run monitor.sh every 30 minutes, 1 hour, 12 hours, or 24 hours.

The following example shows how to install monitor.sh so that it will run once every 30 minutes.

$ ./setup-monitor.sh -a install -i 30m
The following example shows how to uninstall monitor.sh.

$ ./setup-monitor.sh -a uninstall
Information About the Periodic Checker Script

• The Periodic Checker Script

• Tests

The Periodic Checker Script

The periodic checker script, monitor.sh , calls a series of sub-scripts that monitor different aspects of a running system:

~scmscm/setup/monitor/monitor.sh{ -a| TEST NAME} [ -v] [ -d]
The script is not intended to be run from the command line, although you can do so. Test results are sent to the syslog subsystem and are logged in the file /var/log/messages.

Table 4-6 monitor.sh Options

-a

Run all tests.

TEST NAME

The names of one or more tests. A test name is the test file name, without the leading digits and trailing .sh.

-v

Output results in verbose mode. (Log successful tests.)

-d

Print results to screen. (By default, results are sent to syslog.)

Any test that is run returns a result in the following format:

STATUS: Message
•STATUS—PASS or FAIL

•Message—A short informative status message

For example, FAIL: db "apricot" has only 1523 free blocks

The following example shows how to run all available tests and print system output to the screen.

$ ./monitor.sh -d -aTest: 01free_db.sh. Status: PASS. Message: db apricot has 1532 free blocks Test: 02cm_is_up.sh. Status: FAIL. Message: cm process is not running
The following example shows how to run a single test to check that the installed database has sufficient free space.

$ ./monitor.sh -d free_dbTest: 01free_db.sh. Status: PASS. Message: db apricot has 1532 free blocks
Tests

The following tests can be run using monitor.sh :

•db_up —Checks that the bundled Sybase database is running.

•cm_up —Checks that the CM application is running.

•free_db —Checks that the database has at least 10 percent free space.

•free_log —Check that the database transaction log has at least 70 percent free space.

•cm_persistent_buffers —Checks that each CM adapter�s persistent buffer contains less than 500 files.

The scripts for all of these tests are located in the ~/setup/monitor/tests directory.

When calling a test called test_name , the script expects to find a file called NNtest_name.sh , where NN is a number that denotes the script�s overall priority. For example, the test free_db will be mapped to the file 01free_db.sh.

Managing Users

The CM uses the p3rpc utility to manage users for authenticated RPC calls.

The command format is: p3rpc OPERATION [OPTIONS]

The following table lists the p3rpcoperations and options.

Table 4-7 p3rpc Operations

Operation

Description

--set-user--username=username--password=pas sword

Adds and updates the username and password.

--validate-password--username=username--pas sword=password

Validates the username and password.

--delete-user--username=username

Delete a user configuration.

--show-users

Displays all configured users.

Managing Virtual Links

A script is included in the CM distribution to allow you to manage virtual link names and indices that are configured for a specific SCE.

To show or set virtual links, use the update_vlinks.sh script:

~scmscm/cm/bin/update_vlinks.sh--sce=SCE IP address[ --file=file| --show]
Table 4-8 update_vlinks.sh Options --sce=SCE IP--file=file Update the VLINK_INI table with the data in the supplied csv formatted file for the specified SCE. --sce=SCE IP--show Query the VLINK_INI table for entries for the specified SCE. --help Display these options.

To set the virtual link details, as the scmscm user, run the following command:

~scmscm/cm/bin/update_vlinks.sh--sce=SCE IP address--file=file
The CSV file format is: link id (positive integer), link direction (0=upstream, 1=downstream), name (string).

The following validation steps are performed on the file:

•The file exists

•There are no duplicate virtual links ids for each direction

•The virtual links id is a positive value from 0 to 1024.

•The direction is either 0 (upstream) or 1 (downstream)

•There are no duplicate virtual links names or empty names for each direction

•Virtual links names can contain up to 256 characters. All printable characters with an ASCII code between 32 and 126 (inclusive) can be used; except for 34 ("), 39 ('), and 96 (`).

After the file is successfully validated, the script performs the following actions:

1. All entries containing the SCE IP address in their SCE_IP field are deleted from the VLINK_INI table

2. Two entries will be added to the VLINK_INI table in the following format:

–Timestamp, sce ip, 0, 0, "Default Virtual Link Up"

–Timestamp, sce ip, 0, 1, "Default Virtual Link Down"

3. The CSV file is parsed and each line in the CSV file will be entered as a line entry in the VLINK_INI table.

To show the virtual link details, as the scmscm user, run the following command:

~scmscm/cm/bin/update_vlinks.sh--sce=SCE IP address--show

How to Monitor the CM

You can use scripts to monitor system statistics that are relevant to the CM, such as:

•Percentage of free space in the database

•Rate of RDRs entering the CM

•SCE platform connection data

The following scripts are used to monitor the CM:

•~scmscm/scripts/dbfree.sh

•~scmscm/scripts/rdr-rate.py

•~scmscm/scripts/sceconf.py

•~scmscm/setup/alive.sh

The following scripts are used to configure the CM (see Configuring the CM ), but can also be invoked to display the relevant configuration:

•~scmscm/setup/on-boot.py

•~scmscm/scripts/adapterconf.py

•~scmscm/scripts/dbconf.sh

Checking the Database Capacity

To display the percentage of free space in the database report tables and the associated transaction log, use the dbfree.sh script:

~scmscm/scripts/dbfree.sh
The script can be used only with a bundled database.

DETAILED STEPS

Step 1 As the scmscm user, run the dbfree.shscript

Checking the RDR Rate

To display the momentary total rate of reports entering the CM, use the rdr-rate.py script

~scmscm/scripts/rdr-rate.py
The output is a single floating-point number representing the total rate per second of incoming RDRs (from all sources) that have entered the CM in the past 5 seconds.

This script can be used only if the HTTP Adaptor of the CM is running.

DETAILED STEPS

Step 1 As the scmscm user run the rdr-rate.pyscript

Checking the SCE Connection

To display information about the SCE connections, use the sceconf.py script:

~scmscm/scripts/sceconf.py --op=list
This script can be used only if the HTTP Adaptor of the CM is running.

The script is also used to drop a connection from a particular SCE. See Dropping an SCE Connection.

DETAILED STEPS

Step 1 As the scmscm user, run the sceconf.pyscript

~scmscm/scripts/sceconf.py --op=list
Example:

The following example shows SCE connection output:

>~scmscm/scripts/sceconf.py --op=listIP Rate Peak ------- ------- ------- 10.1.6.93 0.71798986 0.718 10.1.9.36 0.14420895 0.1442139 10.1.9.35 0.0 0.027929332 10.1.12.11 0.0 0.0
Verifying that the Server is Operational

To verify that the Server is functioning correctly, use the alive.sh script:

~scmscm/setup/alive.sh
The script verifies that the following components are operational:

•Collection Manager

•Database (in the bundled database case)

•Report tables (in the bundled database case)

If any component is down, the script issues an error message.

DETAILED STEPS

Step 1 As the scmscm user, run the alive.shscript

Note It takes time for the components to initialize after a startup; after a restart, wait five minutes before running this script.

`-a{ install\| uninstall}`	Make/remove an entry for monitor.sh in the cron.
`-i{ 30m\| 1h\| 12h\| 24h}`	Run monitor.sh every 30 minutes, 1 hour, 12 hours, or 24 hours.

`--cm={ on \| off}`	Activate/do not activate the CM at startup.
`--sybase={ on \| off }`	Activate/do not activate the Sybase server at startup.

`--op=start`	Bring up the adapter specified in the adapter parameter.
`--op=stop`	Shut down the adapter specified in the adapter parameter.
`--op=list`	List the currently running CM adapters.
`adapter=adapter name`	Identify the adapter to be operated on. Use only with start and stop actions.
`--help`	Display these options.

`--op=start`	Start the CM database.
`--op=stop`	Shut down the CM database.
`--op=status`	Display the current operational status of the database.

`Adapter=IP address`	Drop the connection at the specified IP address.
`--help`	Display these options.

`-a`	Run all tests.
`TEST NAME`	The names of one or more tests. A test name is the test file name, without the leading digits and trailing .sh.
`-v`	Output results in verbose mode. (Log successful tests.)
`-d`	Print results to screen. (By default, results are sent to syslog.)

Operation	Description
`--set-user--username=username--password=pas sword`	Adds and updates the username and password.
`--validate-password--username=username--pas sword=password`	Validates the username and password.
`--delete-user--username=username`	Delete a user configuration.
`--show-users`	Displays all configured users.

`--sce=SCE IP--file=file`	Update the VLINK_INI table with the data in the supplied csv formatted file for the specified SCE.
`--sce=SCE IP--show`	Query the VLINK_INI table for entries for the specified SCE.
`--help`	Display these options.