cc/td/doc/product/rtrmgmt/qos/qpm21
hometocprevnextglossaryfeedbacksearchhelp
PDF

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.

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.

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:

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


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:


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.


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.

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

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

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:

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.


hometocprevnextglossaryfeedbacksearchhelp
Posted: Tue Nov 12 12:21:20 PST 2002
All contents are Copyright © 1992--2002 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.