Distributing Policies to Network Devices

Use the Distribution Manager application to distribute policies to network devices. These sections describe the use of Distribution Manager, and other tasks associated with distribution policies:

How to Use the Distribution Manager Application

These sections describe the basics for how to use Distribution Manager:

Starting Distribution Manager

Start Distribution Manager to distribute policies and QoS settings to network devices.

Procedure

Click the Distribution Manager button on the Policy Manager tool bar or select Tools>Distribution Manager in Policy Manager.

Distribution Manager starts.

Tips

You can also start Distribution Manager by selecting Start>Programs>QoS Policy Manager>Distribution Manager. If you have not already logged into Policy Manager, you must log into Distribution Manager using a name defined in the Windows NT QPM user group (for read-write access) or guest group (for read-only access).

Understanding the Distribution Manager Interface

The Distribution Manager main window (Figure 8-1) is divided into three panes.

All Jobs Tree View—The upper left quadrant. This tree shows all jobs that you have created from QoS databases.
List View—The upper right quadrant. This pane shows the contents of the job selected in the tree view. If no job is selected, it shows the details of the jobs listed in the tree.
Log—The lower half of the main window. This pane shows logs for system, job, and device status. This pane only appears if you select View>Log.

Figure 8-1 The Distribution Manager Main Window

All Jobs Tree View

The all jobs tree view pane (Figure 8-2) shows all the jobs that you have created from QoS databases. Each job is assigned a number, which is the name of the job.

Figure 8-2 Distribution Manager All Jobs Tree View

The root of the tree shows the name of the machine that is running the QoS Manager service to which Distribution Manager is connected: localhost means that QoS Manager resides on the same machine as Distribution Manager.

When you select a job in the list, the contents of the job is displayed in the right-hand list view pane. When no job is selected, or when you select the root of the tree, the right-hand list view shows the details for all the jobs listed in the tree.

You can control the number of jobs shown in the tree with the Number of jobs to show setting in the Distribution Manager options (select Devices>Options to change these settings).

List View

The list view pane (Figure 8-3) shows the contents of the job selected in the all jobs tree view. If no job is selected in the tree, the list shows the details for all jobs listed in the tree.

Figure 8-3 Distribution Manager List View Pane, Showing Job Contents

Job summaries have these details:

Job Name—The name of the job, which is a number.
Database Name—The name of the database from which this job was created.
Total Devices—The number of devices contained in the job.
Written Devices—The number of devices whose configurations were changed when the job was applied to the network.
Date/Time—The date and time when the job was created.
Status—The status of the job. These statuses are described in Table 8-1.

Job contents have these details:

Device—The IP address of a device defined in the job.
Date/Time—The date and time the job was created.
Status—The status of the device. These statuses are described in Table 8-1.

Table 8-1 Distribution Manager Job and Device Statuses

List Item	Status	Description
Job	Canceled	You created a new job from the database from which this job was created.
	Completed	All configuration changes have been successfully made to all devices in the job.
	Failed	Changing the configuration of one or more devices in the job failed to complete successfully. Select the job in the tree view to see which device configurations failed.
	In-Process	QoS Manager is in the process of changing the configuration of devices in the job.
	Not-Applied	You have not applied the job to the network. No configuration changes have been made on any of the devices in the job.
	Stopped	You stopped the job in the middle of distribution. You can resume the job by selecting it in the tree view and selecting Devices>Resume (or by clicking the Resume button in the tool bar).
Device	Completed	All configuration changes have been successfully made on this device.
	Failed	The configuration change failed for this device. Select the device and view the device log in the log pane to determine the reason for failure.
	In-Process	QoS Manager is in the process of changing the configuration of this device.
	Not-Applied	Configuration changes have not been made to this device. Either QPM has not yet attempted to make the change, or you have not yet applied the job that contains this device.
	Unchanged	This job does not contain configuration changes for this device.
	Unknown	QPM cannot locate the device on the network. Check to ensure the device is powered on and functioning properly, and that you have entered the correct IP address for the device in the QoS database.

Log

The log pane (Figure 8-4) displays logs of event messages.

Figure 8-4 Distribution Manager Log Pane

The pane has two tabs to display three types of logs:

