Using QoS Policy Manager 2.1
Distributing Policies to Network Devices

Table of Contents

Distributing Policies to Network Devices

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:

Understanding Policy Distribution

You use the Distribution Manager to distribute the device configurations and QoS policies in a database to the network. Each distribution event is called a "job." QPM translates your policies into device commands and enters the commands through the device's command line interface (CLI). Some policies require the creation of access control lists (ACLs), others do not.

Through QPM, you can inspect the commands that will be used to configure the devices. During policy distribution, you can view device log messages as QPM configures each device, so that you can identify configuration successes and failures.

You can configure up to three ACL ranges for the ACLs created by QPM. You can also configure the Distribution Manager to distribute a job to output files (for IOS devices) as well as to the network devices. For details about Distribution Manager configuration options, see Changing Distribution Manager Configuration Settings.

You can restore a previous version of a specific database that was distributed to the network, and then edit it and redistribute it. For details, see Restoring a Database Version.

You can verify the device configuration to check whether the policies configured on the devices are consistent with the policies defined in your QoS database. For details, see Verifying Device Configuration.

Changing Distribution Manager Configuration Settings

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

  • For IOS devices (including Catalyst 6000 with Supervisor IOS), you can choose the output of the deployment process—via Telnet, to configuration files, or both.

The output files are located in the Versions folder in the QoS Policy Manager file structure. The configuration and log files for each job are located in a separate subfolder identified by the job number. The output file for each IOS device is identified by the device name.

The output files can be deployed to the devices via TFTP or any other application that downloads configuration files to the devices.

  • You can configure up to three ACL ranges for the ACLs created by QPM. This lets you control your ACL numbering and use your specific numbering convention. The ACL range is defined globally for all QoS databases in your system.

  • You can configure global control settings, which apply to all jobs. Some of these settings can be overwritten on a per device basis.

Procedure

Step 1   In the Distribution Manager, select Devices>Options.

Distribution Manager opens the Options dialog box.

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


Distributing Policies and QoS Configurations

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

The Apply command distributes the QoS configuration only to those devices in the selected job for which the configuration has changed. The Apply to All command distributes the QoS configuration to all the devices of the selected job, regardless of their status (Not-Applied, Unchanged, and so on). The status of each device is changed to Not-Applied, and then the deployment process starts.

The Apply command applies (distributes) the first valid Not-Applied job in the tree view to the network, if there is one. If there is no valid Not-Applied job, QPM asks you to select the database from which to create the job, and then applies the job without allowing you to inspect the job contents. The job contains the configuration commands required to deploy your QoS policies and settings to the network.

The Apply to All command generates an apply process to all the devices of the selected job, regardless of their status (Not-Applied, Unchanged, and so on). The status of each device is changed to Not-Applied, and then the deployment process starts. Because the deployment is incremental, if nothing has been changed on the device and the database has not been changed, no configuration will be deployed.


Note   You can also deploy output to a file. See Changing Distribution Manager Configuration Settings for more details.

Before You Begin

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

Procedure

Step 1   In the Distribution Manager, select Devices>Create Job to create a job from the QoS database.

Distribution Manager opens the Create Job dialog box.

Step 2   In the Create Job dialog box, 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. The job contains the configuration commands required to deploy your QoS policies and settings to the network.

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   Distribute the job:


  • To apply the job to devices where the configuration has changed, click the Apply button, or select Devices>Apply, to start the job.

  • To apply the job to all devices, click the Apply to All button, or select Devices>Apply to All, 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.



Table 8-1: Distribution Manager Job and Device Statuses
List Item Status Description

Job

Canceled

You created a new job before applying the existing job.

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-Progress

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-Progress

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.



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 progress.

Related Topics

Stopping a Distribution Job

You can stop the distribution of the job that is currently running.

Procedure

Step 1  
In the Distribution Manager, click the Stop button or select Devices>Stop.

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


Related Topics

Resuming a Stopped Distribution Job

You can resume the distribution of the last job that you stopped.

Procedure

Step 1  
In the Distribution Manager, 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.


Related Topics

Restoring a Database Version

You can restore a previous version of a specific database that was distributed to the network. You can edit the restored database and then redistribute it, or you can restore and redistribute the database in a single operation. This feature is very useful when unexpected errors occur as a result of the deployment of a database and there is an immediate need to go back to a previous version of that database.

Before You Begin

Ensure that you have enabled the Restore to Current option in the Distribution Manager Options dialog. See Table C-2 for more details of this setting.

Procedure

Step 1   In the Distribution Manager, select the job you want to restore to the current database version.

Step 2  
To restore the database without applying, click the Restore to Current button, or select Devices>Restore to Current.

