Table of Contents

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
  
  
• Changing Distribution Manager Configuration Settings
  
  
• Distributing Policies and QoS Configurations
  
  
• Stopping a Distribution Job
  
  
• Resuming a Stopped Distribution Job
  
  
• Restoring a Database Version
  
  
• Verifying Device Configuration
  
  
• Viewing the Configuration Commands for a Device
  
  
• Reading the Distribution Manager Logs
  
  
• Creating Policy Distribution Reports
  
  
• Deploying Distribution Jobs from an External Program
  
  
• QPM Naming Conventions
  
  

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.

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

• Changing Distribution Manager Configuration Settings
  
  
• Stopping a Distribution Job
  
  
• Resuming a Stopped Distribution Job
  
  
• Viewing the Configuration Commands for a Device
  
  
• Reading the Distribution Manager Logs
  
  
• Creating Policy Distribution Reports
  
  

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
  
  
• Reading the Distribution Manager Logs
  
  

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

• Distributing Policies and QoS Configurations
  
  
• Stopping a Distribution Job
  
  
• Reading the Distribution Manager Logs
  
  

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

• QPM Abstract Actions Translated to Device Commands
  
  
• Distributing Policies and QoS Configurations
  
  

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.

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.
  
  

Distribution Manager Log Messages

The messages can have these severities:

• Informational Messages
  
  
• Error Messages
  
  

Informational Messages

These are the informational messages in alphabetical order:

Configured successfully.

Database has been saved.

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

Distribution Manager is connected to the QoS Manager Service.

Distribution Manager is disconnected from the QoS Manager Service.

Job number cancelled by user.

Job number ended with status name.

Job number has started.

Job number was created for database name.

New database has been saved.

Policy Manager is connected to the QoS Manager Service.

Policy Manager is disconnected from the QoS Manager Service.

Error Messages

These are the error messages:

Device name is not a Cisco device.

Cannot identify policy action.

Configuration error, interface does not exist on the device.

Configuration error, missing device name.

Custom queue byte count exceeds the queue byte count limit.

Error in building the configuration.

Failed to find message ID number in message.ini.

Failed to resolve DNS in name policy.

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

Incomplete policy-name policy statement in database.

Invalid precedence value: value.

Invalid priority queue level: number.

Invalid trust value: number.

Job ID number is invalid.

Missing parameter in name policy.

No SNMP connection to device.

Out of ACL resources for name policy.

Out of custom queue-list resources.

Out of priority-list resources.

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

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

Telnet communication initialization failed: device, host.

Telnet error: device, host.

Wrong parameter in name policy at name interface.

Related Topics

• Creating Policy Distribution Reports
  
  

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.

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.

Syntax Description

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.

Examples

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

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

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

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

• Understanding QPM User Authorization
  
  
• Reading the Distribution Manager Logs
  
  
• Creating Policy Distribution Reports
  
  

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.