System Log tab—Shows the system log, which contains messages about general QPM system events.
Job or Device Log tab—Shows the job or device log, depending on what is selected in the tree or list pane.

Job logs contain messages about the events for the selected job, and are only created if you apply the job to the network.
Device logs contain messages about the events for the selected device, and are only created when QPM starts configuring the device.

Changing the Distribution Manager Display

You can change the main Distribution Manager window to display information according to your preferences. Table 8-2 lists the available commands for changing the main Distribution Manager window.

Table 8-2 Changing the Distribution Manager Main Window

If you want to...	Command	Description
Display or hide the tool bar	View>Toolbar	The tool bar is the row of short-cut buttons beneath the menu. When Toolbar is checked on the View menu, the tool bar is displayed.
Display or hide the log pane	View>Log	The log pane is the bottom half of the main window, and displays log messages for the system, selected job, or selected device. When Log is checked on the View menu, the log pane is displayed.
Display or hide the status bar	View>Status Bar	The status bar is at the bottom of the window, and displays informative messages as you use Distribution Manager. When Status Bar is checked on the View menu, the status bar is displayed.

Changing Distribution Manager Configuration Settings

You can change various Distribution Manager behaviors by setting configuration options.

Procedure

Step 1 Select Devices>Options.

Distribution Manager opens the Options window.

Step 2 Change the options as desired. Table C-2 describes the settings you can configure for Distribution Manager.

Starting Policy Manager from Distribution Manager

If Policy Manager is not running, you can start it from Distribution Manager.

Procedure

Click the Policy Manager button, or select Tools>Policy Manager.

The Policy Manager application starts.

Exiting Distribution Manager

From the Distribution Manager interface, you can close just Distribution Manager, or exit both Distribution Manager and Policy Manager.

Before You Begin

Make sure that all distribution activities are complete or have been stopped.

Procedure

To close Distribution Manager without closing Policy Manager, select File>Close.
To exit both Distribution Manager and Policy Manager, select File>Exit.

Distributing Policies and QoS Configurations to Network Devices

When you are finished creating your policies and QoS configurations in the QoS database, you can distribution those settings to network devices.

Before You Begin

Make sure that you saved your changes to the database using Policy Manager.

Procedure

Step 1 Select Devices>Create Job to create a job from the QoS database.

Distribution Manager opens the Create Job window.

Step 2 In the Create Job window, select the database whose changes you want to apply to the network and click OK.

Distribution Manager creates a job from the database and adds it to the top of the job list in the all jobs tree view pane.

Step 3 Select the job in the tree view pane. The devices defined in the job are shown in the list view to the right of the tree.

Step 4
Click the Apply button, or select Devices>Apply, to start the job.

QPM applies the configuration changes defined in the job to the devices. You can monitor the progress of the job in the list view: the device status changes as QPM configures the devices. See Table 8-1 for information about device status.

Tips

You can apply a job before creating it by selecting Devices>Apply when there are no valid Not-Applied jobs in the tree view. Devices>Apply always applies the first valid Not-Applied job, if there is one. If there is not a valid Not-Applied job, the command prompts you to choose a database from which to create the job, and then applies the newly created job without allowing you to inspect the job contents. If you want to inspect the job's contents, always create the job first (using Devices>Create Job) before applying it.
Logs are created for the job and for each device in the job.

To view the job log, select the job in the tree view and click the Job tab in the logging pane.
To view the log for a device, select the job in the tree view, then select the device in the list view, and finally click the Device tab in the logging pane.

Devices are configured serially unless you deselect the Write only one device at a time option (select Devices>Options to change option settings). If you deselect this option, QPM configures as many devices simultaneously as it can. This can reduce the time required to apply your changes. However, if you configure QPM to stop when it encounters an error during configuration, QPM only stops after completing the configuration of all devices that are in process.

Stopping a Distribution Job

You can stop a distribution job that is currently running.

Procedure

Step 1 Select the job you want to stop in the all jobs tree view pane.

Step 2
Click the Stop button or select Devices>Stop.

Distribution Manager stops the job after completing all device configurations that are in process. If all devices in the job are in the process of being configured, then the job is completed.

Resuming a Stopped Distribution Job