Step 3  
To restore the database and apply, click the Restore to Current And Apply button, or select Devices>Restore to Current And Apply.


Note   If a job has not been created for the latest version of the database you want to restore, QPM first creates a job for that version, and then begins the restore process.


Verifying Device Configuration

You can verify the device configuration to check whether the policies configured on the devices are consistent with the policies defined in your QoS database. If CLI changes are made on the device after deployment, there might be a mismatch between the database and the device configuration. During verification a DNS resolution check is done for all DNS names that are defined in the policy filter definition.

Verification is carried out on the last job that was created. The verification process contains two steps: DNS resolution check, and device configuration check.

Procedure

Step 1  
In the Distribution Manager, click the Verify Device Configuration button, or select Devices>Verify Device Configuration.

QPM verifies the configuration on each device in the database, and displays the verification status, Matched or Mismatched.

You can verify a job before creating it by selecting Devices>Verify Device Configuration when there are no valid Not-Applied jobs in the tree view. Devices>Verify Device Configuration always verifies 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 verifies the newly created job.


Viewing the Configuration Commands for a Device

You can view the device commands that Distribution Manager will use to configure the devices before and after 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 a job and then, in the list pane, select the device for which you want to see the device configuration commands.

Step 2   Select Device>View Commands.

Distribution Manager opens the View Commands dialog box 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 dialog box:

  • 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 dialog box. 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>Search 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.

Related Topics

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-2: 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.



Audit Trail of User Logon

Distribution Manager maintains an audit trail of user logon for security purposes, enabling the Network Manager to keep track of who made configuration changes.

  • The Job Log in the Distribution Manager displays for each job, the user that last saved the current database, as well as the user that last deployed the job (see Database Creator and Job Handler in Figure 8-1).

  • The System Log in the Distribution Manager displays the time and user, each time a database is save.


Figure 8-1: Distribution Manager Audit Trail of User Logon


Distribution Manager Log Messages

The messages can have these severities:

Informational Messages

These are the informational messages in alphabetical order:

Configured successfully.

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

Database has been saved.

Explanation   The database was saved in Policy Manager.

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 QPM 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 that the device is online and reachable and have QPM verify the device information.

Distribution Manager is connected to the QoS Manager Service.

Explanation   Distribution Manager is communicating with the QoS Manager service.

Distribution Manager is disconnected from the QoS Manager Service.

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

Job number cancelled by user.

Explanation   You cancelled the indicated job.

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.

Job number has started.

Explanation   The indicated job is now running.

Job number was created for database name.

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

New database has been saved.

Explanation   A new database was saved in Policy Manager.

Policy Manager is connected to the QoS Manager Service.

Explanation   Policy Manager is communicating with the QoS Manager service.

Policy Manager is disconnected from the QoS Manager Service.

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

Error Messages

These are the error messages:

Device name is not a Cisco device.

Explanation   QPM does not support the indicated device.

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

Cannot identify policy action.

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

Action Report this error to Cisco technical support.

Configuration error, interface does not exist on the device.

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

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

Configuration error, missing device name.

Explanation   The device name was missing while building the configuration.

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

Custom queue byte count exceeds the queue byte count limit.

Explanation   The specified byte size of the custom queue exceeds the maximum supported limit.

Action Use Policy Manager to specify a reduced byte count.

Error in building the configuration.

Explanation   The system was unable to build the configuration.

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.

Failed to find message ID number in message.ini.

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

Action Report this error to Cisco technical support.

Failed to resolve DNS in name policy.

Explanation   There is a problem with the DNS resolving host names to their IP addresses.

Action If there is a problem with the DNS server, try again later. If the URL that you specified does not exist, you should provide a valid URL.

Frame-Relay Traffic Shaping configuration in interface name requires a rate value.

Explanation   A rate value was not specified during FRTS configuration.

Action Use Policy Manager to specify a rate value less than or equal to the interface rate.

Incomplete policy-name policy statement in database.

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

Action Use Policy Manager to correct the policy.

Invalid precedence value: value.

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

Action Report this error to Cisco technical support.

Invalid priority queue level: number.

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

Action Report this error to Cisco technical support.

Invalid trust value: number.

Explanation   The configured trust value for the interface is invalid.

Action Use Policy Manager to reconfigure the trust value.

Job ID number is invalid.

Explanation   There is no job with the indicated ID number.

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

Missing parameter in name policy.

Explanation   The indicated policy is missing one or more parameters.

Action Use Policy Manager to correct the policy.

No SNMP connection to device.

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

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

Out of ACL resources for name policy.

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

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.

Out of custom queue-list resources.

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

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

