|
|
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:
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.
You can change various Distribution Manager behaviors by setting configuration options.
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.
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. |
Make sure that you saved your changes to the database using Policy Manager.
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.
| 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. |
You can stop the distribution of the job that is currently running.
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.
You can resume the distribution of the last job that you stopped.
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.
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.
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.
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. |
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.
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.
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.
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:
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.
| 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. |
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 messages can have these severities:
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.
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.
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.
| 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. |
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 | 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. |
Table 8-4 describes the codes returned when you run distribute_policy.exe. Use Distribution Manager to view logs for the jobs.
| 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. |
|
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
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. |
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.
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.