You can resume any distribution job that you have stopped.

Procedure

Step 1 Select the job you want to resume in the all jobs tree view.

Step 2
Click the Resume button, or select Devices>Resume.

Distribution Manager reapplies the configuration changes defined in the job to the devices. You can monitor the progress of the job in the list view; the device status changes as Distribution Manager configures the devices. See Table 8-1 for information about device status.

Viewing the Configuration Commands for a Device

You can view the device commands that Distribution Manager will use to configure the devices before applying a distribution job. Viewing the commands can help you understand the QoS device commands and their relationship to QPM fields.

Procedure

Step 1 Select the device for which you want to see the device configuration commands in the list pane.

Step 2 Select Device>View Device Commands.

Distribution Manager opens the View Commands window with the command stream that will be sent to the device if you apply the job.

You can use these commands in the View Commands window:

File>Print, to print the command stream.
File>Save, to save the command stream to a file. Saving the commands does not affect the device configuration. The configuration is only changed if you apply the job.
File>Exit, to close the window. This does not affect the device configuration or the contents of the job.
Edit>Select All, to highlight all of the text in the file.
Edit>Copy, to copy highlighted text to the Windows clipboard.
Search>Find, to search for a text string.
Search>Find Again, to search for the next occurrence of the last text string for which you searched.
Search>Incremental Search, to search for a text string as you type it. After you select this command, you return to the main window. Start typing and the cursor will move to the matching text.

Reading the Distribution Manager Logs

Distribution Manager creates logs for the QPM system, for each job that is run, and for each device that it attempts to configure. These logs are shown in the log pane. If the log pane is not visible, select View>Log.

Table 8-3 Distribution Manager Logs

Log	To view the log...	Description
System	Click the System Log tab.	The system log contains status messages for the overall QPM system operation.
Job	Select a job in the all jobs tree view and click the Job Log tab.	The job log contains messages concerning the application of configuration changes to the devices defined in the job, and the overall status of the job.
Device	Select a device in the list pane and click the Device Log tab.	The device log contains messages concerning the application of configuration changes to the selected device.

The messages can have these severities:

Informational Messages

These are the informational messages in alphabetical order:

Message Configured successfully.

Explanation The device has been successfully configured with the policy and configuration changes defined in the job.

Message Database has been saved.

Explanation The database was saved in Policy Manager.

Message The device device-ID in the database-name database was not reachable while upgrading the database.

Explanation This device was not reachable while converting the database from QPM version 1.0 to version 1.1 format. The software version, model, and interface types for the device were not verified. These properties were changed to default values in the converted database. Ensure the device is online and reachable and have QPM verify the device information.

Message Distribution Manager is connected to the QoS Manager Service.

Explanation Distribution Manager is communicating with the QoS Manager service.

Message Distribution Manager is disconnected from the QoS Manager Service.

Explanation Distribution Manager is not communicating with the QoS Manager service.

Message Job number cancelled by user.

Explanation You cancelled the indicated job.

Message Job number ended with status name.

Explanation The indicated job has ended as described by the status. See Table 8-1 for a description of job statuses.

Message Job number has started.

Explanation The indicated job is now running.

Message Job number was created for database name

Explanation The indicated job was created based on the changes in the indicated database.

Message New database has been saved.

Explanation A new database was saved in Policy Manager.

Message Policy Manager is connected to the QoS Manager Service.

Explanation Policy Manager is communicating with the QoS Manager service.

Message Policy Manager is disconnected from the QoS Manager Service.

Explanation Policy Manager is not communicating with the QoS Manager service.

Warning Messages

These are the warning messages in alphabetical order:

Message Could not detect the interface-name interface in the device-name device while converting the database-name database.

Explanation While converting the indicated database in QPM 1.0 format to a QPM 1.1 database, QPM could not detect the interface on the device, although the database indicates that it exists on the device. The interface is added to the database with its old properties.

Recommended Action Check the device to ensure that the interface still exists and is operating correctly, and have QPM redetect interfaces on the device.

Error Messages

These are the error messages in alphabetical order:

Message device name is not a Cisco device.

Explanation QPM does not support the indicated device.

Recommended Action Use Policy Manager to remove the device from the database.