Out of priority-list resources.

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

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

Port number in name policy with name protocol should be between 1-65535.

Explanation   In the NBAR Port Mapping table, the specified protocol for the specified policy has an invalid port number.

Action Use Policy Manager to specify a port number within the permitted range.

Rate parameter in name policy at name interface is higher than the interface rate.

Explanation   The target average rate for traffic that the policy covers must not exceed the interface rate.

Action Use Policy Manager to specify a rate less than or equal to the interface rate.

Telnet communication initialization failed: device, host.

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

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.

Telnet error: device, host.

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

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

Wrong parameter in name policy at name interface.

Explanation   One of the parameters for the specified interface is invalid.

Action Use Policy Manager to check the parameters defined for the interface.

Related Topics

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-3 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 commands to print or save the reports.


Table 8-3: 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 Understanding QPM User Authorization for information on authorization requirements.

-m domain-name

The Windows NT or Windows 2000 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 distribute_policy.exe should retry the job distribution if another job is running (distribute_policy.exe will not retry if there is no connection to the QoS manager, or there is no other job running).

If you specify -b without a wait time, distribute_policy.exe waits one second between attempts, and retries indefinitely while another job is running.

If you specify -b with a wait time, distribute_policy.exe retries once after the specified time interval, if another job is running. The wait time is in seconds.

-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-4 describes the codes returned when you run distribute_policy.exe. Use Distribution Manager to view logs for the jobs.


Table 8-4: distribute_policy.exe Return Codes
Return Code Description Action

0

Job created successfully.

No action required

1

Error connecting to the QoS Manager.

2

User has no privileges to apply to the system, or the password is wrong.

3

Failed to create job.

4

Failed to create job. Failed to find the database.

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.

5

Failed to create job. Failed to convert the database.

6

There is an active job in QoS Manager.

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.

7

Bad or missing argument.



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 Retry

Distribute the Edge database using the QPM_User user account with the password secret12, and retry indefinitely at 1 second intervals if another job is running. 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 Retry after Five Minutes

Distribute the Edge database using the QPM_User user account with the password secret12, and wait five minutes before retrying distribution if another job is running. 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 Retry

Distribute the Core database using the krj user account in the ENG domain with the password secret12, and retry indefinitely at 1 second intervals if another job is running. 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

Example Script

You can also run a script to execute distributions as required.

The following example is a PERL script that executes the distribute_policy command with two different databases alternately. The first database is deployed every day at 06:00, and the second database is deployed every day at 18:00. The script also demonstrates a possible use of the status code returned by the distribute_policy.

use Time::localtime;
$nextDeploy;
#get current hour to decide which database to deploy first.
$currentHour = localtime->hour();
if ($currentHour < 6){
	$nextDeploy = "Day";
}
else{
	$nextDeploy = "Night";
}
STARTLOOP:
 
	#reset the status code scalar for the current iteration.
	$? = -1;
 
	#read current hour.
	$hour = localtime->hour();
 
	if ($hour == 6 && $nextDeploy eq "day"){
		\Qdistribute_policy -d DataBase1 -u QPM_User -m HOST-MACHINE\Q;
		$nextDeploy = "Night";
	}
	elsif ($hour == 18 && $nextDeploy eq "Night"){
		\Qdistribute_policy -d DataBase2 -u QPM_User -m HOST-MACHINE\Q;
		$nextDeploy = "Day";
	}
 
	if ($? > -1){
		#Divide the returned status code by 256 because the code returned from 
external commands is multiplied by 256
		$? = $? >>8;
 
		print "return value: $?\n";
		if ($? == 0){
			print "The job was created successfully.\n";
		}
		if ($? == 1){
			print "Cannot connect to \"QoS Manager\".\n";
		}
	}
	
	sleep 1;
 
goto STARTLOOP
#End of script.			
 

You can use this script, or a similar one, to deploy one database containing policies to handle heavy traffic load on the devices during day time, and a different database containing other policies for night hours.


Note   PERL is not included with the QPM software.

Related Topics

QPM Naming Conventions

Naming conventions to configure class-map, route-map, policy-map, and frame-relay-map to the devices must be maintained as much as possible. QPM uses the following naming conventions:

  • Modular CLI Class-map default name is a concatenation of QPM_ and the interface name or device group name.

  • Modular CLI policy-map default name is a concatenation of QPM_ and the interface name or device group name.

  • Route-map and Map-class-frame-relay default names are a concatenation of QPM_ and the interface name or device group name.

If a name is already used, a counter is concatenated to the end of the name. For policies created from a device group, no duplication of resource's naming is done because the policy name and content of the policy are the same.