Message Can not identify policy action.

Explanation The policy action is not within the range of commands for this device.

Recommended Action Report this error to Cisco technical support.

Message Configuration error, interface does not exist on the device.

Explanation The indicated interface does not exist on the specified device.

Recommended Action Use Policy Manager to remove the interface from the database.

Message Configuration error, missing device name.

Explanation The device name was missing while building the configuration.

Recommended Action Use Policy Manager to add the device's IP address or host name to the device's QPM properties.

Message Error in building the configuration.

Explanation The system was unable to build the configuration.

Recommended Action Check for other error messages and resolve the indicated problems and try again. If that does not resolve the problem, contact Cisco technical support.

Message External Distribution Error, Could not find database name

Explanation You ran distribute_policy.exe to create and run a job from the indicated database, but QPM could not find the database.

Recommended Action Change your invocation of distribute_policy.exe to use an existing database. If you are running the command from a different machine than the QoS Manager service, make sure the command specifies the correct name of the QoS Manager machine.

Message External Distribution Error, Database database-name is in version 1.0 format. Convert the database to version 1.1 format by opening it and saving it in Policy Manager.

Explanation You ran distribute_policy.exe to create and run a job using a database that is in QPM version 1.0 format. However, this program can only create and run a job from a QPM version 1.1 database.

Recommended Action Convert the database to QPM version 1.1 format by opening it in Policy Manager and then saving it. QPM automatically converts the database when opening it. Then, rerun your distribute_policy.exe job.

Message External Distribution Error, Job number is already in progress

Explanation You ran distribute_policy.exe to create and run a job, but QPM is already running a distribution job.

Recommended Action If your invocation of distribute_policy.exe is set to wait until QPM can run the job, no action is required. If you are not waiting, either your program must be able to execute the command again, or you need to run the program when QPM is not busy.

Message Failed to calculate ratio in custom queuing policy.

Explanation Distribution Manager was unable to properly calculate the ratio for the custom queuing policies.

Recommended Action Report this error to Cisco technical support.

Message Failed to find message ID number in message.ini.

Explanation The system could not find this message in the message file.

Recommended Action Report this error to Cisco technical support.

Message Incomplete policy-name policy statement in database.

Explanation Information is missing from the indicated policy in the database.

Recommended Action Use Policy Manager to correct the policy.

Message Invalid precedence value: value.

Explanation A policy contains this value, which is not an acceptable IP precedence.

Recommended Action Report this error to Cisco technical support.

Message Invalid priority queue level: number.

Explanation The priority queue number does not fit within the priority queuing range.

Recommended Action Report this error to Cisco technical support.

Message Job ID number is invalid.

Explanation There is no job with the indicated ID number.

Recommended Action Change the job number to the correct one and try again.

Message Missing parameter in name policy.

Explanation The indicated policy is missing one or more parameters.

Recommended Action Use Policy Manager to correct the policy.

Message No SNMP connection to device.

Explanation The system was unable to make an SNMP connection to the indicated device.

Recommended Action Use Policy Manager to check the SNMP community string in the device's QPM properties.

Message Out of ACL resources for name policy.

Explanation There are insufficient resources for the indicated policy on the device.

Recommended Action Check the device's ACLs to see if there are any that you can delete. If you cannot delete any ACLs, then you cannot apply additional policies to the device.

Message Out of custom queue-list resources.

Explanation There are insufficient resources for your custom queuing policies on the device.

Recommended Action Use Policy Manager to remove some of your custom queuing policies. Try to consolidate policies if possible.

Message Out of priority-list resources.

Explanation There are insufficient resources for your priority queuing policies on the device.

Recommended Action Use Policy Manager to remove some of your priority queuing policies. Try to consolidate policies if possible.

Message Telnet communication initialization failed: device, host.

Explanation Telnet could not make contact with the device or host.

Recommended Action Ensure the host is powered on and running correctly, and that the machine running the QoS Manager service is running correctly and connected to the network, and try again.

Message Telnet error: device, host.

Explanation The indicated Telnet communications error occurred. This error is returned from the Telnet program.

Recommended Action Try to resolve the error. See the documentation for Telnet for help.

Creating Policy Distribution Reports

You can create reports of policy distributions and Distribution Manager system messages. You can then print or save the reports to maintain records of system usage.

Table 8-4 lists the reports available and the commands for creating them. The reports are created in HTML and displayed in your default web browser. Use the web browser's print and save as commands to print or save the reports.

Table 8-4 Distribution Manager Reports

Report Type	Command	Description
All Jobs	Tools>Reports>All Jobs	Displays the summary information for each job, along with the device details for each job.
System Log	Tools>Reports>System Log	Displays the system log, which contains messages concerning the functioning of the Distribution Manager.
Device Log	Tools>Reports>Device Log	Displays the log of the selected device, which contains Telnet and device messages produced while the device was being configured.
Job Log	Tools>Reports>Job Log	Displays the log of the selected job, which contains Telnet and device messages produced while the job was being applied to the network.

Tips

When you create a report, it overwrites the last report you generated, if any.
If you want to save a report, you must save it to a different directory than the one it was created in, or change the file's name.
If you save a report to a different directory, you must also copy the GIF images from the original reports directory to maintain the look of the page. If you do not copy the images, you will see missing image errors when viewing the page in your web browser.

Deploying Distribution Jobs from an External Program

You can use the distribute_policy.exe program to automate distribution job creation and execution. Using distribute_policy.exe, you can create a program that runs a distribution job without you having to start Distribution Manager manually. You can then use a scheduling program to automate your distribution program.

: distribute_policy.exe
      -d database-name
      -u user-name
      -m domain-name
      [ -p password ]
      [ -b [ wait-time-sec ] ]
      [ -h host-name ]

Syntax Description

-d database-name	The name of the QoS database whose policies and QoS configurations you want to distribute to the devices.
-u user-name	A user name defined in the QPM user group. You must have read-write authority to use this command. See the "Understanding QPM User Authorization" section for information on authorization requirements.
-m domain-name	The Windows NT domain in which the user name is defined. If the user is defined locally on the machine running QoS Manager, the domain name is the name of the machine.
-p password	The password for the user name, if any.
-b [ wait-time-secs ]	Whether QoS Manager should wait until the distribution job is completed before returning control to distribute_policy.exe. If you specify -b without a wait time, distribute_policy.exe does not gain control until QoS Manager is finished with the job (whether successfully or unsuccessfully). If you specify -b with a wait time, distribute_policy.exe gains control either when QoS Manager is finished with the job or when the wait time has expired, whichever comes first. The wait time is in seconds. If you do not specify -b, distribute_policy.exe regains control immediately.
-h host-name	The name of the host where the QoS Manager service is running. This parameter is required if your programming is not running on the same machine as the QoS Manager service.

Return Codes and Logs

Table 8-5 describes the codes returned when you run distribute_policy.exe. Use Distribution Manager to view logs for the jobs.

Table 8-5 distribute_policy.exe Return Codes

Return Code	Description
1	QPM accepted the command.
0	QPM is already running a distribution job.
-1	QPM could not find the specified database.
-2	Unexpected error.

Examples

These are examples of using distribute_policy.exe to create and run a job from a QoS database.

Example 8-1 Run Job on Same Machine as QoS Manager and Wait

Distribute the Edge database using the QPM_User user account with the password secret12, and wait until QPM has finished the job. Run the command from the same machine as the QoS Manager service (machine is called QPM-Main).

distribute_policy.exe -d Edge -u QPM_User

   -m QPM-Main -p secret12 -b

Example 8-2 Run Job on Same Machine as QoS Manager and Wait Five Minutes

Distribute the Edge database using the QPM_User user account with the password secret12, and wait five minutes before having QPM return control to you. Run the command from the same machine as the QoS Manager service (machine is called QPM-Main).

distribute_policy.exe -d Edge -u QPM_User

   -m QPM-Main -p secret12 -b 300

Example 8-3 Run Job on Remote Machine and Wait

Distribute the Core database using the krj user account in the ENG domain with the password secret12, and wait until QPM has finished the job. QoS Manager runs on a machine named POLICY-PC, which is not the machine on which you are running the command.

distribute_policy.exe -d Core -u krj

   -m ENG -p secret12 -b -h POLICY-PC

Table of Contents