Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x CISCO sur FNAC.COM

 

 

Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x
 
Click the links on the left to view the individual chapters in HTML format.

Voir également d'autres Guide CISCO :

Cisco-Security-Appliance-Command-Line-ASA-5500-version-7-2

Cisco-Introduction-to-the-Security-Appliance

Cisco-ASR-9000-Series-Aggregation-Configuration-Guide-Release-4-2-x

Cisco-IOS-XR-Carrier-Grade-NAT-Configuration-Guide-for-the-Cisco-CRS-Router-Release-4-2-x

Cisco-ASR-9000-Series-Aggregation-Services-Router-Interface-and-Hardware-Component-Configuration-Guide-Release-4-2-x

Cisco-ASR-9000-Series-Aggregation-Services-Router-IP-Addresses-and-Services-Configuration-Guide-Release-4-2-x

Cisco-ASR-9000-Series-Aggregation-Services-Router-L2VPN-et-services-Ethernet-Configuration-Guide-version-4-2-x

Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA http://www.cisco.com Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883 Text Part Number: OL-26077-02THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http:// www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R) Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental. © 2012 Cisco Systems, Inc. All rights reserved.C O N T E N T S P r e f a c e Preface xiii Changes to this document xiii Obtaining Documentation and Submitting a Service Request xiii C H A P T E R 1 Modular QoS Overview 1 Information About Modular Quality of Service Overview 1 Benefits of Cisco IOS XR QoS Features 2 QoS Techniques 2 Packet Classification and Marking 2 Default Marking Behavior 3 Congestion Management 4 Congestion Avoidance 4 Differentiated Service Model for Cisco IOS XR Software 4 Access Node Control Protocol 5 Additional Cisco IOS XR QoS Supported Features 5 Modular QoS Command-Line Interface 5 Fabric QoS 5 Where to Go Next 5 Additional References 6 Related Documents 6 Standards 6 MIBs 6 RFCs 7 Technical Assistance 7 C H A P T E R 2 Configuring Access Node Control Protocol 9 Prerequisites for Configuring ANCP 10 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 iiiRestrictions for Configuring ANCP 10 Information About Configuring ANCP 10 ANCP Adjacencies 10 Neighbor Adjacency Timing 10 ANCP Messages 11 Port Mapping 11 Rate Adjustment 11 Prioritization of ANCP Traffic 12 Process Restart 12 ANCP and QoS Interaction 12 Multi Chassis Link Aggregation 12 ANCP over MC-LAG 13 How to Configure ANCP on Cisco 14 Enabling ANCP 14 Configuring ANCP Server Sender Name 15 Configuring ANCP Neighbors 16 Mapping AN Ports to VLAN Subinterfaces 18 Configuring ANCP Rate Adjustment 21 Configuration Examples for Configuring ANCP contains the following examples: 22 Configuring ANCP Server Sender Name: Example 22 Configuring ANCP Neighbors: Example 22 Mapping AN ports to VLAN Subinterfaces: Example 25 Configuring ANCP Rate Adjustment: Example 26 ANCP and QoS Interaction: Example 26 QoS Policy Inconsistency on an Interface: Example 29 ANCP Rate Change 31 Port Speed Change 32 The show qos inconsistency Command: Example 33 Additional References 34 Related Documents 34 Standards 34 MIBs 34 RFCs 35 Technical Assistance 35 Configuring Access Node Control Protocol 35 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x iv OL-26077-02 ContentsC H A P T E R 3 Configuring Modular QoS Congestion Avoidance 37 Prerequisites for Configuring Modular QoS Congestion Avoidance 38 Information About Configuring Modular QoS Congestion Avoidance 38 Random Early Detection and TCP 38 Queue-limit for WRED 38 Tail Drop and the FIFO Queue 39 Configuring Random Early Detection 39 Configuring Random Early Detection 42 Configuring Weighted Random Early Detection 44 Configuring Tail Drop 47 Additional References 51 Related Documents 51 Standards 51 MIBs 52 RFCs 52 Technical Assistance 52 C H A P T E R 4 Configuring Modular QoS Congestion Management 53 Prerequisites for Configuring QoS Congestion Management 54 Information about Configuring Congestion Management 55 Congestion Management Overview 55 Modified Deficit Round Robin 55 Low-Latency Queueing with Strict Priority Queueing 56 Configured Accounting 56 QoS for IPv6 ACLs 57 Traffic Shaping 57 Regulation of Traffic with the Shaping Mechanism 57 Traffic Policing 58 Regulation of Traffic with the Policing Mechanism 59 Single-Rate Policer 59 Two-Rate Policer 60 Committed Bursts and Excess Bursts 62 Committed Bursts 62 Committed Burst Calculation 63 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 v ContentsExcess Bursts 63 Excess Burst Calculation 63 Deciding if Packets Conform or Exceed the Committed Rate 64 Two-Rate Three-Color (2R3C) Policer 64 Hierarchical Policing 65 Multiple Action Set 65 Packet Marking Through the IP Precedence Value, IP DSCP Value, and the MPLS Experimental Value Setting 65 Policer Granularity and Shaper Granularity 66 Congestion Management Using DEI 66 How to Configure QoS Congestion Management 66 Configuring Guaranteed and Remaining Bandwidths 66 Configuring Guaranteed Bandwidth 70 Configuring Bandwidth Remaining 73 Configuring Low-Latency Queueing with Strict Priority Queueing 76 Configuring Traffic Shaping 78 Configuring Traffic Policing (Two-Rate Color-Blind) 81 Configuring Traffic Policing (2R3C) 84 Configuring Hierarchical Policing 87 Configuration Examples for configuring congestion management 89 Traffic Shaping for an Input Interface: Example 89 Traffic Policing for a Bundled Interface: Example 90 2R3C Traffic Policing: Example 90 ATM QoS: Example 92 Hierarchical Policing: Example 92 Additional References 92 Related Documents 92 Standards 92 MIBs 93 RFCs 93 Technical Assistance 93 C H A P T E R 5 Configuring Modular QoS Service Packet Classification 95 Prerequisites for Configuring Modular QoS Packet Classification 96 Information About Configuring Modular QoS Packet Classification 97 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x vi OL-26077-02 ContentsPacket Classification Overview 97 Traffic Class Elements 97 Traffic Policy Elements 98 Default Traffic Class 98 Bundle Traffic Policies 98 Shared Policy Instance 99 Policy Inheritance 99 Port Shape Policies 99 Class-based Unconditional Packet Marking Feature and Benefits 100 Specification of the CoS for a Packet with IP Precedence 101 IP Precedence Bits Used to Classify Packets 101 IP Precedence Value Settings 102 Classification Based on DEI 102 Default DEI Marking 103 IP Precedence Compared to IP DSCP Marking 103 QoS Policy Propagation Using Border Gateway Protocol 103 QoS on the Satellite System 104 Auto QoS 104 In-Place Policy Modification 106 Modifications That Can Trigger In-Place Policy Modifications 106 Modifications to QoS Policies 106 Modifications to Class Maps 106 Modifications to Access Lists Used in Class Maps 107 Recommendations for Using In-Place Policy Modification 107 Dynamic Modification of Interface Bandwidth 107 Policy States 107 How to Configure Modular QoS Packet Classification 107 Creating a Traffic Class 107 Creating a Traffic Policy 111 Attaching a Traffic Policy to an Interface 113 Attaching a Shared Policy Instance to Multiple Subinterfaces 115 Attaching a Shared Policy Instance to Bundle Interfaces or EFP Bundles 116 Configuring Class-based Unconditional Packet Marking 118 Configuring QoS Policy Propagation Using Border Gateway Protocol 123 Policy Propagation Using BGP Configuration Task List 123 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 vii ContentsOverview of Tasks 123 Defining the Route Policy 123 Applying the Route Policy to BGP 125 Configuring QPPB on the Desired Interfaces 126 QPPB scenario 127 Configuring Hierarchical Ingress Policing 127 Configuration Examples for Configuring Modular QoS Packet Classification 129 Traffic Classes Defined: Example 129 Traffic Policy Created: Example 130 Traffic Policy Attached to an Interface: Example 130 Traffic Policy Attached to Multiple Subinterfaces: Example 130 Traffic Policy Attached to a Bundle Interface: Example 131 EFP Load Balancing with Shared Policy Instance: Example 131 |Configuring a Bundle Interface: Example 131 Configuring Two Bundle EFPs with the Load Balance Options: Example 131 Default Traffic Class Configuration: Example 132 class-map match-any Command Configuration: Example 132 Class-based, Unconditional Packet Marking Examples 132 IP Precedence Marking Configuration: Example 132 IP DSCP Marking Configuration: Example 133 QoS Group Marking Configuration: Example 133 CoS Marking Configuration: Example 133 MPLS Experimental Bit Imposition Marking Configuration: Example 134 MPLS Experimental Topmost Marking Configuration: Example 134 In-Place Policy Modification: Example 134 Additional References 135 Related Documents 135 Standards 136 MIBs 136 RFCs 136 Technical Assistance 137 C H A P T E R 6 Modular QoS Deployment Scenarios 139 802.1ad DEI 140 Mark DEI Based on a Policing Action: Example 141 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x viii OL-26077-02 ContentsMark DEI Based on Incoming Fields: Example 141 Congestion Management Using DEI: Example 141 Frame Relay QoS 141 Frame Relay DLCI Classification 142 Frame Relay DE Classification 142 Frame Relay DE Marking 142 Frame Relay QoS: Example 143 IP Header Compression QoS 145 IP Header Compression QoS: Example 146 L2VPN QoS 146 Frame Relay <-> Frame Relay Over Pseudowire: Example 146 Frame Relay <-> Ethernet Over Pseudowire: Example 148 MLPPP QoS/MLFR QoS 149 Multiclass MLPPP with QoS 150 MLPPP QoS/MLFR QoS: Example 151 MPLS QoS 151 MPLS Uniform Mode 152 MPLS Pipe Mode 152 MPLS Short Pipe Mode 153 Uniform, Pipe, Short Pipe Modes: Ingress PE Example 153 Uniform Mode: Egress PE Example 154 Pipe Mode: Egress PE Example 154 Short Pipe Mode: Egress PE Example 155 QoS on Multicast VPN 156 ASR 9000 Ethernet Line Cards 156 QoS on Multicast VPN: Example 156 Unconditional Marking 157 Conditional Marking 157 SIP 700 for the ASR 9000 157 QoS on Multicast VPN: Example 157 QoS on NxDS0 Interfaces 158 One-Level Policy Applied to Main Interface: Example 158 Two-Level Policy Applied to a Subinterface: Example 158 VPLS and VPWS QoS 159 VPLS and VPWS QoS: Example 160 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 ix ContentsRelated Information 161 C H A P T E R 7 Configuring Hierarchical Modular QoS 163 How to Configure Hierarchical QoS 164 Configuring the Three-Parameter Scheduler 164 ASR 9000 Ethernet Line Cards 165 SIP 700 for the ASR 9000 167 Attaching Hierarchical Policies to Physical and Virtual Links 169 Configuring Enhanced Hierarchical Ingress Policing 171 Two-Level Hierarchical Queueing Policy: Example 173 Three-Level Hierarchical Queueing Policy: Examples 174 Three-Level Hierarchical Queueing Policy: Examples 174 SIP 700 for the ASR 9000 175 Three-Parameter Scheduler: Examples 177 Three-Parameter Scheduler: Examples 177 SIP 700 for the ASR 9000 177 Hierarchical Policing: Examples 178 Hierarchical Policing: Examples 178 SIP 700 for the ASR 9000 178 Attaching Service Policies to Physical and Virtual Links: Examples 179 Physical Link: Example 179 Virtual Link: Example 179 Enhanced Hierarchical Ingress Policing: Example 179 Verifying the Configuration of Hierarchical Policies 180 Additional References 181 Related Documents 181 Standards 181 MIBs 181 RFCs 182 Technical Assistance 182 C H A P T E R 8 Configuring Modular QoS on Link Bundles 183 Link Bundling Overview 183 Load Balancing 184 Layer 3 Load Balancing on Link Bundles 184 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x x OL-26077-02 ContentsQoS and Link Bundling 185 QoS for POS link bundling 185 Input QoS Policy setup 185 Output QoS Policy setup 185 Additional References 186 Related Documents 186 Standards 186 MIBs 187 RFCs 187 Technical Assistance 187 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 xi Contents Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x xii OL-26077-02 ContentsPreface This guide describesthe IOS XR QoS configurations. The preface for the Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guidecontains the following sections: • Changes to this document, page xiii • Obtaining Documentation and Submitting a Service Request, page xiii Changes to this document Table 1 lists the technical changes made to this document since it was first printed. Table 1: Changes to This Document Revision Date Change Summary Republished with documentation updates for Cisco IOS XR Release 4.2.1. OL-26077-02 June 2012 OL-26077-01 December 2011 Initial release of this document. Obtaining Documentation and Submitting a Service Request For information on obtaining documentation,submitting a service request, and gathering additional information, see the monthly What's New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html Subscribe to the What's New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 xiii Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x xiv OL-26077-02 Preface Obtaining Documentation and Submitting a Service RequestC H A P T E R 1 Modular QoS Overview Quality of Service (QoS) is the technique of prioritizing traffic flows and providing preferential forwarding for higher-priority packets. The fundamental reason for implementing QoS in your network is to provide betterservice for certain traffic flows. A traffic flow can be defined as a combination ofsource and destination addresses, source and destination socket numbers, and the session identifier. A traffic flow can more broadly be described as a packet moving from an incoming interface that is destined for transmission to an outgoing interface. The traffic flow must be identified, classified, and prioritized on all routers and passed along the data forwarding path throughout the network to achieve end-to-end QoS delivery. The terms traffic flow and packet are used interchangeably throughout this module. To implement QoS on a network requires the configuration of QoS features that provide better and more predictable network service by supporting bandwidth allocation, improving loss characteristics, avoiding and managing network congestion, metering network traffic, or setting traffic flow priorities across the network. This module contains overview information about modular QoS features within a service provider network. • Information About Modular Quality of Service Overview, page 1 • Where to Go Next, page 5 • Additional References, page 6 Information About Modular Quality of Service Overview Before configuring modular QoS on your network, you should understand the following concepts: • Benefits of Cisco IOS XR QoS Features • QoS Techniques • Differentiated Service Model for Cisco IOS XR Software, page QC-4 • Access Node Control Protocol, page QC-5 • Additional Cisco IOS XR QoS Supported Features, page QC-5 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 1Benefits of Cisco IOS XR QoS Features The Cisco IOS XR QoS features enable networks to control and predictably service a variety of networked applications and traffic types. Implementing Cisco IOS XR QoS in your network promotes the following benefits: • Control over resources. You have control over which resources (bandwidth, equipment, wide-area facilities, and so on) are being used. For example, you can limit bandwidth consumed over a backbone link by FTP transfers or give priority to an important database access. • Tailored services. If you are an Internet Service Provider (ISP), the control and visibility provided by QoS enables you to offer carefully tailored grades of service differentiation to your customers. • Coexistence of mission-critical applications. Cisco IOS XR QoS features make certain of the following conditions: ? That your WAN is used efficiently by mission-critical applications that are most important to your business. ? That bandwidth and minimum delaysrequired by time-sensitive multimedia and voice applications are available. ? That other applications using the link get their fair service without interfering with mission-critical traffic. QoS Techniques QoS on Cisco IOS XR software relies on the following techniques to provide for end-to-end QoS delivery across a heterogeneous network: • Packet classification and marking • Congestion management • Congestion avoidance Before implementing the QoS features for these techniques, you should identify and evaluate the traffic characteristics of your network because not all techniques are appropriate for your network environment. Packet Classification and Marking Packet classification and marking techniques identify the traffic flow, and provide the capability to partition network traffic into multiple priority levels or classes of service. After classification is complete, any other QoS actions can be performed. Identification of a traffic flow can be performed by using several methods within a single router, such as access control lists(ACLs), protocol match, IP precedence, IP differentiated service code point (DSCP), MPLS EXP bit, or Class of Service (CoS). Marking of a traffic flow is performed by: • Setting IP Precedence or DSCP bits in the IP Type of Service (ToS) byte. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 2 OL-26077-02 Modular QoS Overview Benefits of Cisco IOS XR QoS Features• Setting CoS bits in the Layer 2 headers. • Setting EXP bits within the imposed or the topmost Multiprotocol Label Switching (MPLS) label. • Setting qos-group and discard-class bits. Marking can be carried out: • Unconditionally—As part of the class-action. • Conditionally—As part of a policer-action. • Combination of conditionally and unconditionally. For detailed conceptual and configuration information about packet marking, see the “Configuring Modular Quality of Service Packet Classification on Cisco ASR 9000 Series Routers” module in this guide for unconditional marking, and the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module in this guide for conditional marking. Default Marking Behavior When an ingress or egress interface adds VLAN tags or MPLS labels, it requires a default value for the CoS and EXP values that go into those tags and labels. The default value can be then overridden based on the policy map. The default value for CoS and EXP is based on a trusted field in the packet upon ingress to the system. The router implements an implicit trust of certain fields based on the packet type and ingress interface forwarding type (Layer 2 or Layer 3). By default, the router does not modify the IP precedence or DSCP without a policy-map being configured. The default behavior is described below. On an ingress or egress Layer 2 interface, such as xconnect or bridge-domain, the outermost CoS value is used for any field that gets added in the ingress interface. If there is a VLAN tag that gets added due to a Layer 2 rewrite, the incoming outermost CoS value is used for the new VLAN tag. If an MPLS label is added, the CoS value would be used for the EXP bits in the MPLS tag. On an ingress or egress Layer 3 interface (routed or label weighted for IPv4 or IPv6 packets), the three DSCP and precedence bits are identified in the incoming packet. For MPLS packets, the outermost label’s EXP bit is identified, and this value is used for any new field that gets added at the ingress interface. If an MPLS label is added, then the identified precedence, DSCP, or MPLS EXP value is used for the EXP bits in the newly added MPLS tag. Provider Backbone Bridge (PBB) Configuration In a PBB configuration, when a packet goes from a customer network to a service provider network using PBB encapsulation, the class of service (CoS) and discard eligibility indicator (DEI) used in the backbone VLAN tag (B-tag) and service instance tag (I-tag) of the PBB header is by default the CoS and DEI in the topmost tag of the incoming packet. When a packet goes from a service provider to a customer network, the PBB header is removed and the I-tag CoS and DEI is used by default on any tags that are imposed on the customer interface. The default marking occurs only on imposed tags, and not on existing or translated tags. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 3 Modular QoS Overview QoS TechniquesCongestion Management Congestion management techniques control congestion after it has occurred. One way that network elements handle an overflow of arriving traffic is to use a queueing algorithm to sort the traffic, then determine some servicing method of prioritizing it onto an output link. Cisco IOS XR software implements the low-latency Queueing (LLQ) feature, which brings strict priority queueing (PQ) to the Modified Deficit Round Robin (MDRR) scheduling mechanism. LLQ with strict PQ allows delay-sensitive data,such as voice, to be dequeued and sent before packetsin other queues are dequeued. Cisco IOS XR software includestraffic policing capabilities available on a per-class basis as well as class-based shaping. The traffic policing feature limitsthe input or output transmission rate of a class of traffic based on user-defined criteria, and can mark packets by setting values such as IP Precedence, QoS group, or DSCP value. Traffic shaping allows control over the traffic that leaves an interface to match its flow to the speed of the remote target interface and ensure that the traffic conforms to the policies contracted for it. Thus, traffic adhering to a particular profile can be shaped to meet downstream requirements, thereby eliminating bottlenecks in topologies with data-rate mismatches. Cisco IOS XRsoftware supports a class-based traffic shaping method through a CLI mechanism in which parameters are applied per class. For detailed conceptual and configuration information about congestion management, see the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module. Congestion Avoidance Congestion avoidance techniques monitor network traffic flowsin an effort to anticipate and avoid congestion at common network and internetwork bottlenecks before problems occur. These techniques are designed to provide preferential treatment for traffic (such as a video stream) that has been classified as real-time critical under congestion situations while concurrently maximizing network throughput and capacity utilization and minimizing packet loss and delay. Cisco IOS XR software supports the Random Early Detection (RED), Weighted RED (WRED), and tail drop QoS congestion avoidance features. For detailed conceptual and configuration information about congestion avoidance techniques, see the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module in this guide. Differentiated Service Model for Cisco IOS XR Software Cisco IOS XR software supports a differentiated service that is a multiple-service model that can satisfy different QoS requirements. However, unlike in the integrated service model, an application using differentiated service does not explicitly signal the router before sending data. For differentiated service, the network tries to deliver a particular kind of service based on the QoS specified by each packet. Thisspecification can occur in different ways, for example, using the IP Precedence bitsettings in IP packets or source and destination addresses. The network uses the QoS specification to classify, mark, shape, and police traffic, and to perform intelligent queueing. The differentiated service model is used for several mission-critical applications and for providing end-to-end QoS. Typically, this service model is appropriate for aggregate flows because it performs a relatively coarse level of traffic classification. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 4 OL-26077-02 Modular QoS Overview Differentiated Service Model for Cisco IOS XR SoftwareAccess Node Control Protocol Access Node Control Protocol (ANCP) creates a control plane between a service-oriented aggregation device and an access node (AN) (for example, a DSLAM) in order to perform QoS-related, service-related, and subscriber-related operations. An ANCP Network Access Server (NAS) accepts and maintains ANCP adjacencies (sessions with an ANCP neighbor), and sending and receiving ANCP messages. ANCP allows static mapping between AN ports and VLAN subinterfaces so that DSL rate updates for a specific subscriber received by the ANCP server are applied to the QoS configuration corresponding to that subscriber. DSL train rates received via ANCP are used to alter shaping rates on subscriber-facing interfaces and subinterfaces on the router. Additional Cisco IOS XR QoS Supported Features The following sections describe the additional features that play an important role in the implementation of QoS on Cisco IOS XR software. Modular QoS Command-Line Interface In Cisco IOS XR software, QoS features are enabled through the Modular QoS command-line interface (MQC) feature. The MQC is a command-line interface (CLI) structure that allows you to create policies and attach these policies to interfaces. A traffic policy contains a traffic class and one or more QoS features. A traffic class is used to classify traffic, whereas the QoS features in the traffic policy determine how to treat the classified traffic. One of the main goals of MQC is to provide a platform-independent interface for configuring QoS across Cisco platforms. For detailed conceptual and configuration information about the MQC feature, see the “Configuring Modular Quality of Service Packet Classification on Cisco ASR 9000 Series Routers” module in this guide. Fabric QoS There is no separate configuration for fabric QoS. The fabric priority is derived from the priority action in the ingress service policy. Where to Go Next To configure the packet classification features that involve identification and marking of traffic flows, see the “Configuring Modular Quality of Service Packet Classification on Cisco ASR 9000 Series Routers” module in this guide. To configure the queueing, scheduling, policing, and shaping features, see the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module in this guide. To configure the WRED and RED features, see the “Configuring Modular QoS Congestion Avoidance on Cisco ASR 9000 Series Routers module in this guide. To configure Access Node Control Protocol (ANCP) features, see the “Configuring Access Node Control Protocol on Cisco ASR 9000 Series Routers” module in this guide. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 5 Modular QoS Overview Access Node Control ProtocolAdditional References The following sections provide references related to implementing QoS. Related Documents Related Topic Document Title Cisco ASR 9000 Series Aggregation Services Router Getting Started Guide Initial system bootup and configuration Cisco ASR 9000 Series Aggregation Services Router Master Command Listing Master command reference Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference QoS commands “Configuring AAA Services on Cisco ASR 9000 Series Router” module of Cisco Cisco ASR 9000 Series Aggregation Services Router System Security Configuration Guide User groups and task IDs Standards Standards Title No new or modified standards are supported by — this feature, and support for existing standards has not been modified by this feature. MIBs MIBs MIBs Link To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/ cmtk/mibs.shtml CISCO-CLASS-BASED-QOS-MIB Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 6 OL-26077-02 Modular QoS Overview Additional ReferencesRFCs RFCs Title No new or modified RFCs are supported by this — feature, and support for existing RFCs has not been modified by this feature. Technical Assistance Description Link The Cisco Technical Support website contains http://www.cisco.com/techsupport thousands of pages of searchable technical content, including links to products, technologies,solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 7 Modular QoS Overview RFCs Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 8 OL-26077-02 Modular QoS Overview Technical AssistanceC H A P T E R 2 Configuring Access Node Control Protocol Access Node Control Protocol (ANCP) creates a control plane between a service-oriented aggregation device and an access node (AN) (for example, a DSLAM) in order to perform QoS-related, service-related, and subscriber-related operations. An ANCP server accepts and maintains ANCP adjacencies (sessions with an ANCP neighbor), and sending and receiving ANCP messages. ANCP allows static mapping between ANCP ports and VLAN subinterfaces so that DSL rate updates for a specific subscriber received by the ANCP server are applied to the QoS configuration corresponding to that subscriber. DSL train rates received via ANCP are used to alter shaping rates on subscriber-facing interfaces and subinterfaces on the router. ANCP runs as a single process on the route processor (RP). This module provides the conceptual and configuration information for implementing ANCP. Line Card, SIP, and SPA Support Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 Access Node Control Protocol yes no Feature History for Configuring Access Node Protocol on Cisco ASR 9000 Series Routers Release Modification Release 3.7.2 The Access Node Control Protocol feature was introduced. Release 3.9.0 Mapping of ANCP portsto VLAN interfaces over Ethernet bundles was added. Release 4.0.0 ANCP over Multi Chassis Link Aggregation was introduced. • Prerequisites for Configuring ANCP, page 10 • Restrictions for Configuring ANCP, page 10 • Information About Configuring ANCP, page 10 • How to Configure ANCP on Cisco, page 14 • Configuration Examples for Configuring ANCP contains the following examples:, page 22 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 9• Additional References, page 34 • Configuring Access Node Control Protocol, page 35 Prerequisites for Configuring ANCP Restrictions for Configuring ANCP The following restrictions apply when configuring ANCP on your network: • Only Rate Adaptive Mode is supported in Cisco IOS XR Release 3.7.2. • VPN routing and forwarding (VRF) awareness is not supported in Cisco IOS XR Release 3.7.2. All IP interfaces receiving ANCP traffic should be in default VRF. • ANCP over IPv6 is not supported for Cisco IOS XR Release 3.7.2. • Only VLAN subinterfaces over Ethernet and Ethernet bundle ports can be mapped to AN ports using ANCP. Information About Configuring ANCP To implement ANCP, you must understand the following concepts: ANCP Adjacencies The ANCP server accepts TCP connections from access nodes. An ANCP neighbor is any access node that establishes an adjacency with an ANCP server. ANCP is configured globally, and as long as it is IP-enabled, there is no restriction on whether ANCP messages are received on the physical or logical interface. TCP creates a separate connection socket for each access node. Because access nodes are not identified explicitly in ANCP messages, the TCP socket serves as the ANCP neighbor identifier for the ANCP server. Once the TCP connection between ANCP neighbors has been made, the ANCP adjacency protocol establishes an ANCP session over that connection and negotiates ANCP capabilities. There is a single ANCP session per ANCP neighbor. ANCP session information becomes a subset of the information of a corresponding neighbor. ANCP protocol supports dynamic neighbor detection so no configuration of access nodes is required. ANCP neighbors can also be statically preconfigured on the ANCP server. In such a case, access nodes are explicitly identified by their IDs, which then must match the sender-name field in the ANCP adjacency protocol messages. Neighbor Adjacency Timing The adjacency timer defines the maximum delay between different stages of ANCP session establishment and the period of ANCP keepalive. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 10 OL-26077-02 Configuring Access Node Control Protocol Prerequisites for Configuring ANCPANCP adjacency lifetime is governed by the adjacency protocol. If synchronization with the peer access node is lost (for example, if the adjacency dead timer expires), the ANCP server removes the adjacency, and the underlying TCP connection is closed. ANCP Messages Two ANCP message types are processed by the ANCP server: Port Up and Port Down. Port Up messages contain DSL rate information; Port Down messages indicate that the corresponding access line is no longer available. DSL rate updates from Port Up messages are made available to the QoS subsystem. Port Down messages are used to internally track the ANCP port state. These messages can only be received by the server after the ANCP adjacency is established. However, once a Port Up message is received, the DSL rate information it contains is considered valid indefinitely, provided AN-port-to-interface mapping is configured for that port. It is stored in the AN port database until it is overwritten by another Port Up message for this port or is cleared manually. The removal of an adjacency or the reception of a Port Down message is reflected in the database for display and troubleshooting purposes, but DSL rate information is not invalidated. Port Mapping AN ports are statically mapped to VLAN subinterfaces, referred to as AN-port-to-interface mapping. This implies that there is at least one VLAN subinterface configured per subscriber line. There is no limit to the number of interfaces that can be mapped to an AN port. VLAN subinterfaces mapped to an AN port can be created or removed. When mapping is configured, VLAN subinterfaces are referenced in the ANCP module by name. This name is used for notifications of interface creation and deletion and provides the information that is used in updating the DSL rate. An AN port database is maintained for all ports learned from Port Up messages. This database also contains the AN-port-to-interface mapping database. If a Port Up message for an AN port arrives but no interface is mapped to that port, the rate information is stored in the AN port database but not published. When a mapping for that port is configured, the AN port database is scanned to identify any ANCP messagesthat were received on this port prior to the mapping configuration. If there were, the known rate is published. Rate Adjustment ANCP can apply a correction factor to the DSL line rate reported in Port Up messages before publishing the rate update to the system. This correction factor or rate adjustment is configurable in the global configuration mode per DSL type and access encapsulation type (ATM or Ethernet). DSL type and encapsulation type are provided in mandatory type, length, and value (TLV) data in the Port Up message. To use the rate adjustment feature for non-default loop types (Ethernet), DSLAMs must support the optional Access Loop Encapsulation sub-TLV. Note ANCP rate-adaptive mode information is processed by the ANCP module to determine the maximum bandwidth (shape rate) available for a given subscriber line. A fixed correction factor is then applied to the ANCP bandwidth based on the DSL type to account for the overhead of different DSL technologies. For example, a given subscriber’s ANCP bandwidth may be 15 Mbps, but due to the DSL technology overhead, the effective Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 11 Configuring Access Node Control Protocol ANCP Messagesbandwidth for that subscriber should be limited to 80 percent of 15 Mbps, which is 12 Mbps. This corrected effective bandwidth is conveyed to QoS modules to limit the maximum rate for the subscriber’s traffic. The ANCP rate is used as a QoS shaping rate only if the ANCP rate is greater than the currently configured QoS shaping rate. (The ANCP rate used by QoS is rounded down to the nearest 128 kbps.) Note Prioritization of ANCP Traffic In case of congestion, the Cisco ASR 9000 Series Router marks ANCP messages as high priority so that the aggregation network between the Network Access Server (NAS) and the access node (AN) can prioritize the ANCP messages ahead of other traffic. Process Restart During a process restart, TCP connections with ANCP neighbors normally drop. When the ANCP server comes back, TCP connections and ANCP sessions are reestablished by the neighbors. Upon reconnecting to the server, DSLAMs send Port Up messages for every active port. Any published rate information received prior to restart is restored in the ANCP configuration. If the restart occurred due to a crash, conflicts between published data and configuration data are detected and published data is corrected. ANCP and QoS Interaction When the ANCP value is applied correctly, it overrides the configured QoS shaper value. For an example of an ANCP value applied incorrectly and an example of the interaction with QoS when the ANCP value is applied correctly, see ANCP and QoS Interaction: Example. Multi Chassis Link Aggregation Multi Chassis Link Aggregation (MC-LAG) provides a simple redundancy mechanism for a Digital Subscriber Line Access Multiplier (DSLAM) to Cisco ASR 9000 Series Router connection. The redundancy is achieved by allowing a dual-homed connection to two routers. There is no added software complexity on the DSLAM, because the DSLAMviewsthe dual-homed connection as a single LAG. The DSLAMis known as a dual-homed device (DHD), and each router is known as a point of attachment (PoA) in MC-LAG terminology. For more Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 12 OL-26077-02 Configuring Access Node Control Protocol Prioritization of ANCP Trafficdetailed information about MC-LAG, see the Cisco ASR 9000 Series Aggregation Services Router L2VPN and Ethernet Services Configuration Guide. Figure 1: MC-LAG connects DSLAM to ASR 9000 Series Routers ANCP over MC-LAG Access Node Control Protocol (ANCP) is required to support a network topology that includes MC-LAG connections to DSLAMs. CPE circuits connect to DSLAMs and adjust line speeds based on signal quality with Rate Adaptive DS. Uplinks connect DSLAMs to routers. If the line speed of a circuit adjusts to a lower data rate than the uplink, subscriber data can be lost on the DSLAM. To prevent data loss, a DSLAM notifies the router of the new DSL rate with ANCP, and downstream shaping is dynamically applied on the router such that the data rate of the uplink does not exceed the CPE circuit data rate. ANCP applies DSLAM subscriber circuit DSL rate data it learns, to MC-LAG VLAN subinterfaces that are mapped to the subscriber circuit. The rates are applied to QoS shapers. The DSL rates that ANCP has applied to the MC-LAG VLAN subinterfaces are distributed by the ANCP application running on the active PoA for the MC-LAG to the ANCP application that is running on the standby PoA for the MC-LAG, using ICCP (Inter-Chassis Communication Protocol). ANCP on the standby PoA for the MC-LAG applies the DSL rate data to the corresponding MC-LAG VLAN subinterfaces. When an event occursthat causes one of the standby PoAs to assume the active role for the MC-LAG, the ANCP application on the newly active PoA has already applied the DSL rates to shapers on the MC-LAG VLAN subinterfaces, so the correct DSL rates are applied when this LAG goes active and congestion and subsequent data loss does not occur at the DSLAM. A DSLAM establishes an ANCP adjacency with a router over a TCP connection. The DSL rates for the DSLAM subscriber circuits are communicated over this TCP connection. The DSL rates are applied to Layer Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 13 Configuring Access Node Control Protocol ANCP and QoS Interaction2 VLAN subinterfaces that are mapped to the subscriber circuits. The ANCP TCP connection that is used to send DSL rates for Layer 2 VLAN subinterfaces on an MC-LAG must be on a Layer 3 VLAN subinterface that is in the same MC-LAG as the L2VLAN subinterfaces. Note that this constraint implies that there is one ANCP TCP connection between the DSLAM and router per MC-LAG. Figure 2: ANCP over MC-LAG VLAN Subinterfaces When an active PoA for a MC-LAG becomes the standby, the DSLAM ANCP TCP connection is terminated. The DSLAM re-establishes the ANCP TCP connection with the PoA that assumes the active role for the MC-LAG. How to Configure ANCP on Cisco This section contains instructions for the following tasks: • Enabling ANCP • Configuring ANCP Server Sender Name • Configuring ANCP Neighbors • Mapping AN Ports to VLAN Subinterfaces • Configuring ANCP Rate Adjustment Enabling ANCP To enable ANCP, use the ancp command in global configuration mode. Prerequisites To use this command, you must be in a user group associated with a task group that includes the proper task IDs for ANCP. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 14 OL-26077-02 Configuring Access Node Control Protocol How to Configure ANCP on CiscoSUMMARY STEPS 1. configure RP/0/RSP0/CPU0:router# configure RP/0/RSP0/CPU0:router(config)# 2. ancp RP/0/RSP0/CPU0:router(config)# ancp 3. end 4. or commit 5. show ancp summary [statistics][detail] RP/0/RSP0/CPU0:router# show ancp summary DETAILED STEPS Command or Action Purpose configure RP/0/RSP0/CPU0:router# Enters global configuration mode. configure RP/0/RSP0/CPU0:router(config)# Step 1 Step 2 ancp RP/0/RSP0/CPU0:router(config)# ancp Enables ANCP. Step 3 end Step 4 or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-ancp)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-ancp)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays ANCP summary and general configuration information. show ancp summary [statistics][detail] RP/0/RSP0/CPU0:router# show ancp summary Step 5 Configuring ANCP Server Sender Name The ANCP server sender name is used by the ANCP server in adjacency protocol messages to DSLAMs. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 15 Configuring Access Node Control Protocol Configuring ANCP Server Sender NameSUMMARY STEPS 1. configure RP/0/RSP0/CPU0:router# configure RP/0/RSP0/CPU0:router(config)# 2. ancp server sender-name {H.H.H | A.B.C.D} RP/0/RSP0/CPU0:router(config)# ancp server sender-name 0013.1aff.c2bd 3. end 4. or commit DETAILED STEPS Command or Action Purpose configureRP/0/RSP0/CPU0:router# configure Enters global configuration mode. RP/0/RSP0/CPU0:router(config)# Step 1 ancp server sender-name {H.H.H | A.B.C.D} Configures a local sender name. RP/0/RSP0/CPU0:router(config)# ancp server sender-name 0013.1aff.c2bd Step 2 Step 3 end Step 4 or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-ancp)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-ancp)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Configuring ANCP Neighbors The TCP connection from any neighbor is accepted on any interface. To match a neighbor configuration to a respective TCP connection, ANCP neighbors are identified by a sender name that must match the corresponding field in adjacency protocol messages. Optionally, a description string can be supplied to identify the ANCP neighbor on the system and an adjacency timer interval configured. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 16 OL-26077-02 Configuring Access Node Control Protocol Configuring ANCP NeighborsSUMMARY STEPS 1. configure 2. ancp neighbor sender-name {H.H.H | A.B.C.D}[description string] 3. ancp neighbor sender-name {H.H.H | A.B.C.D} [adjacency-timer interval] 4. end or commit 5. show ancp neighbor {description description-string| sender-name {H.H.H | A.B.C.D}} [statistics][detail] RP/0/RSP0/CPU0:router# show ancp neighbor sender-name 0006.2aaa.281b 6. show ancp neighbor summary [statistics][detail] RP/0/RSP0/CPU0:router# show ancp neighbor summary 7. clear ancp neighbor {all | description description-string |sender-name {H.H.H | A.B.C.D}}[state |statistics] RP/0/RSP0/CPU0:router# clear ancp neighbor all 8. clear ancp summary [statistics | detail] RP/0/RSP0/CPU0:router# clear ancp summary statistics 9. show ancp neighbor [all] [statistics] RP/0/RSP0/CPU0:router# show ancp neighbor statistics 10. show ancp neighbor state [none | synsent | synrcvd | estab} [statistics] RP/0/RSP0/CPU0:router# show ancp neighbor none DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure RP/0/RSP0/CPU0:router(config)# Step 1 ancp neighbor sender-name {H.H.H | Sets neighbor description parameter to easily identify DSLAMs. A.B.C.D}[description string] Step 2 Example: RP/0/RSP0/CPU0:router(config)# ancp neighbor sender-name oo13.1aff.c2bd description vendorA1 Sets neighbor adjacency timer parameter. If a neighbor session is already established, it will be reset so this timer can take affect. ancp neighbor sender-name {H.H.H | A.B.C.D} [adjacency-timer interval] Example: RP/0/RSP0/CPU0:router(config)# ancp neighbor sender-name 0013.1aff.c2bd adjacency-timer 20 Step 3 Note • Configured ports are placed in a down state while unconfigured ports are released. Step 4 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-ancp)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changesfound, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-ancp)# commit Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 17 Configuring Access Node Control Protocol Configuring ANCP NeighborsCommand or Action Purpose Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changesto the running configuration file and remain within the configuration session. (Optional) Displays data or message statistics associated with individual ANCP adjacencies or sets of adjacencies. show ancp neighbor {description description-string| sender-name {H.H.H | A.B.C.D}} [statistics][detail] RP/0/RSP0/CPU0:router# show ancp neighbor sender-name 0006.2aaa.281b Step 5 show ancp neighbor summary [statistics][detail] (Optional) Displays adjacency counts by state. RP/0/RSP0/CPU0:router# show ancp neighborsummary Step 6 (Optional) Clears ANCP neighbors, either all or individually. Configured ports are placed in a down state while releasing clear ancp neighbor {all | description description-string | sender-name {H.H.H | A.B.C.D}}[state | statistics] RP/0/RSP0/CPU0:router# clear ancp neighbor all Step 7 unconfigured ports. If state is selected, the adjacency is reset without clearing the TCP socket. (Optional) Clears aggregate message statistics only, without modifying individual neighbor or port statistics. clear ancp summary [statistics | detail] RP/0/RSP0/CPU0:router# clear ancp summary statistics Step 8 show ancp neighbor [all] [statistics] (Optional) Displays ANCP neighbor information. RP/0/RSP0/CPU0:router# show ancp neighborstatistics Step 9 show ancp neighbor state [none | synsent | synrcvd | (Optional) Displays adjacency protocol state information. estab} [statistics] RP/0/RSP0/CPU0:router# show ancp neighbor none Step 10 Mapping AN Ports to VLAN Subinterfaces Port mapping associates DSLAM access ports or customer premises equipment (CPE) clients of a DSLAM with VLAN subinterfaces. The VLANs can be IEEE 802.1Q or QinQ hierarchical VLANs. To map AN ports to VLAN subinterfaces, use the ancp an-port command in global configuration mode. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 18 OL-26077-02 Configuring Access Node Control Protocol Mapping AN Ports to VLAN SubinterfacesSUMMARY STEPS 1. configure 2. ancp an-port circuit-id Access-Loop-Circuit-ID [interface type interface-path-id | interface Bundle-Ether bundle-id] RP/0/RSP0/CPU0:router(config)# ancp an-port circuit-id circuit1 interface gigabitethernet 2/0/1/1.1 3. end or commit 4. show ancp an-port {circuit-id Access-Loop-Circuit-ID | interface type interface-path-id | interface Bundle-Ether bundle-id | mapping} [statistics | detail] 5. show ancp an-port [configured | dynamic-only][statistics] 6. show ancp an-port summary [statistics][detail] 7. clear ancp an-port {all | circuit-id Access-Loop-Circuit-Id | interface type interface-path-id | interface Bundle-Ether bundle-id | neighbor {description string | sender-name {H.H.H | A.B.C.D}}[statistics] 8. show ancp an-port {description description-string | sender-name {H.H.H | A.B.C.D}} 9. show ancp an-port state [up | down | none] [statistics] DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure RP/0/RSP0/CPU0:router(config)# Step 1 Defines a unique access node ID. This ID information is included in the ANCP Port Up and Port Down messages. ancp an-port circuit-id Access-Loop-Circuit-ID [interface type interface-path-id | interface Step 2 Bundle-Ether bundle-id] The Circuit ID must be supplied before the access node port configuration can be committed. RP/0/RSP0/CPU0:router(config)# ancp an-port circuit-id circuit1 interface gigabitethernet 2/0/1/1.1 When using a shared policy instance in subinterfaces with ANCP, the same AN port circuit ID must be mapped to all subinterfaces that have the same shared policy instance. Step 3 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-ancp)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changesfound, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-ancp)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 19 Configuring Access Node Control Protocol Mapping AN Ports to VLAN SubinterfacesCommand or Action Purpose Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changesto the running configuration file and remain within the configuration session. (Optional) Displays information about the association of DSLAM access ports(or CPE clients of a DSLAM) with VLAN subinterfaces. show ancp an-port {circuit-id Access-Loop-Circuit-ID | interface type interface-path-id | interface Bundle-Ether bundle-id | mapping} [statistics | detail] Example: RP/0/RSP0/CPU0:router# show ancp an-port gigabitethernet 2/0/1/1.1 Step 4 (Optional) Displayssummary data orstatisticsfor AN portsthat are or are not mapped to interfaces. show ancp an-port [configured | dynamic-only][statistics] Example: RP/0/RSP0/CPU0:router# show ancp an-port configured Step 5 show ancp an-port summary [statistics][detail] (Optional) Displays port counts by state. Example: RP/0/RSP0/CPU0:router# show ancp an-port summary Step 6 (Optional) Clears AN ports of dynamic data or statistics either individually or in groups. Published information is cleared and information learned from the DSLAM is cleared. clear ancp an-port {all | circuit-id Access-Loop-Circuit-Id | interface type interface-path-id | interface Bundle-Ether bundle-id | neighbor {description string | sender-name {H.H.H | A.B.C.D}}[statistics] Step 7 Example: RP/0/RSP0/CPU0:router# clear ancp an-port all show ancp an-port {description description-string | (Optional) Displays AN port information. sender-name {H.H.H | A.B.C.D}} Step 8 Example: RP/0/RSP0/CPU0:router# show ancp an-port description vendor3b show ancp an-portstate [up | down | none] [statistics] (Optional) Displays AN port state information. Example: RP/0/RSP0/CPU0:router# show ancp an-port state up Step 9 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 20 OL-26077-02 Configuring Access Node Control Protocol Mapping AN Ports to VLAN SubinterfacesConfiguring ANCP Rate Adjustment Use the ancp rate-adjustment command to apply a mathematical correction to the ANCP rate update prior to applying it as a shaper rate. SUMMARY STEPS 1. configure RP/0/RSP0/CPU0:router# configure RP/0/RSP0/CPU0:router(config)# 2. ancp rate-adjustment dsl-type access-loop-type percent-factor factor 3. end or commit 4. show ancp summary detail RP/0/RSP0/CPU0:router# show ancp summary detail DETAILED STEPS Command or Action Purpose configure RP/0/RSP0/CPU0:router# Enters global configuration mode. configure RP/0/RSP0/CPU0:router(config)# Step 1 Sets the parameters for the ANCP shaper percent factor. dsl-type and access-loop-type are compared to appropriate values in optional type-length ancp rate-adjustment dsl-type access-loop-type percent-factor factor Example: RP/0/RSP0/CPU0:router(config)# ancp Step 2 values (TLVs) in the ANCP Port Up message and the ANCP rate is adjusted by a configured factor in case of a match. • dsl-type—(Required) Sets DSL type code: rate-adjustment adsl2 ethernet percent-factor 90 adsl1 adsl2 adsl2+ vdsl1 vdsl2 sdsl • access-loop-type—(Required) Sets access-loop-type to ATMor Ethernet. • percent-factor factor—(Required) A percent value to be applied to the ANCP reported rate update prior to configuring it as a shaping rate. Step 3 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changesfound, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config)# commit Entering yes saves configuration changes to the running configuration file, exitsthe configuration session, and returnsthe router to EXEC mode. Entering no exitsthe configuration session and returnsthe router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changesto the running configuration file and remain within the configuration session. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 21 Configuring Access Node Control Protocol Configuring ANCP Rate AdjustmentCommand or Action Purpose (Optional) Shows generic ANCP configuration information along with rate adjustment configuration information. show ancp summary detail RP/0/RSP0/CPU0:router# show ancp summary detail Step 4 Configuration Examples for Configuring ANCP contains the following examples: • Configuring ANCP Server Sender Name: Example • Configuring ANCP Neighbors: Example • Mapping AN ports to VLAN Subinterfaces: Example • Configuring ANCP Rate Adjustment: Example • ANCP and QoS Interaction: Example • QoS Policy Inconsistency on an Interface: Example Configuring ANCP Server Sender Name: Example Configuring ANCP Neighbors: Example The following example shows how to set ANCP neighbor parameters: configure ancp neighbor sender-name 0001.2222.3333 description VendorA-1 ancp neighbor sender-name 0001.2222.3333 adjacency-timer 20 commit The following example shows the output from a specific neighbor using the sender-name MAC address: show ancp neighbor sender-name 0006.2aaa.281b ANCP Neighbor Data ------------------------------------------- Sender Name 0006.2aaa.281b Description first State ESTAB Capability Topology Discovery Ports: State Up 25 State Down 5 Total 30 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 22 OL-26077-02 Configuring Access Node Control Protocol Configuration Examples for Configuring ANCP contains the following examples:The following example showsthe same command with the addition of the detail keyword,showing a summary of AN ports that were reported by that neighbor: show ancp neighbor sender-name 0006.2aaa.281b detail ANCP Neighbor Data ------------------------------------------- Sender Name 0006.2aaa.281b Description first State ESTAB Capability Topology Discovery Ports: State Up 4 State Down 0 Total 4 Remote IP Addr/TCP Port 209.165.200.225/11126 Local IP Addr/TCP Port 209.165.200.250/6068 Server Sender Name 0013.1aff.c2bd Remote Timeout 25500 msec Local Timeout 10000 msec Adjacency Uptime 01:25:20 Time Since Last Port Msg 00:00:04 Remote Port 0 Remote Instance 1 Local Instance 1 Remote Partition ID 0 List of AN port data for neighbor sender name 0006.2aaa.281b ------------------------------ ----- ---------- -------- ---- ------------ Line Num Adjusted DS Circuit-id State Uptime State Intf Rate (kbps) ------------------------------ ----- ---------- -------- ---- ------------ circuit1 UP 00:27:49 SHOWTIME 3 2250 circuit2 UP 00:00:49 SHOWTIME 2 2250 circuit3 UP 00:00:49 SHOWTIME 2 2250 circuit4 UP 00:00:49 SHOWTIME 0 2250 The following example shows the same command, this time with the addition of the statistics keyword, showing a summary of message statistics for the selected neighbor: show ancp neighbor sender-name 0006.2aaa.281b statistics ANCP Neighbor Message Statistics for Sender-name -, Description 0006.2aaa.281b ----------------------------------------------- Sent Received SYN 1 2 SNYACK 1 0 ACK 589 238 RSTACK 0 0 Port Up - 10 Port Down - 0 Drops 0 0 Total 600 250 The following example shows how to display generic information about ANCP configuration, along with neighbor and port counts by state: show ancp summary ANCP Summary Information ---------------------------------------------- Capability: Topology Discovery Server sender-name: 0013:1aff.c2bd Neighbor count by state: - 0 SYNSENT 0 SUNRCVD 0 ESTAB 1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 23 Configuring Access Node Control Protocol Configuring ANCP Neighbors: Example---------------------------------- Total 1 Port count by state: State Up 1 State Down 0 State Unknown 0 ---------------------------------- Total 1 No. configured ports 1 No. mapped sub-interfaces 4 The following example shows how to display rate adjustment configuration information in addition to the generic information shown in the previous example: show ancp summary detail ANCP Summary Information ---------------------------------------------- Capability: Topology Discovery Server sender-name: 0013:1aff.c2bd Neighbor count by state: - 0 SYNSENT 0 SUNRCVD 0 ESTAB 1 ---------------------------------- Total 1 Port count by state: State Up 1 State Down 0 State Unknown 0 ---------------------------------- Total 1 No. configured ports 1 No. mapped sub-interfaces 4 Rate adjustment configuration: ------------------------------------------- DSL Type Loop Type Percent-Factor ------------------------------------------- ADSL1 ETHERNET 90 ADSL2 ETHERNET 100 ADSL2PLUS ETHERNET 100 VDSL1 ETHERNET 100 VDSL2 ETHERNET 100 SDSL ETHERNET 100 ADSL1 ATM 100 ADSL2 ATM 100 ADSL2PLUS ATM 100 VDSL1 ATM 100 VDSL2 ATM 100 SDSL ATM 100 The following example shows how to display a summary of ANCP message statistics: show ancp summary statistics ANCP Summary Message Statistics -------------------------------------- Sent Received SYN 3 6 SYNACK 4 0 ACK 7105 2819 RSTACK 2 0 Port Up - 6 Port Down - 0 Drops 0 0 Total 7114 2831 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 24 OL-26077-02 Configuring Access Node Control Protocol Configuring ANCP Neighbors: ExampleThe following example shows how to clear all neighbor data and statistics: clear ancp neighbor all The following example shows how to clear a specific neighbor: clear ancp neighbor description vendor1a The following example shows how to clear aggregate message statistics: clear ancp summary statistics Mapping AN ports to VLAN Subinterfaces: Example The following example shows a unique access node ID being defined: configure ancp an-port circuit-id circuit1 interface gigabitethernet 2/0/1/1.1 The following example shows how to display information for a port identified by its subinterface: show ancp an-port interface gigabitethernet 0/0/0/37.1 AN port circuit-id ccc1: State UP UPtime 02:23:45 Time Since Last Message 00:00:00 Encap Type ETHERNET DSL type ADSL1 DSL Line State SHOWTIME Number of Mapped Interfaces 3 Neighbor sender-name 0006.2aaa.281b Neighbor description 7200-client Configured Rate Adjustment 90% Actual Downstream Data Rate (kbps) 2500 Effective Downstream Data Rate (kbps) 2250 The following example shows how use the detail keyword to display port information as well as a list of the interfaces mapped to that port. show ancp an-port circuit-id ccc1 detail AN port circuit-id ccc1: State UP UPtime 02:31:36 Time Since Last Message 00:00:00 Encap Type ETHERNET DSL type ADSL1 DSL Line State SHOWTIME Number of Mapped Interfaces 3 Neighbor sender-name 0006.2aaa.281b Neighbor description 7200-client Configured Rate Adjustment 90% Actual Downstream Data Rate (kbps) 2500 Effective Downstream Data Rate (kbps) 2250 Actual Data Rate Upstream/Downstream (kbps) 2500/2500 Minimum Data Rate Upstream/Downstream (kbps) 0/0 Attainable Data Rate Upstream/Downstream (kbps) 0/0 Maximum Data Rate Upstream/Downstream (kbps) 0/0 Minimum Low Power Data Rate Upstream/Downstream (kbps) 0/0 Maximum Interleaving delay Upstream/Downstream (ms) 0/0 Actual Interleaving Delay Upstream/Downstream (ms) 0/0 Sub-interface Summary: total 3 ----------------------------------------------- Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 25 Configuring Access Node Control Protocol Mapping AN ports to VLAN Subinterfaces: ExampleSub-interface Name ifhandle --------------------------------- ---------- GigabitEthernet0/0/0/37.1 0x0 GigabitEthernet0/0/0/37.11 0x0 GigabitEthernet0/0/0/38.10 0xb80 The following example uses the statistics keyword to display port message statistics for a specific AN port: show ancp an-port circuit-id ccc1 statistics Port message statistics for circuit-id ccc1: Port Up 5 Port Down 0 The following example shows how to display port counts by state: show ancp an-port summary AN Port Count Summary ------------------------------ State UP 4 State DOWN 0 Config only ports 0 Total 4 # Configured ports 1 # Mapped sub-interfaces 4 The following example shows how to clear message statistics for all AN ports: clear ancp an-port all statistics The following example shows how to clear dynamic data for all AN ports: clear ancp an-port all The following example show how to clear dynamic data for a specific interface: clear ancp an-port interface gigabitethernet 0/1/0/10.5 Configuring ANCP Rate Adjustment: Example ANCP and QoS Interaction: Example The following example shows a hierarchical QoS policy configuration with and without an ANCP value applied: policy-map child-3play class 3play-voip priority level 1 police rate 65 kbps ! ! class 3play-video priority level 2 police rate 128 kbps ! random-detect cos 3 10 ms 100 ms random-detect cos 4 20 ms 200 ms ! class 3play-premium bandwidth percent 100 ! class class-default ! Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 26 OL-26077-02 Configuring Access Node Control Protocol Configuring ANCP Rate Adjustment: Exampleend-policy-map ! policy-map parent-3play-subscriber-line class class-default service-policy child-3play shape average 1 mbps ! end policy-map ! A policy is applied on an interface without ANCP: interface GigabitEthernet 0/1/0/0.1 l2transport encapsulation dot1q 2 service-policy output parent-3play-subscriber-line ! The show qos command verifies that ANCP has not been applied (ANCP is shown as 0 kbps). RP/0/RSP0/CPU0:router# show qos interface GigabitEthernet 0/1/0/0.1 out Interface: GigabitEthernet0_1_0_0.1 output Bandwidth: 1000000 kbps ANCP: 0 kbps Policy: parent-3-play-subscriber-line Total number of classes: 5 --------------------------------------------------------------------------- Level: 0 Policy: parent-3-play-subscriber-line Class: class-default QueueID: N/A Shape Profile: 1 CIR: 960 kbps CBS: 1024 bytes PIR: 960 kbps PBS: 13312 bytes WFQ Profile: 1 Committed Weight: 1 Excess Weight: 1 Bandwidth: 0 kbps, BW sum for Level 0: 1000000 kbps, Excess Ratio: 1 --------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-voip Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 8 (Priority 1) Queue Limit: 16 kbytes Profile: 3 Scale Profile: 0 Policer Profile: 0 (Single) Conform: 65 kbps (65 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP --------------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-video Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 9 (Priority 2) Queue Limit: 8 kbytes (11 Unknown) Profile: 4 Scale Profile: 0 Policer Profile: 24 (Single) Conform: 128 kbps (128 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP WRED Type: COS based Table: 0 Profile: 4 Scale Profile: 0 Curves: 3 Default RED Curve Thresholds Min : 8 kbytes Max: 8 kbytes WRED Curve: 1 Thresholds Min : 8 kbytes Max: 8kbytes Match: 3 WRED Curve: 2 Thresholds Min : 8 kbytes Max: 8 kbytes Match: 4 --------------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3-play-premium Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 10 (Priority Normal) Queue Limit: 16 kbytes Profile: 1 Scale Profile: 1 WFQ Profile: 4 Committed Weight: 100 Excess Weight: 100 Bandwidth: 1000 kbps, BW sum for Level 1: 1000 kbps, Excess Ratio: 1 --------------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: class-default Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 11 (Priority Normal) Queue Limit: 8 kbytes Profile: 1 Scale Profile: 0 WFQ Profile: 5 Committed Weight: 1 Excess Weight: 1 Bandwidth: 0 kbps, BW sum for Level 1: 1000 kbps, Excess Ratio: 1 -------------------------------------------------------------------------------- RP/0/RSP0/CPU0:router# Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 27 Configuring Access Node Control Protocol ANCP and QoS Interaction: ExampleANCP AN-Port to Interface Mapping is applied: RP/0/RSP0/CPU0:router# configure RP/0/RSP0/CPU0:router(config)# ancp an-port circuit-id dslam1_port1 interface GigabitEthernet 0/1/0/0.1 The show ancp an-port interface command shows the ANCP rate for the interface: RP/0/RSP0/CPU0:router# show ancp an-port interface GigabitEthernet 0/1/0/0.1 detail AN port circuit-id dlsam1_port1: State UP Uptime 00:00:32 Time Since Last Message 00:00:32 Encap Type ATM DSL Type ADSL1 DSL Line State SHOWTIME Number of Mapped Sub-interfaces 1 Neighbor sender-name 0000.0000.1bec Neighbor description - Configured Rate Adjustment 100% Actual Downstream Data Rate (kbps) 2000 Effective Downstream Data Rate (kbps) 2000 Actual Data Rate Upstream/Downstream (kbps) 2000/2000 Minimum Data Rate Upstream/Downstream (kbps) 0/0 Attainable Data Rate Upstream/Downstream (kbps) 0/0 Maximum Data Rate Upstream/Downstream (kbps) 0/0 Minimum Low Power Data Rate Upstream/Downstream (kbps) 0/0 Maximum Interleaving Delay Upstream/Downstream (ms) 0/0 Actual Interleaving Delay Upstream/Downstream (ms) 0/0 Sub-interface Summary: total 1 ------------------------------------------------------ Sub-interface name ifhandle ---------------------------------- ---------- GigabitEthernet0/1/0.1 0x215e042 The show qos command verifies that ANCP has been applied (ANCP is now shown as 1920 kbps). RP/0/RSP0/CPU0/router# show qos interface GigabitEthernet 0/1/0.1 out Interface GigabitEthernet0_1_0_0.1 output Bandwidth: 1000000 kbps ANCP: 1920 kbps Policy: parent-3play-subscriber-line Total number of classes: 5 -------------------------------------------------------------------- Level: 0 Policy: parent-3-play-subscriber-line Class: class-default QueueID: N/A Shape Profile: 1 CIR: 1920 kbps CBS: 1024 bytes PIR: 1920 kbps PBS: 13312 bytes WFQ Profile: 1 Committed Weight: 1 Excess Weight: 1 Bandwidth: 0 kbps, BW sum for Level 0: 1000000 kbps, Excess Ratio: 1 --------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-voip Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 8 (Priority 1) Queue Limit: 16 kbytes Profile: 3 Scale Profile: 0 Policer Profile: 0 (Single) Conform: 65 kbps (65 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP --------------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-video Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 9 (Priority 2) Queue Limit: 8 kbytes (11 Unknown) Profile: 4 Scale Profile: 0 Policer Profile: 24 (Single) Conform: 128 kbps (128 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP WRED Type: COS based Table: 0 Profile: 4 Scale Profile: 0 Curves: 3 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 28 OL-26077-02 Configuring Access Node Control Protocol ANCP and QoS Interaction: ExampleDefault RED Curve Thresholds Min : 8 kbytes Max: 8 kbytes WRED Curve: 1 Thresholds Min : 8 kbytes Max: 8kbytes Match: 3 WRED Curve: 2 Thresholds Min : 8 kbytes Max: 8 kbytes Match: 4 --------------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3-play-premium Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 10 (Priority Normal) Queue Limit: 24 kbytes Profile: 1 Scale Profile: 8 WFQ Profile: 4 Committed Weight: 100 Excess Weight: 100 Bandwidth: 1920 kbps, BW sum for Level 1: 1920 kbps, Excess Ratio: 1 --------------------------------------------------------------------------------- Level: 1 Policy: child-3play Class: class-default Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 11 (Priority Normal) Queue Limit: 8 kbytes Profile: 1 Scale Profile: 0 WFQ Profile: 5 Committed Weight: 1 Excess Weight: 1 Bandwidth: 0 kbps, BW sum for Level 1: 1920 kbps, Excess Ratio: 1 --------------------------------------------------------------------------------- QoS Policy Inconsistency on an Interface: Example A valid QoS policy with absolute or percentage values must satisfy the following requirement: interface speed > ANCP rate > QoS parent shaper rate A Qos policy successfully applied to an interface can become invalid due to two possible external factors. These two factors are an ANCP rate change or a port speed change: • ANCP Rate Change—If the ANCP rate falls, or the ANCP rate adjustment factor makes the ANCP rate fall below the shaper rate of the top-most QoS policy map, the QoS policy on the interface becomes invalid. • Port Speed Change—The port of a GigabitEthernet interface can be configured to 10 Mbps or 100 Mbps mode from the default of 1000 Mbps. When this happens, the interface speed drops to less than the ANCP rate and QoS parent shaper rate. The QoS policy on the interface becomes invalid. When either of these changes occur, the QoS policy on the interface is placed in the inconsistency state. To recover from the inconsistency state, perform one of the following tasks: • Remove the QoS policy from the interface, adjust the QoS policy values, then reapply the QoS policy to the interface. • If the ANCP adjustment rate or the ANCP rate has been modified, update the ANCP rate to satisfy the QoS policy rate requirement. • If port speed has been modified, update the speed to satisfy the QoS policy rate requirement. Following are examples of the effects of an ANCP rate change and a port speed change have on the following QoS policy configuration on a Gigabit Ethernet interface: policy-map child-3play class 3play-voip priority level 1 police rate 65 kbps ! ! class 3play-video priority level 2 police rate 128 kbps ! random-detect cos 3 10 ms 100 ms Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 29 Configuring Access Node Control Protocol QoS Policy Inconsistency on an Interface: Examplerandom-detect cos 4 20 ms 200 ms ! class 3play-premium bandwidth percent 100 ! Class class-default ! end-policy-map ! policy-map parent-3play-subscriber-line class class-default service-policy child-3play bandwidth 200 mbps bandwidth remaining percent 100 shape average 800 mbps ! end-policy-map ! If the ANCP rate value 999936 kbps, and the ANCP rate factor is 100 percent, the ANCP rate value of 999936 is applied to the interface. This satisfies the requirement: Interface speed (1000000 kbps) > ANCP rate (999936 kbps) > QoS parent shaper rate (800000 kbps) This is a successful application of the policy as shown by the following show qos interface command output: show qos interface gig0/0/0/11.1 output Wed Mar 18 18:25:20.140 UTC Interface: GigabitEthernet0_0_0_11.1 output Bandwidth: 1000000 kbps ANCP: 999936 kbps Policy: parent-3play-subscriber-line Total number of classes: 5 ---------------------------------------------------------------------- Level: 0 Policy: parent-3play-subscriber-line Class: class-default QueueID: N/A Shape Profile: 1 CIR: 200000 kbps (200 mbps) CBS: 100352 bytes PIR: 999936 kbps PBS: 12517376 bytes WFQ Profile: 1 Committed Weight: 51 Excess Weight: 100 Bandwidth: 200000 kbps, BW sum for Level 0: 1000000 kbps, Excess Ratio: 100 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-voip Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 136 (Priority 1) Queue Limit: 16 kbytes Profile: 3 Scale Profile: 0 Policer Profile: 0 (Single) Conform: 65 kbps (65 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-video Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 137 (Priority 2) Queue Limit: 8 kbytes (11 Unknown) Profile: 4 Scale Profile: 0 Policer Profile: 24 (Single) Conform: 128 kbps (128 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP WRED Type: COS based Table: 0 Profile: 4 Scale Profile: 0 Curves: 3 Default RED Curve Thresholds Min : 8 kbytes Max: 8 kbytes WRED Curve: 1 Thresholds Min : 8 kbytes Max: 8 kbytes Match: 3 WRED Curve: 2 Thresholds Min : 8 kbytes Max: 8 kbytes Match: 4 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-premium Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 138 (Priority Normal) Queue Limit: 2097 kbytes Profile: 2 Scale Profile: 0 WFQ Profile: 6 Committed Weight: 1020 Excess Weight: 1020 Bandwidth: 200000 kbps, BW sum for Level 1: 200000 kbps, Excess Ratio: 1 ---------------------------------------------------------------------- Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 30 OL-26077-02 Configuring Access Node Control Protocol QoS Policy Inconsistency on an Interface: ExampleLevel: 1 Policy: child-3play Class: class-default Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 139 (Priority Normal) Queue Limit: 65 kbytes Profile: 1 Scale Profile: 3 WFQ Profile: 0 Committed Weight: 1 Excess Weight: 1020 Bandwidth: 0 kbps, BW sum for Level 1: 200000 kbps, Excess Ratio: 1 ---------------------------------------------------------------------- ANCP Rate Change If the ANCP rate falls below the QoS parent shaper rate for example, to 300000 kbps, and the ANCP rate adjustment factor remains at 100 percent, the ANCP rate is no longer greater than the QoS parent shaper rate of 800000 kbps. This causes the QoS policy on the interface to be placed in the inconsistency state as shown by the following show qos interface command output: show qos interface gig0/0/0/11.1 output Wed Mar 18 18:21:11.180 UTC Interface: GigabitEthernet0_0_0_11.1 output Bandwidth: 1000000 kbps ANCP: 299904 kbps *Inconsistency* : ANCP - Downstream Rate less than Shaper Rate Policy: parent-3play-subscriber-line Total number of classes: 5 ---------------------------------------------------------------------- Level: 0 Policy: parent-3play-subscriber-line Class: class-default QueueID: N/A Shape Profile: 2 CIR: 200000 kbps (200 mbps) CBS: 100352 bytes PIR: 800000 kbps PBS: 10027008 bytes WFQ Profile: 1 Committed Weight: 51 Excess Weight: 100 Bandwidth: 200000 kbps, BW sum for Level 0: 1000000 kbps, Excess Ratio: 100 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-voip Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 136 (Priority 1) Queue Limit: 16 kbytes Profile: 3 Scale Profile: 0 Policer Profile: 0 (Single) Conform: 65 kbps (65 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-video Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 137 (Priority 2) Queue Limit: 8 kbytes (11 Unknown) Profile: 4 Scale Profile: 0 Policer Profile: 24 (Single) Conform: 128 kbps (128 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP WRED Type: COS based Table: 0 Profile: 4 Scale Profile: 0 Curves: 3 Default RED Curve Thresholds Min : 8 kbytes Max: 8 kbytes WRED Curve: 1 Thresholds Min : 8 kbytes Max: 8 kbytes Match: 3 WRED Curve: 2 Thresholds Min : 8 kbytes Max: 8 kbytes Match: 4 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-premium Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 138 (Priority Normal) Queue Limit: 2097 kbytes Profile: 2 Scale Profile: 0 WFQ Profile: 6 Committed Weight: 1020 Excess Weight: 1020 Bandwidth: 200000 kbps, BW sum for Level 1: 200000 kbps, Excess Ratio: 1 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: class-default Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 139 (Priority Normal) Queue Limit: 65 kbytes Profile: 1 Scale Profile: 3 WFQ Profile: 0 Committed Weight: 1 Excess Weight: 1020 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 31 Configuring Access Node Control Protocol QoS Policy Inconsistency on an Interface: ExampleBandwidth: 0 kbps, BW sum for Level 1: 200000 kbps, Excess Ratio: 1 ---------------------------------------------------------------------- Once the ANCP rate returns to the configured value, the inconsistency is automatically cleared, which can be confirmed by issuing the show qos interface command. If the ANCP rate has been configured to a value less than the shape rate, the inconsistency is not automatically cleared, and the policy must be modified and reapplied. To prevent this from occurring, be sure to configure the policy-map shape rate to the minimum value of all ANCP rates for a given service level. Note Port Speed Change If the port speed is configured to less than the QoS parent shaper rate for example to 100 Mbps (100000 kbps), the requirement is no longer met since the port speed is no longer greater than the QoS parent shaper rate of 800000 kbps. RP/0/RSP0/CPU0:ro-node1#conf RP/0/RSP0/CPU0:ro-node1(config)#int gigabitEthernet 0/0/0/1 RP/0/RSP0/CPU0:ro-node1(config-if)#speed 100 RP/0/RSP0/CPU0:ro-node1(config-if)#commit LC/0/0/CPU0:Nov 4 05:36:55.041 : qos_ma_ea[197]: %QOS-QOS_EA_MODIFY_FAIL-3-ERROR : inconsistency detected due to ANCP or Bandwidth modification. Execute show qos inconsistency, to obtain information. Policy resolution failure RP/0/RSP0/CPU0:ro-node1(config-if)#end This causes the QoS policy on the interface to be placed in the inconsistency state as shown by the following show qos interface command output: RP/0/RSP0/CPU0:ro-node1#sh qos int gigabitEthernet 0/0/0/1.1 output Interface: GigabitEthernet0_0_0_1.1 output Bandwidth: 1000000 kbps ANCP: 0 kbps *Inconsistency* : Port speed modify fails on Policy Policy: parent-3play-subscriber-line Total number of classes: 5 ---------------------------------------------------------------------- Level: 0 Policy: parent-3play-subscriber-line Class: class-default QueueID: N/A Shape Profile: 1 CIR: 200000 kbps (200 mbps) CBS: 100352 bytes PIR: 800000 kbps PBS: 10027008 bytes WFQ Profile: 1 Committed Weight: 51 Excess Weight: 100 Bandwidth: 200000 kbps, BW sum for Level 0: 1000000 kbps, Excess Ratio: 100 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-voip Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 640 (Priority 1) Queue Limit: 16 kbytes Profile: 3 Scale Profile: 0 Policer Profile: 0 (Single) Conform: 65 kbps (65 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-video Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 641 (Priority 2) Queue Limit: 8 kbytes Profile: 4 Scale Profile: 0 Policer Profile: 24 (Single) Conform: 128 kbps (128 kbps) Burst: 1598 bytes (0 Default) Child Policer Conform: TX Child Policer Exceed: DROP Child Policer Violate: DROP WRED Type: COS based Table: 2 Profile: 4 Scale Profile: 0 Curves: 3 Default RED Curve Thresholds Min : 8 kbytes Max: 8 kbytes WRED Curve: 1 Thresholds Min : 8 kbytes Max: 8 kbytes Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 32 OL-26077-02 Configuring Access Node Control Protocol QoS Policy Inconsistency on an Interface: ExampleMatch: 3 WRED Curve: 2 Thresholds Min : 8 kbytes Max: 8 kbytes Match: 4 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: 3play-premium Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 642 (Priority Normal) Queue Limit: 4194 kbytes Profile: 2 Scale Profile: 1 WFQ Profile: 3 Committed Weight: 1020 Excess Weight: 1020 Bandwidth: 200000 kbps, BW sum for Level 1: 200000 kbps, Excess Ratio: 1 ---------------------------------------------------------------------- Level: 1 Policy: child-3play Class: class-default Parent Policy: parent-3play-subscriber-line Class: class-default QueueID: 643 (Priority Normal) Queue Limit: 4194 kbytes Profile: 2 Scale Profile: 1 WFQ Profile: 4 Committed Weight: 1 Excess Weight: 1 Bandwidth: 0 kbps, BW sum for Level 1: 200000 kbps, Excess Ratio: 1 ---------------------------------------------------------------------- To resolve this issue, the port speed must be set back to 1000 Mbps (1000000 kbps) using the no speed command. RP/0/RSP0/CPU0:ro-node1#conf RP/0/RSP0/CPU0:ro-node1(config)#int gigabitEthernet 0/0/0/1 RP/0/RSP0/CPU0:ro-node1(config-if)#no speed RP/0/RSP0/CPU0:ro-node1(config-if)#commit LC/0/0/CPU0:Nov 4 05:37:39.171 : ifmgr[144]: %PKT_INFRA-LINEPROTO-5-UPDOWN : Line protocol on Interface GigabitEthernet0/0/0/1, changed state to Up The clearing of the inconsistency can be verified by again issuing the show qos interface command. The show qos inconsistency Command: Example A command related to show qosinterface command provides additional detail about QoS policy inconsistency: RP/0/RSP0/CPU0:RO2#show qos inconsistency detail 0 location 0/7/CPU0 Interface Lists with QoS Inconsistency Warning: ========================================================= Node 0/7/CPU0 --------------------------------------------------------- Interfaces with QoS Inconsistency: ANCP - No Shaper at top policymap ========================================================================== Interface Direction Policy Name SPI Name -------------------------------------------------------------------------- GigabitEthernet0/7/0/1.5 output parent-none Interfaces with QoS Inconsistency: ANCP - Downstream Rate less than Shaper Rate ========================================================================== Interface Direction Policy Name SPI Name -------------------------------------------------------------------------- GigabitEthernet0/7/0/1 output parent SPI1 GigabitEthernet0/7/0/1.2 output parent GigabitEthernet0/7/0/1 output normal-policy-name normal-spi-name RP/0/RSP0/CPU0:RO2# RP/0/RSP0/CPU0:RO2#show qos inconsistency summary location 0/7/CPU0 Summary Counts of QoS Inconsistency Warnings: ========================================================= Node 0/7/CPU0 Inconsistency Warning Type Count -------------------------------------------------------- ANCP - No Shaper at top policymap: 1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 33 Configuring Access Node Control Protocol QoS Policy Inconsistency on an Interface: ExampleANCP - Downstream Rate less than Shaper Rate: 4 RP/0/RSP0/CPU0:RO2# Additional References The following sections provide references related to implementing ANCP. Related Documents Related Topic Document Title Cisco ASR 9000 Series Aggregation Services Router Getting Started Guide Initial system bootup and configuration Cisco ASR 9000 Series Aggregation Services Router Master Command Listing Master command reference Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference QoS commands “Configuring AAA Services on Cisco ASR 9000 Series Router” module of Cisco Cisco ASR 9000 Series Aggregation Services Router System Security Configuration Guide User groups and task IDs Standards Standards Title No new or modified standards are supported by — this feature, and support for existing standards has not been modified by this feature. MIBs MIBs MIBs Link To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/ cmtk/mibs.shtml — Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 34 OL-26077-02 Configuring Access Node Control Protocol Additional ReferencesRFCs RFCs Title No new or modified RFCs are supported by this — feature, and support for existing RFCs has not been modified by this feature. Technical Assistance Description Link The Cisco Technical Support website contains http://www.cisco.com/techsupport thousands of pages of searchable technical content, including links to products, technologies,solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content. Configuring Access Node Control Protocol Access Node Control Protocol (ANCP) creates a control plane between a service-oriented aggregation device and an access node (AN) (for example, a DSLAM) in order to perform QoS-related, service-related, and subscriber-related operations. An ANCP server accepts and maintains ANCP adjacencies (sessions with an ANCP neighbor), and sending and receiving ANCP messages. ANCP allows static mapping between ANCP ports and VLAN subinterfaces so that DSL rate updates for a specific subscriber received by the ANCP server are applied to the QoS configuration corresponding to that subscriber. DSL train rates received via ANCP are used to alter shaping rates on subscriber-facing interfaces and subinterfaces on the router. ANCP runs as a single process on the route processor (RP). This module provides the conceptual and configuration information for implementing ANCP. Line Card, SIP, and SPA Support Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 Access Node Control Protocol yes no Feature History for Configuring Access Node Protocol on Cisco ASR 9000 Series Routers Release Modification Release 3.7.2 The Access Node Control Protocol feature was introduced. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 35 Configuring Access Node Control Protocol RFCsRelease 3.9.0 Mapping of ANCP portsto VLAN interfaces over Ethernet bundles was added. Release 4.0.0 ANCP over Multi Chassis Link Aggregation was introduced. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 36 OL-26077-02 Configuring Access Node Control Protocol Configuring Access Node Control ProtocolC H A P T E R 3 Configuring Modular QoS Congestion Avoidance Congestion avoidance techniques monitor traffic flow in an effort to anticipate and avoid congestion at common network bottlenecks. Avoidance techniques are implemented before congestion occurs as compared with congestion management techniques that control congestion after it has occurred. Congestion avoidance is achieved through packet dropping. Cisco IOS XR software supports the following quality of service (QoS) congestion avoidance techniques that drop packets: • Random early detection (RED • Weighted random early detection (WRED) • Tail drop The module describes the concepts and tasks related to these congestion avoidance techniques. Line Card, SIP, and SPA Support Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 Random Early Detection yes yes Weighted Random Early Detection yes yes Tail Drop yes yes Feature History for Configuring Modular QoS Congestion Avoidance on Cisco ASR 9000 Series Routers Release Modification The Congestion Avoidance feature was introduced on ASR 9000 Ethernet Line Cards. The Random Early Detection, Weighted Random Early Detection, and Tail Drop features were introduced on ASR 9000 Ethernet Line Cards. Release 3.7.2 The Random Early Detection, Weighted Random Early Detection, and Tail Drop features were supported on the SIP 700 for the ASR 9000. Release 3.9.0 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 37• Prerequisites for Configuring Modular QoS Congestion Avoidance, page 38 • Information About Configuring Modular QoS Congestion Avoidance, page 38 • Additional References, page 51 Prerequisites for Configuring Modular QoS Congestion Avoidance The following prerequisite is required for configuring QoS congestion avoidance on your network: You must be in a user group associated with a task group that includes the proper task IDs. The command reference guides include the task IDs required for each command. If you suspect user group assignment is preventing you from using a command, contact your AAA administrator for assistance. Information About Configuring Modular QoS Congestion Avoidance To configure QoS congestion avoidance techniques in this document you must understand the following concepts: Random Early Detection and TCP The RED congestion avoidance technique takes advantage of the congestion control mechanism of TCP. By randomly dropping packets prior to periods of high congestion, RED tells the packet source to decrease its transmission rate. Assuming the packet source is using TCP, it decreases its transmission rate until all packets reach their destination, indicating that the congestion is cleared. You can use RED as a way to cause TCP to slow transmission of packets. TCP not only pauses, but it also restarts quickly and adapts its transmission rate to the rate that the network can support. RED distributes losses in time and maintains normally low queue depth while absorbing traffic bursts. When enabled on an interface, RED begins dropping packets when congestion occurs at a rate you select during configuration. Queue-limit for WRED Queue-limit is used to fine-tune the number of buffers available for each queue. It can only be used on a queuing class. Default queue limit is 100 ms of the service rate for the given queue. The service rate is the sum of minimum guaranteed bandwidth and bandwidth remaining assigned to a given class either implicitly or explicitly. The queue-limit is rounded up to one of the following values: 8 KB, 16 KB, 24 KB, 32 KB, 48 KB, 64 KB, 96 KB, 128 KB, 192 KB, 256 KB, 384 KB, 512 KB, 768 KB, 1024 KB, 1536 KB, 2048 KB, 3072 KB, 4196 KB, 8192 KB, 16394 KB, 32768 KB, 65536 KB, 131072 KB, or 262144 KB. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 38 OL-26077-02 Configuring Modular QoS Congestion Avoidance Prerequisites for Configuring Modular QoS Congestion AvoidanceTail Drop and the FIFO Queue Tail drop is a congestion avoidance technique that drops packets when an output queue is full until congestion is eliminated. Tail drop treats all traffic flow equally and does not differentiate between classes of service. It manages the packets that are unclassified, placed into a first-in, first-out (FIFO) queue, and forwarded at a rate determined by the available underlying link bandwidth. See the “Default Traffic Class” section of the “Configuring Modular Quality of Service Packet Classification and Marking on Cisco ASR 9000 Series Routers” Configuring Random Early Detection This configuration task issimilar to that used for WRED except that the random-detect precedence command is not configured and the random-detect command with the default keyword must be used to enable RED. Restrictions If you configure the random-detect default command on any classincluding class-default, you must configure one of the following commands: • shape average • bandwidth • bandwidth remaining SUMMARY STEPS 1. configure 2. policy-map policy-map-name 3. class class-name 4. random-detect {cos value | default | discard-class value | dscp value | exp value | precedence value | min-threshold [units] max-threshold [units] } 5. bandwidth {bandwidth [units] | percent value} or bandwidth remaining [percent value | ratio ratio-value 6. shape average {percent percentage | value [units]} 7. exit 8. exit 9. interface type interface-path-id 10. service-policy {input | output} policy-map 11. Use one of these commands: • end • commit Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 39 Configuring Modular QoS Congestion Avoidance Tail Drop and the FIFO QueueDETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-map-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. random-detect {cos value | default | discard-class Enables RED with default minimum and maximum thresholds. value | dscp value | exp value | precedence value | min-threshold [units] max-threshold [units] } Step 4 Example: RP/0/RSP0/CPU0:router(config-pmap-c)# random-detect default (Optional) Specifiesthe bandwidth allocated for a class belonging to a policy map. bandwidth {bandwidth [units] | percent value} or bandwidth remaining [percent value | ratio ratio-value Step 5 or Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth percent 30 (Optional) Specifies how to allocate leftover bandwidth to various classes. Note • One of these configurations is required for a or non-default class. RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth remaining percent 20 (Optional) Shapes traffic to the specified bit rate or a percentage of the available bandwidth. shape average {percent percentage | value [units]} Example: RP/0/RSP0/CPU0:router(config-pmap-c)# shape average percent 50 Step 6 exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 7 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 40 OL-26077-02 Configuring Modular QoS Congestion Avoidance Configuring Random Early DetectionCommand or Action Purpose exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 8 interface type interface-path-id Enters configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface TenGigE 0/2/0/0 Step 9 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 10 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 11 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config-if)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config-if)# commit ? Entering no exitsthe configuration session and returns the router to EXEC mode without committing the configuration changes. ? Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 41 Configuring Modular QoS Congestion Avoidance Configuring Random Early DetectionConfiguring Random Early Detection SUMMARY STEPS 1. 2. policy-map policy-name 3. class class-name 4. random-detect {cos value | default | discard-class value | dscp value | exp value | precedence value | min-threshold [units] max-threshold [units] } 5. random-detect {discard-class value | dscp value | exp value | precedence value | min-threshold [units] max-threshold [units] } 6. bandwidth {bandwidth [units] | percent value} 7. bandwidth remaining percent value 8. shape average {percent percentage | value [units]} 9. exit 10. exit 11. interface type interface-path-id 12. end or commit DETAILED STEPS Command or Action Purpose Enters global configuration mode. Example: RP/0//CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0//CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0//CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. random-detect {cos value | default | discard-class Enables RED with minimum and maximum thresholds. value | dscp value | exp value | precedence value | min-threshold [units] max-threshold [units] } Step 4 Example: RP/0/RP0/CPU0:router(config-pmap-c)# random-detect default Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 42 OL-26077-02 Configuring Modular QoS Congestion Avoidance Configuring Random Early DetectionCommand or Action Purpose random-detect {discard-class value | dscp value | Enables RED with default minimum and maximum thresholds. exp value | precedence value | min-threshold [units] max-threshold [units] } Step 5 Example: RP/0/0/CPU0:router(config-pmap-c)# random-detect 1000000 2000000 (Optional) Specifiesthe bandwidth allocated for a class belonging to a policy map. bandwidth {bandwidth [units] | percent value} Example: RP/0//CPU0:router(config-pmap-c)# bandwidth percent 30 Step 6 (Optional) Specifies how to allocate leftover bandwidth to various classes. bandwidth remaining percent value Example: RP/0//CPU0:router(config-pmap-c)# bandwidth remaining percent 20 Step 7 (Optional) Shapes traffic to the specified bit rate or a percentage of the available bandwidth. shape average {percent percentage | value [units]} Example: RP/0//CPU0:router(config-pmap-c)# shape average percent 50 Step 8 exit Returns the router to policy map configuration mode. Example: RP/0//CPU0:router(config-pmap-c)# exit Step 9 exit Returns the router to global configuration mode. Example: RP/0//CPU0:router(config-pmap)# exit Step 10 Step 11 interface type interface-path-id Enters configuration mode and configures an interface. Example: RP/0//CPU0:router(config)# interface pos 0/2/0/0 Attaches a policy map to an input or output interface to be used as the service policy for that interface. • In this example, the traffic policy evaluates all traffic leaving that interface. Example: RP/0//CPU0:router(config-if)# service-policy output policy1 Step 12 end or commit Saves configuration changes. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 43 Configuring Modular QoS Congestion Avoidance Configuring Random Early DetectionCommand or Action Purpose Example: RP/0//CPU0:router(config-cmap)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0//CPU0:router(config-cmap)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changesto the running configuration file and remain within the configuration session. Configuring Weighted Random Early Detection WRED drops packets selectively based on any specified criteria, such as CoS, DSCP, EXP, discard-class, or precedence . WRED uses these matching criteria to determine how to treat different types of traffic. Configure WRED using the random-detect command and different CoS, DSCP, EXP, and discard-class values. The value can be range or a list of values that are valid for that field. You can also use minimum and maximum queue thresholds to determine the dropping point. When a packet arrives, the following actions occur: • If the queue size is less than the minimum queue threshold, the arriving packet is queued. • If the queue size is between the minimum queue threshold for that type of traffic and the maximum threshold for the interface, the packet is either dropped or queued, depending on the packet drop probability for that type of traffic. • If the queue size is greater than the maximum threshold, the packet is dropped. Restrictions When configuring the random-detect dscp command, you must configure one of the following commands: shape average, bandwidth, and bandwidth remaining. Only two minimum and maximum thresholds (each with different match criteria) can be configured per class. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 44 OL-26077-02 Configuring Modular QoS Congestion Avoidance Configuring Weighted Random Early DetectionSUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. random-detect dscp dscp-value min-threshold [units] max-threshold [units] 5. bandwidth {bandwidth [units] | percent value} or bandwidth remaining [percent value | ratio ratio-value] 6. bandwidth {bandwidth [units] | percent value} 7. bandwidth remaining percent value 8. shape average {percent percentage | value [units]} 9. queue-limit value [units] RP/0/RSP0/CPU0:router(config-pmap-c)# queue-limit 50 ms 10. exit 11. interface type inteface-path-id 12. service-policy {input | output} policy-map 13. end or commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. Changes the minimum and maximum packet thresholds for the DSCP value. random-detect dscp dscp-value min-threshold [units] max-threshold [units] Step 4 Example: RP/0/RSP0/CPU0:router(config-pmap-c)# • Enables WRED. • dscp-value—Number from 0 to 63 that sets the DSCP value. Reserved keywords can be specified instead of numeric values. random-detect dscp af11 1000000 bytes 2000000 bytes • min-threshold—Minimum threshold in the specified units. When the average queue length reaches the minimum threshold, WRED randomly drops some packets with the specified DSCP value. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 45 Configuring Modular QoS Congestion Avoidance Configuring Weighted Random Early DetectionCommand or Action Purpose • max-threshold—Maximum threshold in the specified units. When the average queue length exceeds the maximum threshold, WRED drops all packets with the specified DSCP value. • units—Units of the threshold value. This can be bytes, gbytes, kbytes, mbytes, ms(milliseconds), packets, or us(microseconds). The default is packets. • This example shows that for packets with DSCP AF11, the WRED minimum threshold is 1,000,000 bytes and maximum threshold is 2,000,000 bytes. (Optional) Specifies the bandwidth allocated for a class belonging to a policy map. bandwidth {bandwidth [units] | percent value} or bandwidth remaining [percent value | ratio ratio-value] Step 5 or Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth percent 30 (Optional) Specifies how to allocate leftover bandwidth to various classes. Note • One of these configurations is required for a non-default class. or RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth remaining percent 20 (Optional) Specifies the bandwidth allocated for a class belonging to a policy map. bandwidth {bandwidth [units] | percent value} Example: RP/0//CPU0:router(config-pmap-c)# bandwidth percent 30 Step 6 • This example guarantees 30 percent of the interface bandwidth to class class1. Step 7 bandwidth remaining percent value (Optional) Specifies how to allocate leftover bandwidth to various classes. Example: RP/0//CPU0:router(config-pmap-c)# bandwidth remaining percent 20 • The remaining bandwidth of 70 percent is shared by all configured classes. • In this example, class class1 receives 20 percent of the 70 percent. (Optional) Shapes traffic to the specified bit rate or a percentage of the available bandwidth. shape average {percent percentage | value [units]} Example: RP/0/RSP0/CPU0:router(config-pmap-c)# shape average percent 50 Step 8 (Optional) Changes queue-limit to fine-tune the amount of buffers available for each queue. The default queue-limit is 100 ms of the service rate for a given queue class. queue-limit value [units] RP/0/RSP0/CPU0:router(config-pmap-c)# queue-limit 50 ms Step 9 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 46 OL-26077-02 Configuring Modular QoS Congestion Avoidance Configuring Weighted Random Early DetectionCommand or Action Purpose exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 10 interface type inteface-path-id Enters configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/2/0/0 Step 11 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 12 • In this example, the traffic policy evaluates all traffic leaving that interface. • Ingress policies are not valid; the bandwidth and bandwidth remaining commands cannot be applied to ingress policies. Step 13 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-cmap)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-cmap)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Configuring Tail Drop Packets satisfying the match criteria for a class accumulate in the queue reserved for the class until they are serviced. The queue-limit command is used to define the maximum threshold for a class. When the maximum threshold is reached, enqueued packets to the class queue result in tail drop (packet drop). Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 47 Configuring Modular QoS Congestion Avoidance Configuring Tail DropThe queue-limit value uses the guaranteed service rate (GSR) of the queue as the reference value for the queue_bandwidth. If the class has bandwidth percent associated with it, the queue-limit isset to a proportion of the bandwidth reserved for that class. If the GSR for a queue is zero, use the following to compute the default queue-limit: • 1 percent of the interface bandwidth for queues in a nonhierarchical policy. • 1 percent of minimum parent shape and interface rate for queues within a hierarchical policy. default queue limit (in packets) = (200 ms * (queue bandwidth or shaper rate) / 8) / average packet size, which is 250 bytes The default queue-limit is set to bytes of 100 ms of queue bandwidth. The following formula is used to calculate the default queue limit (in bytes):??bytes = (100 ms / 1000 ms) * queue_bandwidth kbps)) / 8 Note Restrictions • When configuring the queue-limit command in a class, you must configure one of the following commands: priority, shape average, bandwidth, or bandwidth remaining, except for the default class. SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. queue-limit value [units] 5. class class-name 6. bandwidth {bandwidth [units] | percent value} 7. bandwidth remaining percent value 8. exit 9. exit 10. interface type interface-path-id 11. service-policy {input | output} policy-map 12. Use one of these commands: • end • commit Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 48 OL-26077-02 Configuring Modular QoS Congestion Avoidance Configuring Tail DropDETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. Specifies or modifies the maximum the queue can hold for a class policy configured in a policy map. The default value of the units argument is packets. queue-limit value [units] Example: RP/0/RSP0/CPU0:router(config-pmap-c)# queue-limit 1000000 bytes Step 4 • In this example, when the queue limit reaches 1,000,000 bytes, enqueued packets to the class queue are dropped. Example: RP/0//CPU0:router(config-pmap-c)# priority level 1 Specifies priority to a class of traffic belonging to a policy map. Configures traffic policing. Example: RP/0//CPU0:router(config-pmap-c)# police rate percent 30 Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class class2 Step 5 • In this example, class2 is configured. (Optional) Specifies the bandwidth allocated for a class belonging to a policy map. bandwidth {bandwidth [units] | percent value} Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth percent 30 Step 6 • This example guarantees 30 percent of the interface bandwidth to class class2. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 49 Configuring Modular QoS Congestion Avoidance Configuring Tail DropCommand or Action Purpose (Optional) Specifies how to allocate leftover bandwidth to various classes. bandwidth remaining percent value Example: RP/0//CPU0:router(config-pmap-c)# bandwidth remaining percent 20 Step 7 • This example allocates 20 percent of the leftover interface bandwidth to class class2. exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 8 exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 9 interface type interface-path-id Enters configuration mode, and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface pos 0/2/0/0 Step 10 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 11 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 12 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config)# commit ? Entering no exitsthe configuration session and returnsthe router to EXEC mode without committing the configuration changes. ? Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 50 OL-26077-02 Configuring Modular QoS Congestion Avoidance Configuring Tail DropCommand or Action Purpose • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Additional References The following sections provide references related to implementing QoS congestion avoidance. Related Documents Related Topic Document Title Cisco ASR 9000 Series Aggregation Services Router Getting Started Guide Initial system bootup and configuration Cisco ASR 9000 Series Aggregation Services Router Master Command Listing Master command reference Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference QoS commands “Configuring AAA Services on Cisco ASR 9000 Series Router” module of Cisco Cisco ASR 9000 Series Aggregation Services Router System Security Configuration Guide User groups and task IDs Standards Standards Title No new or modified standards are supported by — this feature, and support for existing standards has not been modified by this feature. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 51 Configuring Modular QoS Congestion Avoidance Additional ReferencesMIBs MIBs MIBs Link To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/ cmtk/mibs.shtml — RFCs RFCs Title No new or modified RFCs are supported by this — feature, and support for existing RFCs has not been modified by this feature. Technical Assistance Description Link The Cisco Technical Support website contains http://www.cisco.com/techsupport thousands of pages of searchable technical content, including links to products, technologies,solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 52 OL-26077-02 Configuring Modular QoS Congestion Avoidance MIBsC H A P T E R 4 Configuring Modular QoS Congestion Management Congestion management controls congestion after it has occurred on a network. Congestion is managed on Cisco IOS XR software by using packet queueing methods and by shaping the packet flow through use of traffic regulation mechanisms. The types of traffic regulation mechanisms supported are: • Traffic shaping: ? Modified Deficit Round Robin (MDRR) ? Low-latency queueing (LLQ) with strict priority queueing (PQ) • Traffic policing: ? Color blind ? Color-aware (ingress direction) Line Card, SIP, and SPA Support The following table lists the features that are supported on the ASR 9000 Ethernet Line Cards and SIP 700 for the ASR 9000. Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 Congestion Management Using DEI no yes Guaranteed and Remaining yes yes Bandwidth Low-Latency Queueing with Strict yes yes Priority Queueing Traffic Policing yes yes Traffic Shaping yes yes Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 53Feature History for Configuring Modular QoS Congestion Management on Cisco ASR 9000 Series Router Release Modification The Congestion Avoidance feature was introduced on ASR 9000 Ethernet Line Cards.. The Guaranteed and Remaining Bandwidth, Low-Latency Queueing with Strict Priority Queueing, Traffic Policing, and Traffic Shaping features were introduced on ASR 9000 Ethernet Line Cards. Release 3.7.2 The Guaranteed and Remaining Bandwidth, Low-Latency Queueing with Strict Priority Queueing, Traffic Policing, and Traffic Shaping features were supported on the SIP 700 for the ASR 9000. Release 3.9.0 The Congestion Management Using DEI feature wasintroduced on ASR 9000 Ethernet Line Cards. Release 4.0.0 The police rate command was updated to include packet-based specifications of policing rates and burst sizes. Release 4.0.1 The 2-rate 3-color policer feature was added, including the conform-color and exceed-color commands. This feature is applicable to the SIP 700 line cards, ingress side. Release 4.1.0 Release 4.2.1 The Configured Accounting and QoS for IPv6ACLs features were added. • Prerequisites for Configuring QoS Congestion Management, page 54 • Information about Configuring Congestion Management, page 55 • How to Configure QoS Congestion Management, page 66 • Configuration Examples for configuring congestion management, page 89 • Additional References, page 92 Prerequisites for Configuring QoS Congestion Management The following prerequisites are required for configuring QoS congestion management on your network: • You must be in a user group associated with a task group that includesthe proper task IDs. The command reference guides include the task IDs required for each command. If you suspect user group assignment is preventing you from using a command, contact your AAA administrator for assistance. • You must be familiar with Cisco IOS XR QoS configuration tasks and concepts. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 54 OL-26077-02 Configuring Modular QoS Congestion Management Prerequisites for Configuring QoS Congestion ManagementInformation about Configuring Congestion Management To configure congestion management, you need to understand the following concepts: Congestion Management Overview Congestion management features allow you to control congestion by determining the order in which a traffic flow (or packets) is sent out an interface based on priorities assigned to packets. Congestion management entails the creation of queues, assignment of packets to those queues based on the classification of the packet, and scheduling of the packets in a queue for transmission. The congestion management features in Cisco IOS XR software allow you to specify creation of a different number of queues, affording greater or lesser degree of differentiation of traffic, and to specify the order in which that traffic is sent. During periods with light traffic flow, that is, when no congestion exists, packets are sent out the interface as soon as they arrive. During periods of transmit congestion at the outgoing interface, packets arrive faster than the interface can send them. If you use congestion management features, packets accumulating at an interface are queued until the interface is free to send them; they are then scheduled for transmission according to their assigned priority and the queueing method configured for the interface. The router determines the order of packet transmission by controlling which packets are placed in which queue and how queues are serviced with respect to each other. In addition to queueing methods, QoS congestion management mechanisms, such as policers and shapers, are needed to ensure that a packet adheres to a contract and service. Both policing and shaping mechanisms use the traffic descriptor for a packet. Policers and shapers usually identify traffic descriptor violations in an identical manner through the token bucket mechanism, but they differ in the way they respond to violations. A policer typically dropstraffic flow; whereas, a shaper delays excess traffic flow using a buffer, or queueing mechanism, to hold the traffic for transmission at a later time. Traffic shaping and policing can work in tandem. For example, a good traffic shaping scheme should make it easy for nodes inside the network to detect abnormal flows. Modified Deficit Round Robin MDRR is a class-based composite scheduling mechanism that allowsfor queueing of up to eight traffic classes. It operates in the same manner as class-based weighted fair queueing (CBWFQ) and allows definition of traffic classes based on customer match criteria (such as access lists); however, MDRR does not use the weighted fair queueing algorithm. When MDRR is configured in the queueing strategy, nonempty queues are served one after the other. Each time a queue is served, a fixed amount of data is dequeued. The algorithm then services the next queue. When a queue is served, MDDR keeps track of the number of bytes of data that were dequeued in excess of the configured value. In the next pass, when the queue is served again, less data is dequeued to compensate for the excess data that was served previously. As a result, the average amount of data dequeued per queue is close to the configured value. In addition, MDRR allows for a strict priority queue for delay-sensitive traffic. Each queue within MDRR is defined by two variables: • Quantum value—Average number of bytes served in each round. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 55 Configuring Modular QoS Congestion Management Information about Configuring Congestion Management• Deficit counter—Number of bytes a queue has sent in each round. The counter is initialized to the quantum value. Packets in a queue are served as long as the deficit counter is greater than zero. Each packet served decreases the deficit counter by a value equal to its length in bytes. A queue can no longer be served after the deficit counter becomes zero or negative. In each new round, the deficit counter for each nonempty queue is incremented by its quantum value. Low-Latency Queueing with Strict Priority Queueing The LLQ feature bringsstrict priority queueing (PQ) to the MDRR scheduling mechanism. PQ in strict priority mode ensures that one type of traffic is sent, possibly at the expense of all others. For PQ, a low-priority queue can be detrimentally affected, and, in the worst case, never allowed to send its packets if a limited amount of bandwidth is available or the transmission rate of critical traffic is high. Strict PQ allows delay-sensitive data, such as voice, to be dequeued and sent before packets in other queues are dequeued. LLQ enables the use of a single, strict priority queue within MDRR at the class level, allowing you to direct traffic belonging to a class. To rank class traffic to the strict priority queue, you specify the named class within a policy map and then configure the priority command for the class. (Classes to which the priority command is applied are considered priority classes.) Within a policy map, you can give one or more classes priority status. When multiple classes within a single policy map are configured as priority classes, all traffic from these classes is enqueued to the same, single, strict priority queue. Through use of the priority command, you can assign a strict PQ to any of the valid match criteria used to specify traffic. These methods of specifying traffic for a class include matching on access lists, protocols, IP precedence, and IP differentiated service code point (DSCP) values. Moreover, within an access list you can specify that traffic matches are allowed based on the DSCP value that is set using the first six bits of the IP type of service (ToS) byte in the IP header. Configured Accounting Configured Accounting controls the overhead (packet length) for policing and shaping. The account option can be specified with a service-policy when applying a policy to an interface. For bundle interfaces, the configured accounting option is applied to all member interfaces. The configured accounting option is available on ingress and egress policing, queuing and statistics for CRS-MSC-140G. In CRS-MSC-40G, the configured accounting option is not available for queuing. Prerequisites and Restrictions • Allows packet size accounting tuning to match the QoS treatment provided at the connected interface. • Supported on ASR 9000 Ethernet Linecards and Enhanced Ethernet Linecards. • Supported accounting values are, from -48 to +48. • Ingress shaping accounting is not supported (Ingress and egress policing accounting and egress shaping accounting are supported). • Dynamic changing of accounting overhead after application on policy is not supported Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 56 OL-26077-02 Configuring Modular QoS Congestion Management Low-Latency Queueing with Strict Priority QueueingQoS for IPv6 ACLs The Modular Weapon-X line cards support classification of IPv6 properties based on Source IP, Destination IP, Source Port, Destination Port, Protocol, TOS, Hop Limit, and ACL-based classification. The supported interfaces are indicated below. Supported Interface Ethernet Linecard Enhanced Ethernet Linecard L3 main interface yes yes L3 sub-interface yes yes L3 bundle-interface/ sub-interface yes yes L2 main interface no yes L2 sub-interface no yes L2 bundle-interface/ sub-interface no yes Traffic Shaping Traffic shaping allows you to control the traffic flow exiting an interface to match itstransmission to the speed of the remote target interface and ensure that the traffic conforms to policies contracted for it. Traffic adhering to a particular profile can be shaped to meet downstream requirements, thereby eliminating bottlenecks in topologies with data-rate mismatches. To match the rate of transmission of data from the source to the target interface, you can limit the transfer of data to one of the following: • A specific configured rate • A derived rate based on the level of congestion The rate of transfer depends on these three components that constitute the token bucket: burst size, mean rate, and time (measurement) interval. The mean rate is equal to the burst size divided by the interval. When traffic shaping is enabled, the bit rate of the interface does not exceed the mean rate over any integral multiple of the interval. In other words, during every interval, a maximum of burst size can be sent. Within the interval, however, the bit rate may be faster than the mean rate at any given time. When the peak burst size equals 0, the interface sends no more than the burst size every interval, achieving an average rate no higher than the mean rate. However, when the peak burst size is greater than 0, the interface can send as many as the burst size plus peak burst bits in a burst, if in a previous time period the maximum amount was not sent. Whenever less than the burst size is sent during an interval, the remaining number of bits, up to the peak burst size, can be used to send more than the burst size in a later interval. Regulation of Traffic with the Shaping Mechanism When incoming packets arrive at an interface, the packets are classified using a classification technique, such as an access control list (ACL) or the setting of the IP Precedence bits through the Modular QoS CLI (MQC). Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 57 Configuring Modular QoS Congestion Management QoS for IPv6 ACLsIf the packet matches the specified classification, the traffic-shaping mechanism continues. Otherwise, no further action is taken. Figure 1 illustrates how a traffic shaping mechanism regulates traffic flow. Figure 3: How a Traffic Shaping Mechanism Regulates Traffic Packets matching the specified criteria are placed in the token bucket. The maximum size of the token bucket is the confirm burst (Bc) size plus the Be size. The token bucket is filled at a constant rate of Bc worth of tokens at every Tc. This is the configured traffic shaping rate. If the traffic shaping mechanism is active (that is, packets exceeding the configured traffic shaping rate already exist in a transmission queue) at every Tc, the traffic shaper checks to see if the transmission queue contains enough packets to send (that is, up to either Bc [or Bc plus Be] worth of traffic). If the traffic shaper is not active (that is, there are no packets exceeding the configured traffic shaping rate in the transmission queue), the traffic shaper checks the number of tokens in the token bucket. One of the following occurs: • If there are enough tokens in the token bucket, the packet is sent (transmitted). • If there are not enough tokensin the token bucket, the packet is placed in a shaping queue for transmission at a later time. Traffic Policing In general, traffic policing allows you to control the maximum rate of traffic sent or received on an interface and to partition a network into multiple priority levels or class of service (CoS). Traffic policing manages the maximum rate of traffic through a token bucket algorithm. The token bucket algorithm uses user-configured values to determine the maximum rate of traffic allowed on an interface at a given moment in time. The token bucket algorithm is affected by all traffic entering or leaving the interface (depending on where the traffic policy with traffic policing is configured) and is useful in managing network bandwidth in cases where several large packets are sent in the same traffic stream. Traffic policing is often configured on interfaces at the edge of a network to limit the rate of traffic entering or leaving the network. In the most common traffic policing configurations, traffic that conforms to the CIR is sent and traffic that exceeds is sent with a decreased priority or is dropped. Users can change these Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 58 OL-26077-02 Configuring Modular QoS Congestion Management Traffic Policingconfiguration optionsto suit their network needs. Traffic policing also provides a certain amount of bandwidth management by allowing you to set the burst size (Bc) for the committed information rate (CIR). When the peak information rate (PIR) is supported, a second token bucket is enforced and then the traffic policer is called a two-rate policer. Regulation of Traffic with the Policing Mechanism This section describes the single-rate and two-rate policing mechanisms. Single-Rate Policer A single-rate, two-action policer provides one token bucket with two actionsfor each packet: a conform action and an exceed action. Figure 2 illustrates how a single-rate token bucket policer marks packets as either conforming or exceeding a CIR, and assigns an action. Figure 4: Marking Packets and Assigning Actions—Single-Rate Policer Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 59 Configuring Modular QoS Congestion Management Regulation of Traffic with the Policing MechanismThe time interval between token updates (Tc) to the token bucket is updated at the CIR value each time a packet arrives at the traffic policer. The Tc token bucket can contain up to the Bc value, which can be a certain number of bytes or a period of time. If a packet of size B is greater than the Tc token bucket, then the packet exceeds the CIR value and a configured action is performed. If a packet of size B is less than the Tc token bucket, then the packet conforms and a different configured action is performed. Two-Rate Policer The two-rate policer manages the maximum rate of traffic by using two token buckets: the committed token bucket and the peak token bucket. The dual-token bucket algorithm uses user-configured values to determine the maximum rate of traffic allowed on a queue at a given moment. In this way, the two-rate policer can meter traffic at two independent rates: the committed information rate (CIR) and the peak information rate (PIR). The committed token bucket can hold bytes up to the size of the committed burst (bc) before overflowing. This token bucket holds the tokens that determine whether a packet conforms to or exceeds the CIR as the following describes: • A traffic stream is conforming when the average number of bytes over time does not cause the committed token bucket to overflow. When this occurs, the token bucket algorithm marks the traffic stream green. • A traffic stream is exceeding when it causes the committed token bucket to overflow into the peak token bucket. When this occurs, the token bucket algorithm marks the traffic stream yellow. The peak token bucket is filled as long as the traffic exceeds the police rate. The peak token bucket can hold bytes up to the size of the peak burst (be) before overflowing. This token bucket holds the tokens that determine whether a packet violates the PIR. A traffic stream is violating when it causes the peak token bucket to overflow. When this occurs, the token bucket algorithm marks the traffic stream red. The dual-token bucket algorithm provides users with three actions for each packet—a conform action, an exceed action, and an optional violate action. Traffic entering a queue with the two-rate policer configured is Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 60 OL-26077-02 Configuring Modular QoS Congestion Management Regulation of Traffic with the Policing Mechanismplaced into one of these categories. Within these three categories, users can decide packet treatments. For instance, packets that conform can be configured to be sent; packets that exceed can be configured to be sent with a decreased priority; and packets that violate can be configured to be dropped. Figure 3 shows how the two-rate policer marks a packet and assigns a corresponding action to the packet. Figure 5: Marking Packets and Assigning Actions—2-Rate Policer For example, if a data stream with a rate of 250 kbps arrives at the two-rate policer, and the CIR is 100 kbps and the PIR is 200 kbps, the policer marks the packet in the following way: • 100 kbps conforms to the rate • 100 kbps exceeds the rate • 50 kbps violates the rate The router updates the tokens for both the committed and peak token buckets in the following way: • The router updatesthe committed token bucket at the CIR value each time a packet arrives at the interface. The committed token bucket can contain up to the committed burst (bc) value. • The router updates the peak token bucket at the PIR value each time a packet arrives at the interface. The peak token bucket can contain up to the peak burst (be) value. • When an arriving packet conforms to the CIR, the router takes the conform action on the packet and decrements both the committed and peak token buckets by the number of bytes of the packet. • When an arriving packet exceeds the CIR, the router takes the exceed action on the packet, decrements the committed token bucket by the number of bytes of the packet, and decrements the peak token bucket by the number of overflow bytes of the packet. • When an arriving packet exceeds the PIR, the router takes the violate action on the packet, but does not decrement the peak token bucket. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 61 Configuring Modular QoS Congestion Management Regulation of Traffic with the Policing MechanismCommitted Bursts and Excess Bursts Unlike a traffic shaper, a traffic policer does not buffer excess packets and transmit them later. Instead, the policer executes a “send or do not send” policy without buffering. During periods of congestion, proper configuration of the excess burst parameter enables the policer to drop packets less aggressively. Therefore, it is important to understand how policing uses the committed (normal) and excess burst values to ensure the router reaches the configured committed information rate (CIR). Burst parameters are based on a generic buffering rule for routers, which recommends that you configure buffering to be equal to the round-trip time bit-rate to accommodate the outstanding TCP windows of all connections in times of congestion. The following sections describe committed bursts and excess bursts, and the recommended formula for calculating each of them: • Committed Bursts • Excess Bursts • Deciding if Packets Conform or Exceed the Committed Rate Committed Bursts The committed burst (bc) parameter of the police command implements the first, conforming (green) token bucket that the router uses to meter traffic. The bc parameter sets the size of this token bucket. Initially, the token bucket is full and the token count is equal to the committed burst size (CBS). Thereafter, the meter updates the token counts the number of times per second indicated by the committed information rate (CIR). The following describes how the meter uses the conforming token bucket to send packets: • Ifsufficient tokens are in the conforming token bucket when a packet arrives, the meter marksthe packet green and decrements the conforming token count by the number of bytes of the packet. • If there are insufficient tokens available in the conforming token bucket, the meter allows the traffic flow to borrow the tokens needed to send the packet. The meter checks the exceeding token bucket for the number of bytes of the packet. If the exceeding token bucket has a sufficient number of tokens available, the meter marks the packet: Green and decrements the conforming token count down to the minimum value of 0. Yellow, borrows the remaining tokens needed from the exceeding token bucket, and decrements the exceeding token count by the number of tokens borrowed down to the minimum value of 0. • If an insufficient number of tokens is available, the meter marks the packet red and does not decrement either of the conforming or exceeding token counts. When the meter marks a packet with a specific color, there must be a sufficient number of tokens of that color to accommodate the entire packet. Therefore, the volume of green packetsis neversmaller than the committed information rate (CIR) and committed burst size (CBS). Tokens of a given color are always used on packets of that color. Note The default committed burst size is the greater of 2 milliseconds of bytes at the police rate or the network maximum transmission unit (MTU). Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 62 OL-26077-02 Configuring Modular QoS Congestion Management Regulation of Traffic with the Policing MechanismCommitted Burst Calculation To calculate committed burst, use the following formula: bc = CIR bps * (1 byte) / (8 bits) * 1.5 seconds Note 1.5 seconds is the typical round-trip time. For example, if the committed information rate is 512000 bps, then using the committed burst formula, the committed burst is 96000 bytes. bc = 512000 * 1/8 * 1.5 bc = 64000 * 1.5 = 96000 When the be value equals 0, we recommend that you set the egress bc value to be greater than or equal to the ingress bc value plus 1. Otherwise, packet loss can occur. For example: be = 0 egress bc >= ingress bc + 1 Note Excess Bursts The excess burst (be) parameter of the police command implements the second, exceeding (yellow) token bucket that the router uses to meter traffic. The exceeding token bucket is initially full and the token count is equal to the excess burst size (EBS). Thereafter, the meter updates the token counts the number of times per second indicated by the committed information rate (CIR). The following describes how the meter uses the exceeding token bucket to send packets: • When the first token bucket (the conforming bucket) meets the committed burst size (CBS), the meter allows the traffic flow to borrow the tokens needed from the exceeding token bucket. The meter marks the packet yellow and then decrements the exceeding token bucket by the number of bytes of the packet. • If the exceeding token bucket does not have the required tokens to borrow, the meter marks the packet red and does not decrement the conforming or the exceeding token bucket. Instead, the meter performs the exceed-action configured in the police command (for example, the policer drops the packets). Excess Burst Calculation To calculate excess burst, use the following formula: be = 2 * committed burst For example, if you configure a committed burst of 4000 bytes, then using the excess burst formula, the excess burst is 8000 bytes. be = 2 * 4000 = 8000 The default excess burst size is 0. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 63 Configuring Modular QoS Congestion Management Regulation of Traffic with the Policing MechanismDeciding if Packets Conform or Exceed the Committed Rate Policing uses normal or committed burst (bc) and excess burst (be) values to ensure that the configured committed information rate (CIR) is reached. Policing decides if a packet conforms or exceeds the CIR based on the burst values you configure. Several factors can influence the policer’s decision, such as the following: • Low burst values—If you configure burst values too low, the achieved rate might be much lower than the configured rate. • Temporary bursts—These bursts can have a strong adverse impact on throughput of Transmission Control Protocol (TCP) traffic. It isimportant that you set the burst values high enough to ensure good throughput. If your router drops packets and reports an exceeded rate even though the conformed rate is less than the configured CIR, use the show interface command to monitor the current burst, determine whether the displayed value is consistently close to the committed burst (bc) and excess burst (be) values, and if the actual rates (the committed rate and exceeded rate) are close to the configured committed rate. If not, the burst values might be too low. Try reconfiguring the burst rates using the suggested calculations in the Committed Burst Calculation and the Excess Burst Calculation. Two-Rate Three-Color (2R3C) Policer For the SIP 700 card, a two-rate, three-color (2R3C) policer is supported on policy maps for ingress Layer 2 interfaces. The policer reads a preexisting marking—the frame-relay discard-eligibility (FRDE) bit in the packet header—that was set by a policer on a previous network node. By default the FRDE bit is set to 0. At the receiving node, the system uses this bit to determine the appropriate color-aware policing action for the packet: • To classify the FRDE bit value 0 as conform color, create a conform-color class-map for frde=0 packets. This causes packets to be classified as color green, and the system applies the conform action. • To classify the FRDE bit value 1 as exceed color, create an exceed-color class-map for frde=1 packets. This causes packets to be classified as color yellow, and the system applies the exceed action. Note Color-aware policing is not supported for heirarchical QoS. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 64 OL-26077-02 Configuring Modular QoS Congestion Management Regulation of Traffic with the Policing MechanismThe 2R3C policing process is shown in Figure 4. Figure 6: 2R3C Policing Process Flowchart Hierarchical Policing The Hierarchical Policing feature is an MQC-based solution that supports hierarchical policing on both the ingress and egress interfaces on Cisco ASR 9000 Series Router. Thisfeature allows enforcement ofservice level agreements(SLA) while applying the classification submodel for different QoS classes on the inbound interface. Hiearchical policing provides support at two levels: • Parent level • Child level Multiple Action Set set-mpls-exp-imp, set-clp Packet Marking Through the IP Precedence Value, IP DSCP Value, and the MPLS Experimental Value Setting In addition to rate-limiting, traffic policing allows you to independently mark (or classify) the packet according to whether the packet conforms or violates a specified rate. Packet marking also allows you to partition your network into multiple priority levels or CoS. Packet marking as a policer action is conditional marking. Use the traffic policer to set the IP precedence value, IP DSCP value, or Multiprotocol Label Switching (MPLS) experimental value for packets that enter the network. Then networking devices within your network can use this setting to determine how the traffic should be treated. For example, the Weighted Random Early Detection (WRED) feature uses the IP precedence value to determine the probability that a packet is dropped. If you want to mark traffic but do not want to use traffic policing, see the “Class-based, Unconditional Packet Marking Examples” section to learn how to perform packet classification. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 65 Configuring Modular QoS Congestion Management Regulation of Traffic with the Policing MechanismNote Marking IP fields on an MPLS-enabled interface results in non-operation on that particular interface. Policer Granularity and Shaper Granularity Policer granularity can be configured in the ingress and egress directions. The policer granularity is specified as a perimissible percentage variation between the user-configured policer rate, and the hardware programmed policer rate. Congestion Management Using DEI You can manage congestion based on the Drop Eligible Indicator (DEI) bit that is present in 802.1ad frames and 802.1ah frames. Random early detection based on the DEI value is supported on 802.1ad packets for: • Layer 2 subinterfaces • Layer 2 main interfaces • Layer 3 main interfaces • Ingress and egress If there are any marking actions in the policy, the marked values are used for doing WRED. Note How to Configure QoS Congestion Management This contains the following tasks: Configuring Guaranteed and Remaining Bandwidths The bandwidth command allows you to specify the minimum guaranteed bandwidth to be allocated for a specific class of traffic. MDRR is implemented as the scheduling algorithm. The bandwidth remaining command specifies a weight for the class to the MDRR. The MDRR algorithm derives the weight for each class from the bandwidth remaining value allocated to the class. If you do not configure the bandwidth remaining command for any class, the leftover bandwidth is allocated equally to all classes for which bandwidth remaining is not explicitly specified. Guaranteed Service rate of a queue is defined as the bandwidth the queue receives when all the queues are congested. It is defined as: Guaranteed Service Rate = minimum bandwidth + excess share of the queue Restrictions The amount of bandwidth configured should be large enough to also accommodate Layer 2 overhead. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 66 OL-26077-02 Configuring Modular QoS Congestion Management Policer Granularity and Shaper GranularityThe bandwidth command is supported only on policies configured on outgoing interfaces. SUMMARY STEPS 1. 2. policy-map policy-name 3. class class-name 4. bandwidth {rate [units]| percent value} 5. bandwidth remaining percent value 6. exit 7. class class-name 8. bandwidth {rate [units] | percent value} 9. bandwidth remaining percent value 10. exit 11. exit 12. interface type interface-path-id 13. service-policy {input | output} policy-map 14. end or commit 15. show policy-map interface type interface-path-id [input | output] DETAILED STEPS Command or Action Purpose Enters global configuration mode. Example: RP/0//CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0//CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RP0/CPU0:router(config-pmap)# class class1 Step 3 Step 4 bandwidth {rate [units]| percent value} Enters policy map class configuration mode. Example: RP/0//CPU0:router(config-pmap-c)# bandwidth percent 50 • Specifies the bandwidth allocated for a class belonging to a policy map. • In this example, class class1 is guaranteed 50 percent of the interface bandwidth. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 67 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsCommand or Action Purpose Step 5 bandwidth remaining percent value Specifies how to allocate leftover bandwidth to various classes. Example: RP/0//CPU0:router(config-pmap-c)# bandwidth remaining percent 20 • The remaining bandwidth of 40 percent isshared by class class1 and class2 (see Steps 8 and 9) in a 20:80 ratio: class class1 receives 20 percent of the 40 percent, and class class2 receives 80 percent of the 40 percent. exit Returns the router to policy map configuration mode. Example: RP/0//CPU0:router(config-pmap-c)# exit Step 6 Specifiesthe name of a different class whose policy you want to create or change. class class-name Example: RP/0//CPU0:router(config-pmap)# class class2 Step 7 Specifies the bandwidth allocated for a class belonging to a policy map. bandwidth {rate [units] | percent value} Example: RP/0//CPU0:router(config-pmap-c)# bandwidth percent 10 Step 8 • In this example, class class2 is guaranteed 10 percent of the interface bandwidth. Step 9 bandwidth remaining percent value Specifies how to allocate leftover bandwidth to various classes. Example: RP/0//CPU0:router(config-pmap-c)# bandwidth remaining percent 80 • The remaining bandwidth of 40 percent isshared by class class1 (see Steps 4 and 5) and class2 in a 20:80 ratio: class class1 receives 20 percent of the 40 percent, and class class2 receives 80 percent of the 40 percent. exit Returns the router to policy map configuration mode. Example: RP/0//CPU0:router(config-pmap-c)# exit Step 10 exit Returns the router to global configuration mode. Example: RP/0//CPU0:router(config-pmap)# exit Step 11 interface type interface-path-id Enters interface configuration mode and configures an interface. Example: RP/0//CPU0:router(config)# interface POS 0/2/0/0 Step 12 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 68 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsCommand or Action Purpose Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0//CPU0:router(config-if)# service-policy output policy1 Step 13 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 14 end or commit Saves configuration changes. Example: RP/0//CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0//CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exitsthe configuration session and returnsthe router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id [input | output] Example: RP/0//CPU0:router# show policy-map interface POS 0/2/0/0 Step 15 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 69 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsConfiguring Guaranteed Bandwidth SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. bandwidth {rate [units]| percent percentage-value} 5. exit 6. class class-name 7. bandwidth {rate [units]| percent percentage-value} 8. exit 9. class class-name 10. bandwidth {rate [units]| percent percentage-value} 11. exit 12. exit 13. interface type interface-path-id 14. service-policy {input | output} policy-map 15. end or commit 16. show policy-map interface type interface-path-id [input | output] DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 Step 3 bandwidth {rate [units]| percent Enters policy map class configuration mode. percentage-value} Step 4 • Specifies the bandwidth allocated for a class belonging to a policy map. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 70 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsCommand or Action Purpose Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth percent 40 • In this example, class class1 is guaranteed 40 percent of the interface bandwidth. exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 5 Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class class2 Step 6 bandwidth {rate [units]| percent Enters policy map class configuration mode. percentage-value} Step 7 • Specifies the bandwidth allocated for a class belonging to a policy map. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth percent 40 • In this example, class class2 is guaranteed 40 percent of the interface bandwidth. exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 8 Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class class-default Step 9 bandwidth {rate [units]| percent Enters policy map class configuration mode. percentage-value} Step 10 • Specifies the bandwidth allocated for a class belonging to a policy map. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth percent 20 • In this example, class class-default is guaranteed 20 percent of the interface bandwidth. exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 11 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 71 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsCommand or Action Purpose exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 12 interface type interface-path-id Enters interface configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/2/0/0 Step 13 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 14 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 15 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id [input | output] Example: RP/0/RSP0/CPU0:router# show policy-map interface gigabitethernet 0/2/0/0 Step 16 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 72 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsConfiguring Bandwidth Remaining SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. bandwidth remaining percent percentage-value 5. exit 6. class class-name 7. bandwidth remaining percent percentage-value 8. exit 9. class class-name 10. bandwidth remaining percent percentage-value 11. exit 12. exit 13. interface type interface-path-id 14. service-policy {input | output} policy-map 15. end or commit 16. show policy-map interface type interface-path-id [input | output] DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 Step 3 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 73 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsCommand or Action Purpose bandwidth remaining percent percentage-value Specifies how to allocate leftover bandwidth for class class1. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth remaining percent 40 Step 4 exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 5 Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class class2 Step 6 bandwidth remaining percent percentage-value Specifies how to allocate leftover bandwidth for class class2. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth remaining percent 40 Step 7 exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 8 Specifies the name of the class whose policy you want to create or change. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class class-default Step 9 Specifies how to allocate leftover bandwidth for class class-default. bandwidth remaining percent percentage-value Example: RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth remaining percent 20 Step 10 exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 11 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 74 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsCommand or Action Purpose exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 12 interface type interface-path-id Entersinterface configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/2/0/0 Step 13 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 14 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 15 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changesto the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id [input | output] Example: RP/0/RSP0/CPU0:router# show policy-map interface gigabitethernet 0/2/0/0 Step 16 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 75 Configuring Modular QoS Congestion Management Configuring Guaranteed and Remaining BandwidthsConfiguring Low-Latency Queueing with Strict Priority Queueing The priority command configures low-latency queueing (LLQ), providing strict priority queueing (PQ). Strict PQ allows delay-sensitive data, such as voice, to be dequeued and sent before packets in other queues are dequeued.When a class is marked as high priority using the priority command, we recommend that you configure a policer to limit the priority traffic. This configuration ensures that the priority traffic does not starve all of the other traffic on the line card, which protectslow priority traffic from starvation. Use the police command to explicitly configure the policer. Two levels of priority are supported: priority level 1 and priority level 2. If no priority level is configured, the default is priority level 1. Note Restrictions • Within a policy map, you can give one or more classes priority status. When multiple classes within a single policy map are configured as priority classes, all traffic from these classes is queued to the same single priority queue. SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-burst peak-burst [burst-units]] [peak-rate value [units]] 5. exceed-action action 6. priority [level priority-level] RP/0/RSP0/CPU0:router(config-pmap-c)# priority 7. exit 8. exit 9. interface type interface-path-id 10. service-policy {input | output} policy-map 11. end or commit 12. show policy-map interface type interface-path-id [input | output] DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 76 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Low-Latency Queueing with Strict Priority QueueingCommand or Action Purpose Example: RP/0/RSP0/CPU0:router(config)# policy-map voice • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class voice • Specifies the name of the class whose policy you want to create or change. Configures traffic policing and enters policy map police configuration mode. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-burst peak-burst [burst-units]] [peak-rate value [units]] Step 4 • In this example, the low-latency queue is restricted to 250 kbps to protect low-priority traffic from starvation and to release bandwidth. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# police rate 250 Step 5 exceed-action action Configuresthe action to take on packetsthat exceed the rate limit. Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# exceed-action drop Specifies priority to a class of traffic belonging to a policy map. exit Returns the router to policy map class configuration mode. Example: RP/0//CPU0:router(config-pmap-c)# priority Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# exit priority [level priority-level] Specifies priority to a class of traffic belonging to a policy map. RP/0/RSP0/CPU0:router(config-pmap-c)# priority Step 6 Note • If no priority level is configured, the default is priority 1. exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 7 exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 8 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 77 Configuring Modular QoS Congestion Management Configuring Low-Latency Queueing with Strict Priority QueueingCommand or Action Purpose interface type interface-path-id Enters interface configuration mode, and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/2/0/0 Step 9 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 10 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 11 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exitsthe configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id [input | output] Example: RP/0/RSP0/CPU0:router# show policy-map interface gigabitethernet 0/2/0/0 Step 12 Configuring Traffic Shaping Traffic shaping allows you to control the traffic exiting an interface to match its transmission to the speed of the remote target interface and ensure that the traffic conforms to policies contracted for it. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 78 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Traffic ShapingShaping performed on incoming and outgoing interfaces is done at the Layer 2 level and includes the Layer 2 header in the rate calculation. Restrictions The bandwidth, priority, and shape average commands should not be configured together in the same class. SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. shape average {percent value | rate [units]} 5. exit 6. exit 7. interface type interface-path-id 8. service-policy {input | output} policy-map 9. end or commit 10. show policy-map interface type interface-path-id [input | output] DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifiesthe name of the class whose policy you want to create or change. Shapes traffic to the indicated bit rate according to average rate shaping in the specified units or as a percentage of the bandwidth. shape average {percent value | rate [units]} Example: RP/0/RSP0/CPU0:router(config-pmap-c)# shape average percent 50 Step 4 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 79 Configuring Modular QoS Congestion Management Configuring Traffic ShapingCommand or Action Purpose exit Returns the router to policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 5 exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 6 interface type interface-path-id Enters interface configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/2/0/0 Step 7 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 8 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 9 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exitsthe configuration session and returnsthe router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id [input | output] Example: RP/0/RSP0/CPU0:router# show policy-map interface gigabitethernet 0/2/0/0 Step 10 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 80 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Traffic ShapingConfiguring Traffic Policing (Two-Rate Color-Blind) Traffic policing allows you to control the maximum rate of traffic sent or received on an interface. Thissection provides the procedure for configuring two-rate color-blind traffic policing. SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-burst peak-burst [burst-units]] [peak-rate value [units]] 5. conform-action action 6. exceed-action action 7. exit 8. exit 9. exit 10. interface type interface-path-id 11. service-policy {input | output} policy-map 12. end or commit 13. show policy-map interface type interface-path-id [input | output] DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 81 Configuring Modular QoS Congestion Management Configuring Traffic Policing (Two-Rate Color-Blind)Command or Action Purpose Configures traffic policing and enters policy map police configuration mode. The traffic policing feature works with a token bucket algorithm. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-burst peak-burst [burst-units]] [peak-rate value [units]] Example: RP/0/RSP0/CPU0:router(config-pmap-c)# police rate 250000 Step 4 Configures the action to take on packets that conform to the rate limit. The action argument is specified by one of these keywords: conform-action action Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# Step 5 • drop—Drops the packet. • set—Has these keywords and arguments: conform-action set mpls experimental topmost 3 discard-class value—Sets the discard class value. Range is 0 to 7. dscp —Sets the differentiated services code point (DSCP) value and sends the packet. mpls experimental {topmost | imposition} value—Setsthe experimental (EXP) value of the Multiprotocol Label Switching (MPLS) packet topmost label or imposed label. Range is 0 to 7. precedence —Sets the IP precedence and sends the packet. qos-group—Sets the QoS group value. Range is 0 to 63. • transmit—Transmits the packets. Configures the action to take on packets that exceed the rate limit. The action argument is specified by one of the keywords specified in Step 5 . exceed-action action Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# Step 6 exceed-action set mpls experimental topmost 4 exit Returns the router to policy map class configuration mode. Example: Step 7 RP/0/RSP0/CPU0:router(config-pmap-c-police)# exit exit Returns the router to policy map configuration mode. Example: Step 8 RP/0/RSP0/CPU0:router(config-pmap-c)# exit Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 82 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Traffic Policing (Two-Rate Color-Blind)Command or Action Purpose exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 9 interface type interface-path-id Enters configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/5/0/0 Step 10 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 11 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 12 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exitsthe configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id [input | output] Example: RP/0/RSP0/CPU0:router# show policy-map interface gigabitethernet 0/2/0/0 Step 13 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 83 Configuring Modular QoS Congestion Management Configuring Traffic Policing (Two-Rate Color-Blind)Configuring Traffic Policing (2R3C) This section provides the procedure for configuring two-rate three-color traffic policing. It is applicable to SIP 700 line cards on the ingress side only. SUMMARY STEPS 1. configure 2. class-map [match-all][match-any] class-map-name 3. match [not] fr-de fr-de-bit-value 4. policy-map policy-name 5. class class-name 6. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-burst peak-burst [burst-units]] [peak-rate value [units]] 7. conform-color class-map-name 8. exceed-color class-map-name 9. conform-action action 10. exceed-action action 11. exit 12. exit 13. exit 14. interface type interface-path-id 15. service-policy policy-map 16. end or commit 17. show policy-map interface type interface-path-id DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 class-map [match-all][match-any] class-map-name (Use with SIP 700 line card, ingress only) Example: RP/0/RSP0/CPU0:router(config)# class-map match-all match-not-frde Enters class map configuration mode. • Creates or modifies a class map that can be attached to one or more interfaces to specify a matching policy. Step 3 match [not] fr-de fr-de-bit-value (Use with SIP 700 line card, ingress only) Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 84 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Traffic Policing (2R3C)Command or Action Purpose Example: RP/0/RSP0/CPU0:router(config)# match not fr-de 1 Specifies the matching condition: • Match not fr-de 1 istypically used to specify a conform-color packet. • Match fr-de 1 is typically used to specify an exceed-color packet. Step 4 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 5 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. Configures traffic policing and enters policy map police configuration mode. The traffic policing feature works with a token bucket algorithm. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-burst peak-burst [burst-units]] [peak-rate value [units]] Example: RP/0/RSP0/CPU0:router(config-pmap-c)# police Step 6 rate 768000 burst 288000 peak-rate 1536000 peak-burst 576000 Step 7 conform-color class-map-name (Use with SIP 700 line card, ingress only) Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# conform-color match-not-frde Configuresthe class-map name to assign to conform-color packets. Step 8 exceed-color class-map-name (Use with SIP 700 line card, ingress only) Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# exceed-color match-frde Configuresthe class-map name to assign to exceed-color packets. Configures the action to take on packets that conform to the rate limit. The action argument is specified by one of these keywords: conform-action action Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# Step 9 • drop—Drops the packet. • set—Has these keywords and arguments: conform-action set mpls experimental topmost 3 discard-class value—Sets the discard class value. Range is 0 to 7. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 85 Configuring Modular QoS Congestion Management Configuring Traffic Policing (2R3C)Command or Action Purpose dscp value—Sets the differentiated services code point (DSCP) value and sends the packet. mpls experimental {topmost | imposition} value—Sets the experimental (EXP) value of the Multiprotocol Label Switching (MPLS) packet topmost label or imposed label. Range is 0 to 7. precedence precedence—Sets the IP precedence and sends the packet. qos-group—Sets the QoS group value. Range is 0 to 63. • transmit—Transmits the packets. Configures the action to take on packets that exceed the rate limit. The action argument isspecified by one of the keywordsspecified in Step 5 . exceed-action action Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# Step 10 exceed-action set mpls experimental topmost 4 exit Returns the router to policy map class configuration mode. Example: Step 11 RP/0/RSP0/CPU0:router(config-pmap-c-police)# exit exit Returns the router to policy map configuration mode. Example: Step 12 RP/0/RSP0/CPU0:router(config-pmap-c)# exit exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 13 interface type interface-path-id Enters configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface pos 0/5/0/0 Step 14 Attaches a policy map to an input interface to be used asthe service policy for that interface. service-policy policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy policy1 Step 15 Step 16 end or commit Saves configuration changes. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 86 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Traffic Policing (2R3C)Command or Action Purpose Example: RP/0/RSP0/CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exitsthe configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id Example: RP/0/RSP0/CPU0:router# show policy-map interface POS0/2/0/0 Step 17 Configuring Hierarchical Policing Hierarchical policing provides support at two levels: • Parent level • Child level SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. service-policy policy-map-name 5. police rate percent percentage 6. conform-action action 7. exceed-action action 8. end or commit Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 87 Configuring Modular QoS Congestion Management Configuring Hierarchical PolicingDETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy policy-map-name Example: RP/0/RSP0/CPU0:router(config-pmap-c)# service-policy child Step 4 Configures traffic policing and enters policy map police configuration mode. police rate percent percentage Example: RP/0/RSP0/CPU0:router(config-pmap-c)# police rate percent 50 Step 5 Configures the action to take on packets that conform to the rate limit. The allowed action is: conform-action action Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# conform-action transmit Step 6 transmit—Transmits the packets. Configures the action to take on packets that exceed the rate limit. The allowed action is: exceed-action action Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# exceed-action drop Step 7 drop—Drops the packet. Step 8 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-if)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 88 OL-26077-02 Configuring Modular QoS Congestion Management Configuring Hierarchical PolicingCommand or Action Purpose or RP/0/RSP0/CPU0:router(config-if)# commit Entering yes saves configuration changes to the running configuration file, exitsthe configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Configuration Examples for configuring congestion management Here are some examples for congestion management. Traffic Shaping for an Input Interface: Example The following example shows how to configure a policy map on an input interface: policy-map p2 class voip shape average 20 mbps ! interface GigabitEthernet0/4/0/24 service-policy input p2 commit RP/0/RSP0/CPU0:Jun 8 16:55:11.819 : config[65546]: %MGBL-LIBTARCFG-6-COMMIT : Configuration committed by user 'cisco'. Use 'show configuration commit changes 1000006140' to view the changes. The following example shows the display output for the previous policy map configuration: RP/0/RSP0/CPU0:router# show policy-map interface GigabitEthernet 0/4/0/24 input GigabitEthernet0/4/0/24 input: p2 Class voip Classification statistics (packets/bytes) (rate - kbps) Matched : 0/0 0 Transmitted : 0/0 0 Total Dropped : 0/0 0 Queueing statistics Queue ID : 268435978 High watermark (Unknown) Inst-queue-len (packets) : 0 Avg-queue-len (Unknown) Taildropped(packets/bytes) : 0/0 Queue(confirm) : 0/0 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 89 Configuring Modular QoS Congestion Management Configuration Examples for configuring congestion managementQueue(exceed) : 0/0 RED random drops(packets/bytes) : 0/0 Class class-default Classification statistics (packets/bytes) (rate - kbps) Matched : : 0/0 0 Transmitted : Un-determined Total Dropped : Un-determined Traffic Policing for a Bundled Interface: Example The following example shows how to configure a policy map for a bundled interface: policy-map p2 class voip police rate percent 20 commit RP/0/RSP0/CPU0:Jun 8 16:51:51.679 : config[65546]: %MGBL-LIBTARCFG-6-COMMIT : Configuration committed by user 'cisco'. Use 'show configuration commit changes 1000006135' to view the changes. exit exit interface bundle-ether 1 service-policy input p2 commit RP/0/RSP0/CPU0:Jun 8 16:52:02.650 : config[65546]: %MGBL-LIBTARCFG-6-COMMIT : Configuration committed by user 'cisco'. Use 'show configuration commit changes 1000006136' to view the changes. The following example shows the display output for the policy map configuration in which policing was configured in percentage: RP/0/RSP0/CPU0:router# show policy-map interface bundle-ether 1 Bundle-ether1 input: p2 Class voip Classification statistics (packets/bytes) (rate - kbps) Matched : 0/0 0 Policing statistics (packets/bytes) (rate - kbps) Policed(conform) : 0/0 0 Policed(exceed) : 0/0 0 Policed(violate) : 0/0 0 Policed and dropped : 0/0 Class default Classification statistics (packets/bytes) (rate - kbps) Matched : 0/0 0 Transmitted : 0/0 0 Total Dropped : 0/0 0 Queueing statistics Vital (packets) : 0 Queueing statistics Queue ID : 36 High watermark (packets) : 0 Inst-queue-len (bytes) : 0 Avg-queue-len (bytes) : 0 TailDrop Threshold(bytes) : 239616000 Taildropped(packets/bytes) : 0/0 2R3C Traffic Policing: Example These commands create the color-aware policy. ! class-map match-any match-frde-0 match not fr-de 1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 90 OL-26077-02 Configuring Modular QoS Congestion Management Traffic Policing for a Bundled Interface: Exampleend-class-map ! class-map match-any match-frde-1 match fr-de 1 end-class-map ! ! policy-map color-aware-policer class class-default police rate 1000 kbps peak-rate 2000 kbps conform-color match-frde-0 exceed-color match-frde-1 conform-action set qos-group 10 exceed-action set qos-group 20 violate-action drop ! ! end-policy-map ! ! interface POS0/1/0/0 encapsulation frame-relay pos crc 32 ! frame-relay lmi disable ! interface POS0/1/0/0.1 l2transport pvc 100 service-policy input color-aware-policer ! ! This command displays the current configuration commands for the policy. RP/0/RSP0/CPU0:router# show run policy-map color-aware-policer Thu Apr 14 09:25:04.752 UTC policy-map color-aware-policer class class-default police rate 1000 kbps peak-rate 2000 kbps conform-color match-frde-0 exceed-color match-frde-1 conform-action set qos-group 10 exceed-action set qos-group 20 violate-action drop ! ! end-policy-map ! This command displays the color-aware policy. /0/RSP0/CPU0:router# show policy-map interface pos 0/1/0/0.1 input Thu Apr 14 09:24:10.487 UTC POS0/1/0/0.1 input: color-aware-policer Class class-default Classification statistics (packets/bytes) (rate - kbps) Matched : 66144900/8201967600 498245 Transmitted : N/A Total Dropped : 65879175/8169017700 496245 Policing statistics (packets/bytes) (rate - kbps) Policed(conform) : 132863/16475012 1000 Policed(exceed) : 132863/16475012 1000 Policed(violate) : 65879175/8169017700 496245 Policed and dropped : 65879175/8169017700 Conform Color Policed(conform) : 132863/16475012 1000 Policed(exceed) : 51367/6369508 389 Policed(violate) : 46186826/5727166424 347907 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 91 Configuring Modular QoS Congestion Management 2R3C Traffic Policing: ExampleExceed Color Policed(exceed) : 81496/10105504 611 Policed(violate) : 19692349/2441851276 148338 Violate Color Policed(violate) : 0/0 0 ATM QoS: Example Hierarchical Policing: Example Additional References The following sections provide references related to implementing QoS congestion management. Related Documents Related Topic Document Title Cisco ASR 9000 Series Aggregation Services Router Getting Started Guide Initial system bootup and configuration Cisco ASR 9000 Series Aggregation Services Router Master Command Listing Master command reference Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference QoS commands “Configuring AAA Services on Cisco ASR 9000 Series Router” module of Cisco Cisco ASR 9000 Series Aggregation Services Router System Security Configuration Guide User groups and task IDs Standards Standards Title No new or modified standards are supported by — this feature, and support for existing standards has not been modified by this feature. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 92 OL-26077-02 Configuring Modular QoS Congestion Management ATM QoS: ExampleMIBs MIBs MIBs Link To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/ cmtk/mibs.shtml — RFCs RFCs Title No new or modified RFCs are supported by this — feature, and support for existing RFCs has not been modified by this feature. Technical Assistance Description Link The Cisco Technical Support website contains http://www.cisco.com/techsupport thousands of pages of searchable technical content, including links to products, technologies,solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 93 Configuring Modular QoS Congestion Management MIBs Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 94 OL-26077-02 Configuring Modular QoS Congestion Management Technical AssistanceC H A P T E R 5 Configuring Modular QoS Service Packet Classification Packet classification identifies and marks traffic flows that require congestion management or congestion avoidance on a data path. The Modular Quality of Service (QoS) command-line interface (MQC) is used to define the traffic flows that should be classified, where each traffic flow is called a class of service, or class. Subsequently, a traffic policy is created and applied to a class. All traffic not identified by defined classes falls into the category of a default class. This module provides the conceptual and configuration information for QoS packet classification. Line Card, SIP, and SPA Support Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 Classification Based on DEI yes no Class-Based Unconditional Packet yes yes Marking In-Place Policy Modification yes yes IPv6 QoS yes yes Packet Classification and Marking yes yes Policy Inheritance yes yes Port Shape Policies yes no Shared Policy Instance yes no Feature History for Configuring Modular QoS Packet Classification and Marking on Cisco ASR 9000 Series Routers Release Modification Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 95The Class-Based Unconditional Packet Marking feature was introduced on ASR 9000 Ethernet Line Cards. The IPv6 QoS feature wasintroduced on ASR 9000 Ethernet Line Cards. (QoS matching on IPv6 ACLs is not supported.) The Packet Classification and Marking feature was introduced on ASR 9000 Ethernet Line Cards. Release 3.7.2 The Class-Based Unconditional Packet Marking feature was supported on the SIP 700 for the ASR 9000. The Packet Classification and Marking feature was supported on the SIP 700 for the ASR 9000. The Policy Inheritance feature was introduced on ASR 9000 Ethernet Line Cards and on the SIP 700 for the ASR 9000. The Shared Policy Instance feature was introduced on ASR 9000 Ethernet Line Cards. Release 3.9.0 The Classification Based on DEI feature wasintroduced on ASR 9000 Ethernet Line Cards. The In-Place PolicyModification feature wasintroduced on ASR 9000 Ethernet Line Cards and on the SIP 700 for the ASR 9000. The IPv6 QoS feature was supported on the SIP 700 for the ASR 9000. Support for three stand-alone marking actions and three marking actions as part of a policer action in the same class was added on the SIP 700 for the ASR 9000. (ASR 9000 Ethernet Line Cardssupport two stand-alone marking actions and two marking actions as part of a policer action in the same class.) Release 4.0.0 Support for the port shape policies feature was introduced on ASR 9000 Ethernet Line Cards. Release 4.0.1 Release 4.2.1 QoS on satellite feature was added. • Prerequisites for Configuring Modular QoS Packet Classification, page 96 • Information About Configuring Modular QoS Packet Classification, page 97 • How to Configure Modular QoS Packet Classification, page 107 • Configuration Examples for Configuring Modular QoS Packet Classification, page 129 • Additional References, page 135 Prerequisites for Configuring Modular QoS Packet Classification The following prerequisites are required for configuring modular QoS packet classification and marking on your network: Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 96 OL-26077-02 Configuring Modular QoS Service Packet Classification Prerequisites for Configuring Modular QoS Packet Classification• You must be in a user group associated with a task group that includes the proper task IDs.The command reference guides include the task IDs required for each command. If you suspect user group assignment is preventing you from using a command, contact your AAA administrator for assistance. • You must be familiar with Cisco IOS XR QoS configuration tasks and concepts. Information About Configuring Modular QoS Packet Classification To implement QoS packet classification featuresin this document, you must understand the following concepts: Packet Classification Overview Packet classification involves categorizing a packet within a specific group (or class) and assigning it a traffic descriptor to make it accessible for QoS handling on the network. The traffic descriptor contains information about the forwarding treatment (quality of service) that the packet should receive. Using packet classification, you can partition network traffic into multiple priority levels or classes of service. The source agrees to adhere to the contracted terms and the network promises a quality of service. Traffic policers and traffic shapers use the traffic descriptor of a packet to ensure adherence to the contract. Traffic policers and traffic shapers rely on packet classification features, such as IP precedence, to select packets (or traffic flows) traversing a router or interface for different types of QoS service. For example, by using the three precedence bits in the type of service (ToS) field of the IP packet header, you can categorize packets into a limited set of up to eight traffic classes. After you classify packets, you can use other QoS features to assign the appropriate traffic handling policies including congestion management, bandwidth allocation, and delay bounds for each traffic class. Note IPv6-based classification is supported only on Layer 3 interfaces. Traffic Class Elements The purpose of a traffic class is to classify traffic on your router. Use the class-map command to define a traffic class. A traffic class contains three major elements: a name, a series of match commands, and, if more than one match command exists in the traffic class, an instruction on how to evaluate these match commands. The traffic class is named in the class-map command. For example, if you use the word cisco with the class-map command, the traffic class would be named cisco. The match commands are used to specify various criteria for classifying packets. Packets are checked to determine whether they match the criteria specified in the match commands. If a packet matches the specified criteria, that packet is considered a member of the class and is forwarded according to the QoS specifications set in the traffic policy. Packets that fail to meet any of the matching criteria are classified as members of the default traffic class. See the Default Traffic Class. The instruction on how to evaluate these match commands needs to be specified if more than one match criterion exists in the traffic class. The evaluation instruction is specified with the class-map match-any Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 97 Configuring Modular QoS Service Packet Classification Information About Configuring Modular QoS Packet Classificationcommand. If the match-any option is specified as the evaluation instruction, the traffic being evaluated by the traffic class must match at least one of the specified criteria. If the match-all option is specified, the traffic must match all of the match criteria. The function of these commands is described more thoroughly in the Cisco ASR 9000 Series Aggregation Services Routers Modular Quality of Service Command Reference. The traffic class configuration task is described in the Creating a Traffic Class. Traffic Policy Elements The purpose of a traffic policy is to configure the QoS features that should be associated with the traffic that has been classified in a user-specified traffic class or classes. The policy-map command is used to create a traffic policy. A traffic policy contains three elements: a name, a traffic class (specified with the class command), and the QoS policies. The name of a traffic policy is specified in the policy map Modular Quality of Service (MQC) (for example, the policy-map policy1 command creates a traffic policy named policy1). The traffic classthat is used to classify traffic to the specified traffic policy is defined in class map configuration mode. After choosing the traffic class that is used to classify traffic to the traffic policy, the user can enter the QoS features to apply to the classified traffic. The MQC does not necessarily require that users associate only one traffic class to one traffic policy. When packets match to more than one match criterion, as many as 1024 traffic classes can be associated to a single traffic policy. The 1024 class maps include the default class and the classes of the child policies, if any. The order in which classes are configured in a policy map is important. The match rules of the classes are programmed into the TCAM in the order in which the classes are specified in a policy map. Therefore, if a packet can possibly match multiple classes, only the first matching class is returned and the corresponding policy is applied. The function of these commands is described more thoroughly in the Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference. The traffic policy configuration task is described in Creating a Traffic Policy. Default Traffic Class Unclassified traffic (traffic that does not meet the match criteria specified in the traffic classes) is treated as belonging to the default traffic class. If the user does not configure a default class, packets are still treated as members of the default class. However, by default, the default class has no enabled features. Therefore, packets belonging to a default class with no configured features have no QoS functionality. These packets are then placed into a first in, first out (FIFO) queue and forwarded at a rate determined by the available underlying link bandwidth. This FIFO queue is managed by a congestion avoidance technique called tail drop. For further information about congestion avoidance techniques, such as tail drop, see the “Configuring Modular QoS Congestion Avoidance on Cisco ASR 9000 Series Routers” module in this guide Bundle Traffic Policies When a policy is bound to a bundle, the same policy is programmed on every bundle member (port). For example, if there is a policer or shaper rate, the same rate is configured on every port. Traffic is scheduled to bundle members based on the load balancing algorithm. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 98 OL-26077-02 Configuring Modular QoS Service Packet Classification Traffic Policy ElementsA policy can be bound to: • Bundles • Bundle Layer 3 subinterfaces • Bundle Layer 2 subinterfaces (Layer 2 transport) Both ingress and egress traffic is supported. Percentage-based policies and absolute rate-based policies are supported. However, for ease of use, it is recommended to use percentage-based policies. Shared Policy Instance After the traffic class and traffic policy have been created, Shared Policy Instance (SPI) can optionally be used to allow allocation of a single set of QoS resources and share them across a group of subinterfaces, multiple Ethernet flow points (EFPs), or bundle interfaces. Using SPI, a single instance of qos policy can be shared across multiple subinterfaces, allowing for aggregate shaping of the subinterfaces to one rate. All of the subinterfaces that share the instance of a QoS policy must belong to the same physical interface. The number of subinterfaces sharing the QoS policy instance can range from 2 to the maximum number of subinterfaces on the port. For bundle interfaces, hardware resources are replicated per bundle member. All subinterfaces that use a common shared policy instance and are configured on a Link Aggregation Control Protocol (LAG) bundle must be load-balanced to the same member link. When a policy is configured on a bundle EFP, one instance of the policy is configured on each of the bundle member links. When using SPI across multiple bundle EFPs of the same bundle, one shared instance of the policy is configured on each of the bundle member links. By default, the bundle load balancing algorithm uses hashing to distribute the traffic (that needs to be sent out of the bundle EFPs) among its bundle members. The traffic for single or multiple EFPs can get distributed among multiple bundle members. If multiple EFPs have traffic that needsto be shaped or policed together usingSPI, the bundle load balancing hasto be configured to select the same bundle member (hash-select) for traffic to all the EFPs that belong the same shared instance of the policy. This ensures that traffic going out on all the EFPs with same shared instance of the policy use the same policer/shaper Instance. This is normally used when the same subscriber has many EFPs, for example, one EFP for each service type, and the provider requires shaping and queuing to be implemented together for all the subscriber EFPs. Policy Inheritance When a policy map is applied on a physical port, the policy is enforced for all Layer 2 and Layer 3 subinterfaces under that physical port. Port Shape Policies When a port shaping policy is applied to a main interface, individual regular service policies can also be applied on its subinterfaces. Port shaping policy maps have the following restrictions: • class-default is the only allowed class map. • The shape class action is the only allowed class action. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 99 Configuring Modular QoS Service Packet Classification Shared Policy Instance• They can only be configured in the egress direction. • They can only be applied to main interfaces, not to subinterfaces. • Two- and three- level policies are not supported. Only one level or flat policies are supported. If any of the above restrictions are violated, the configured policy map isapplied as a regular policy, not a port shaping policy. Class-based Unconditional Packet Marking Feature and Benefits The Class-based, Unconditional Packet Marking feature provides users with a means for efficient packet marking by which the users can differentiate packets based on the designated markings. The Class-based, Unconditional Packet Marking feature allows users to perform the following tasks: • Mark packets by setting the IP precedence bits or the IP differentiated services code point (DSCP) in the IP ToS byte. • Mark Multiprotocol Label Switching (MPLS) packets by setting the EXP bits within the imposed or topmost label. • Mark packets by setting the Layer 2 class-of-service (CoS) value. • Mark packets by setting inner and outer CoS tags for an IEEE 802.1Q tunneling (QinQ) configuration. • Mark packets by setting the value of the qos-group argument. • Mark packets by setting the value of the discard-class argument. Note qos-group and discard-class are variables internal to the router, and are not transmitted. Unconditional packet marking allows you to partition your network into multiple priority levels or classes of service, as follows: • Use QoS unconditional packet marking to set the IP precedence or IP DSCP values for packets entering the network. Routers within your network can then use the newly marked IP precedence values to determine how the traffic should be treated. For example, weighted random early detection (WRED), a congestion avoidance technique, can be used to determine the probability that a packet is dropped. In addition, low-latency queueing (LLQ) can then be configured to put all packets of that mark into the priority queue. • Use QoS unconditional packet marking to assign packetsto a QoS group. To set the QoS group identifier on MPLS packets, use the set qos-group command in policy map class configuration mode. Setting the QoS group identifier does not automatically prioritize the packets for transmission. You must first configure an egress policy that uses the QoS group. Note • Use CoS unconditional packet marking to assign packets to set the priority value of IEEE 802.1p/ Inter-Switch Link (ISL) packets. The router uses the CoS value to determine how to prioritize packets Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 100 OL-26077-02 Configuring Modular QoS Service Packet Classification Class-based Unconditional Packet Marking Feature and Benefitsfor transmission and can use this marking to perform Layer 2-to-Layer 3 mapping. To set the Layer 2 CoS value of an outgoing packet, use the set cos command in policy map configuration mode. The configuration task is described in the Configuring Class-based Unconditional Packet Marking. Unless otherwise indicated, the class-based unconditional packet marking for Layer 3 physical interfaces applies to bundle interfaces. Note Specification of the CoS for a Packet with IP Precedence Use of IP precedence allows you to specify the CoS for a packet. You use the three precedence bits in the ToS field of the IP version 4 (IPv4) header for this purpose. Figure 1 shows the ToS field. Figure 7: IPv4 Packet Type of Service Field Using the ToS bits, you can define up to eight classes of service. Other features configured throughout the network can then use these bits to determine how to treat the packet in regard to the ToS to grant it. These other QoS features can assign appropriate traffic-handling policies, including congestion managementstrategy and bandwidth allocation. For example, queueing features such as LLQ can use the IP precedence setting of the packet to prioritize traffic. By setting precedence levels on incoming traffic and using them in combination with the Cisco IOS XR QoS queueing features, you can create differentiated service. So that each subsequent network element can provide service based on the determined policy, IP precedence is usually deployed as close to the edge of the network or administrative domain as possible. This allows the rest of the core or backbone to implement QoS based on precedence. The configuration task is described in the Configuring Class-based Unconditional Packet Marking. IP Precedence Bits Used to Classify Packets Use the three IP precedence bits in the ToS field of the IP header to specify the CoS assignment for each packet. As mentioned earlier, you can partition traffic into a maximum of eight classes and then use policy maps to define network policies in terms of congestion handling and bandwidth allocation for each class. For historical reasons, each precedence corresponds to a name. These names are defined in RFC 791. Table 5 lists the numbers and their corresponding names, from least to most important. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 101 Configuring Modular QoS Service Packet Classification Specification of the CoS for a Packet with IP PrecedenceTable 2: IP Precedence Values Number Name 0 routine 1 priority 2 immediate 3 flash 4 flash-override 5 critical 6 internet 7 network Note IP precedence bit settings 6 and 7 are reserved for network control information, such as routing updates. IP Precedence Value Settings By default, Cisco IOS XR software leaves the IP precedence value untouched. This preserves the precedence value set in the header and allows all internal network devices to provide service based on the IP precedence setting. This policy followsthe standard approach stipulating that network traffic should be sorted into various types of service at the edge of the network and that those types of service should be implemented in the core of the network. Routers in the core of the network can then use the precedence bits to determine the order of transmission, the likelihood of packet drop, and so on. Because traffic coming into your network can have the precedence set by outside devices, we recommend that you reset the precedence for all traffic entering your network. By controlling IP precedence settings, you prohibit users that have already set the IP precedence from acquiring better service for their traffic simply by setting a high precedence for all of their packets. The class-based unconditional packet marking, LLQ, and WRED features can use the IP precedence bits. Classification Based on DEI You can classify traffic based on the Drop Eligible Indicator (DEI ) bit that is present in 802.1ad frames and in 802.1ah frames. Default DEI marking is supported. The set DEI action in policy maps is supported on 802.1ad packets for: • Ingress and egress • Layer 2 subinterfaces Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 102 OL-26077-02 Configuring Modular QoS Service Packet Classification Classification Based on DEI• Layer 2 main interfaces • Layer 3 main interfaces The set DEI action isignored for traffic on interfacesthat are not configured for 802.1ad encapsulation. Note Default DEI Marking Incoming Packet Default DEI on Imposed 802.1ad Headers 802.1q packet None 0 802.1ad packet None DEI of top-most tag of the incoming packet 0 or 1 Based on DEI value in the set action 802.1q packet translated to set dei {0 | 1} 802.1ad packet or 802.1ad packet IP Precedence Compared to IP DSCP Marking If you need to mark packets in your network and all your devices support IP DSCP marking, use the IP DSCP marking to mark your packets because the IP DSCP markings provide more unconditional packet marking options. If marking by IP DSCP is undesirable, however, or if you are unsure if the devices in your network support IP DSCP values, use the IP precedence value to mark your packets. The IP precedence value is likely to be supported by all devices in the network. You can set up to 8 different IP precedence markings and 64 different IP DSCP markings. QoS Policy Propagation Using Border Gateway Protocol Packet classification identifies and marks traffic flows that require congestion management or congestion avoidance on a data path. Quality-of-service Policy Propagation Using Border Gateway Protocol (QPPB) allows you to classify packets by Qos Group ID, based on access lists (ACLs), Border Gateway Protocol (BGP) community lists, BGP autonomous system (AS) paths, Source Prefix address, or Destination Prefix address. After a packet has been classified, you can use other QoS features such as policing and weighted random early detection (WRED) to specify and enforce policies to fit your business model. QoS Policy Propagation Using BGP (QPPB) allows you to map BGP prefixes and attributes to Cisco Express Forwarding (CEF) parameters that can be used to enforce traffic policing. QPPB allows BGP policy set in one location of the network to be propagated using BGP to other parts of the network, where appropriate QoS policies can be created. QPPB allows you to classify packets based on the following: Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 103 Configuring Modular QoS Service Packet Classification IP Precedence Compared to IP DSCP Marking• Access lists. • BGP community lists. You can use community lists to create groups of communities to use in a match clause of a route policy. As with access lists, you can create a series of community lists. • BGP autonomous system paths. You can filter routing updates by specifying an access list on both incoming and outbound updates, based on the BGP autonomous system path. • Source Prefix address. You can classify a set of prefixes coming from the address of a BGP neighbor(s). • Destination Prefix address. You can classify a set of BGP prefixes. Classification can be based on the source or destination address of the traffic. BGP and CEF must be enabled for the QPPB feature to be supported. QoS on the Satellite System AutoQoS which automates consistent deployment of QoS features is enabled on the satellite system. All the user-configured Layer2 and Layer3 QoS features are applied on the ASR9000 and no separate Qos configuration required for the satellite system. Auto-Qos handles the over-subscription of the ICL links. All other QoS features, including broadband QoS, on regular ports are supported on satellite ports as well. System congestion handling between the ASR9000 Series Router and satellite ports is setup to maintain priority and protection. AutoQoS Provide sufficient differentiation between different classes of traffic that flow on the satellite ICLs between the ASR9000 Series Router and the Satellite box. Note Queueing on an ingress service-policy is not supported on satellite interfaces. Auto QoS Traffic from the satellite system to the Cisco IOS XR ASR9000 series router and traffic from the ASR9000 series router to the satellite system have been discussed. Satellite to ASR9000 series router • Traffic is handled using the trusted port model. • Automatic packet classification rules determine whether a packet is control packet (LACP, STP, CDP, CFM, ARP, OSPF etc), high priority data (VLAN COS 5,6,7, IP prec 5, 6, 7) or normal priority data and queued accordingly. • Protocol types auto-prioritized by the satellite - all IEEE control protocols (01 80 C2 xx xx xx), LACP, 802.3ah, CFM, STP, CDP, LLDP, ARP, OSPF, RIP, BGP, IGMP, RSVP, HSRP, VRRP p2 q. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 104 OL-26077-02 Configuring Modular QoS Service Packet Classification QoS on the Satellite System• User data packets auto-prioritized by the satellite - VLAN COS 5, 6, 7, IP precedence 5, 6, 7 MPLS EXP 5, 6, 7. Figure 8: AutoQoS, satellite to host ASR9000 series router to satellite • Traffic targeted to a satellite egress port is shaped on ASR9K to match downstream access port speed. • Traffic is streamed based on the full 3-level egress queuing hierarchy. • Each remotely managed satellite access GigE port is auto-shaped to match access line speed. Figure 9: AutoQoS, host to satellite Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 105 Configuring Modular QoS Service Packet Classification QoS on the Satellite SystemIn-Place Policy Modification The In-Place Policy Modification feature allows you to modify a QoS policy even when the QoS policy is attached to one or more interfaces. When you modify the QoS policy attached to one or more interfaces, the QoS policy is automatically modified on all the interfaces to which the QoS policy is attached. A modified policy is subject to the same checks that a new policy is subject to when it is bound to an interface. If the policy-modification is successful, the modified policy takes effect on all the interfaces to which the policy is attached. The configuration session is blocked until the policy modification is complete. However, if the policy modification fails on any one of the interfaces, an automatic rollback is initiated to ensure that the pre-modification policy is in effect on all the interfaces. The configuration session is blocked until the rollback is complete on all affected interfaces. If unrecoverable errors occur during in-place policy modification, the policy is put into an inconsistent state on target interfaces. Use the show qos inconsistency command to view inconsistency in each location. (This command is supported only on ASR 9000 Ethernet Line Cards). The configuration session is blocked until the modified policy is effective on all interfaces that are using the policy. No new configuration is possible until the configuration session is unblocked. When a QoS policy attached to an interface is modified, there might not be any policy in effect on the interfaces in which the modified policy is used for a short period of time. The QoS statistics for the policy that is attached to an interface are lost (reset to 0) when the policy is modified. Note Modifications That Can Trigger In-Place Policy Modifications Modifications to QoS Policies • Add new actions, such as bandwidth or police • Add new service policies (increasing the hierarchy level) • Remove existing actions • Modify existing actions • Remove service-policies (decreasing the hierarchy level) • Add new classes along with new actions • Add or remove multiple classes in the policy • Modify a child policy Modifications to Class Maps • Add new match statements • Remove existing match statements Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 106 OL-26077-02 Configuring Modular QoS Service Packet Classification In-Place Policy Modification• Change the match type (from match-all to match-any, and vice versa) • Modify existing match statements Modifications to Access Lists Used in Class Maps • Add new access control entries (ACEs) • Remove ACEs • Modify ACEs Recommendations for Using In-Place Policy Modification For a short period of time while a QoS policy is being modified, there might not be any policy in effect on the interfaces in which the modified policy is used. For this reason, modify QoS policies that affect the fewest number of interfaces at a time. Use the show policy-map targets command to identify the number of interfaces that will be affected during policy map modification. Dynamic Modification of Interface Bandwidth This section describes the dynamic modification of interface bandwidth feature. Policy States • Verification—This state indicates an incompatibility of the configured QoS policy with respect to the new interface bandwidth value. The system handles traffic on a best-efforts basis and some traffic drops can occur. How to Configure Modular QoS Packet Classification This section contains instructions for the following tasks: Creating a Traffic Class To create a traffic class containing match criteria, use the class-map command to specify the traffic class name, and then use the following match commands in class-map configuration mode, as needed. For conceptual information, see the Traffic Class Elements. Restrictions All match commands specified in this configuration task are considered optional, but you must configure at least one match criterion for a class. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 107 Configuring Modular QoS Service Packet Classification Dynamic Modification of Interface BandwidthSUMMARY STEPS 1. configure 2. class-map [type qos] [match-any] [match-all] class-map-name 3. match access-group [ipv4 | ipv6] access-group-name 4. match [not] cos [cos-value] [cos-value0 ... cos-value7] 5. match [not] cos inner [inner-cos-value] [inner-cos-value0...inner-cos-value7] 6. match destination-address mac destination-mac-address 7. match source-address mac source-mac-address 8. match [not] discard-class discard-class-value [discard-class-value1 ... discard-class-value6] 9. match [not] dscp [ipv4 | ipv6] dscp-value [dscp-value ... dscp-value] 10. match [not] mpls experimental topmost exp-value [exp-value1 ... exp-value7] 11. match [not] precedence [ipv4 | ipv6] precedence-value [precedence-value1 ... precedence-value6] 12. match [not] protocol protocol-value [protocol-value1 ... protocol-value7] 13. match [not] qos-group [qos-group-value1 ... qos-group-value8] 14. match vlan [inner] vlanid [vlanid1 ... vlanid7] 15. Use one of these commands: • end • commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 class-map [type qos] [match-any] [match-all] Enters class map configuration mode. class-map-name Step 2 • Creates a class map to be used for matching packets to the class whose name you specify. Example: RP/0/RSP0/CPU0:router(config)# class-map class201 • If you specific match-any, one of the match criteria must be met for traffic entering the traffic class to be classified as part of the traffic class. Thisisthe default. If you specify match-all, the traffic must match all the match criteria. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 108 OL-26077-02 Configuring Modular QoS Service Packet Classification Creating a Traffic ClassCommand or Action Purpose (Optional) Configures the match criteria for a class map based on the specified access control list (ACL) name. match access-group [ipv4 | ipv6] access-group-name Example: RP/0/RSP0/CPU0:router(config-cmap)# match access-group ipv4 map1 Step 3 match [not] cos [cos-value] [cos-value0 ... (Optional) Specifies a cos-value in a class map to match packets. cos-value7] Step 4 • cos-value arguments are specified as an integer from 0 to 7. Example: RP/0/RSP0/CPU0:router(config-cmap)# match cos 5 (Optional) Specifies an inner-cos-value in a class map to match packets. match [not] cos inner [inner-cos-value] [inner-cos-value0...inner-cos-value7] Step 5 Example: RP/0/RSP0/CPU0:router match cos inner 7 • inner-cos-value arguments are specified as an integer from 0 to 7. (Optional) Configures the match criteria for a class map based on the specified destination MAC address. match destination-address mac destination-mac-address Example: RP/0/RSP0/CPU0:router(config-cmap)# match destination-address mac 00.00.00 Step 6 (Optional) Configures the match criteria for a class map based on the specified source MAC address. match source-address mac source-mac-address Example: RP/0/RSP0/CPU0:router(config-cmap)# match source-address mac 00.00.00 Step 7 (Optional) Specifies a discard-class-value in a class map to match packets. match [not] discard-class discard-class-value [discard-class-value1 ... discard-class-value6] Step 8 Example: RP/0/RSP0/CPU0:router(config-cmap)# match discard-class 5 • discard-class-value argument is specified as an integer from 0 to 7. The match discard-class command is supported only for an egress policy. match [not] dscp [ipv4 | ipv6] dscp-value (Optional) Identifies a specific DSCP value as a match criterion. [dscp-value ... dscp-value] Step 9 • Value range is from 0 to 63. Example: RP/0/RSP0/CPU0:router(config-cmap)# match dscp ipv4 15 • Reserved keywords can be specified instead of numeric values. • Up to eight values or ranges con be used per match statement. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 109 Configuring Modular QoS Service Packet Classification Creating a Traffic ClassCommand or Action Purpose (Optional) Configure a class map so that the three-bit experimental field in the topmost Multiprotocol Label Switching (MPLS) labels are examined for experimental (EXP) field values. match [not] mpls experimental topmost exp-value [exp-value1 ... exp-value7] Example: RP/0/RSP0/CPU0:router(config-cmap)# match mpls experimental topmost 3 Step 10 The value range is from 0 to 7. match [not] precedence [ipv4 | ipv6] (Optional) Identifies IP precedence values as match criteria. precedence-value [precedence-value1 ... precedence-value6] Step 11 • Value range is from 0 to 7. Example: RP/0/RSP0/CPU0:router(config-cmap)# match precedence ipv4 5 • Reserved keywords can be specified instead of numeric values. (Optional) Configuresthe match criteria for a class map on the basis of the specified protocol. match [not] protocol protocol-value [protocol-value1 ... protocol-value7] Example: RP/0/RSP0/CPU0:router(config-cmap)# match protocol igmp Step 12 (Optional) Specifies service (QoS) group values in a class map to match packets. match [not] qos-group [qos-group-value1 ... qos-group-value8] Step 13 Example: RP/0/RSP0/CPU0:router(config-cmap)# match qos-group 1 2 3 4 5 6 7 8 • qos-group-value identifier argument is specified as the exact value or range of values from 0 to 63. • Up to eight values (separated by spaces) can be entered in one match statement. • match qos-group command is supported only for an egress policy. (Optional) Specifies a VLAN ID or range of VLAN IDs in a class map to match packets. match vlan [inner] vlanid [vlanid1 ... vlanid7] Example: RP/0/RSP0/CPU0:router(config-cmap)# match vlan vlanid vlanid1 Step 14 • vlanid is specified as an exact value or range of values from 1 to 4094. • Total number of supported VLAN values or ranges is 8. Step 15 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config)# end Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 110 OL-26077-02 Configuring Modular QoS Service Packet Classification Creating a Traffic ClassCommand or Action Purpose ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config)# commit ? Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. ? Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Creating a Traffic Policy To create a traffic policy, use the policy-map global configuration command to specify the traffic policy name. The traffic class is associated with the traffic policy when the class command is used. The class command must be issued after you enter the policy map configuration mode. After entering the class command, the router is automatically in policy map class configuration mode, which is where the QoS policies for the traffic policy are defined. The following class-actions are supported: • bandwidth—Configures the bandwidth for the class. See the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module in this guide. • police—Police traffic. See the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module in this guide. • priority—Assigns priority to the class. See the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module in this guide. • queue-limit—Configures queue-limit (tail drop threshold) for the class. See the “Configuring Modular QoS Congestion Avoidance on Cisco ASR 9000 Series Routers” module in this guide. • random-detect—Enables Random Early Detection. See the “Configuring Modular QoS Congestion Avoidance on Cisco ASR 9000 Series Routers” module in this guide. • service-policy—Configures a child service policy. • set—Configures marking for this class. See the Class-based Unconditional Packet Marking Feature and Benefits. • shape—Configures shaping for the class. See the “Configuring Modular Quality of Service Congestion Management on Cisco ASR 9000 Series Routers” module in this guide. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 111 Configuring Modular QoS Service Packet Classification Creating a Traffic PolicyFor additional commands that can be entered as match criteria, see the Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference. For conceptual information, see Traffic Policy Elements. SUMMARY STEPS 1. configure 2. policy-map [type qos] policy-name 3. class class-name 4. set precedence 5. end or commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map [type qos] policy-name Enters policy map configuration mode. Example: • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. RP/0/RSP0/CPU0:router(config)# policy-map policy1 class class-name Specifiesthe name of the class whose policy you want to create or change. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 Step 3 set precedence Sets the precedence value in the IP header. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# set precedence 3 Step 4 Step 5 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-pmap-c)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 112 OL-26077-02 Configuring Modular QoS Service Packet Classification Creating a Traffic PolicyCommand or Action Purpose Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Attaching a Traffic Policy to an Interface After the traffic class and traffic policy are created, you must use the service-policy interface configuration command to attach a traffic policy to an interface, and to specify the direction in which the policy should be applied (either on packets coming into the interface or packets leaving the interface). For additional commands that can be entered in policy map class configuration mode, see the Cisco ASR 9000 Series Aggregation Services RoutersModular Quality of Service Command Reference.. Prerequisites A traffic class and traffic policy must be created before attaching a traffic policy to an interface. Restrictions None SUMMARY STEPS 1. configure 2. interface type interface-path-id 3. service-policy {input | output} policy-map 4. Use one of these commands: • end • commit 5. show policy-map interface type interface-path-id [input | output] Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 113 Configuring Modular QoS Service Packet Classification Attaching a Traffic Policy to an InterfaceDETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 interface type interface-path-id Enters interface configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/1/0/9 Step 2 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 3 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 4 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config)# commit ? Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. ? Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. show policy-map interface type (Optional) Displays statistics for the policy on the specified interface. interface-path-id [input | output] Step 5 Example: RP/0/RSP0/CPU0:router# show policy-map interface gigabitethernet 0/1/0/9 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 114 OL-26077-02 Configuring Modular QoS Service Packet Classification Attaching a Traffic Policy to an InterfaceAttaching a Shared Policy Instance to Multiple Subinterfaces After the traffic class and traffic policy are created, you can optionally use the service-policy (interface) configuration command to attach a shared policy instance to multiple subinterfaces, and to specify the direction in which the policy should be applied (either on packets coming into or leaving the subinterface). Note A shared policy can include a combination of Layer 2 and Layer 3 subinterfaces. For additional commands that can be entered in policy map class configuration mode, see the Cisco ASR 9000 Series Aggregation Services Routers Modular Quality of Service Command Reference. Prerequisites A traffic class and traffic policy must be created before attaching a shared policy instance to a subinterface. Restrictions Shared policy instance across multiple physical interfaces is not supported. SUMMARY STEPS 1. configure 2. interface type interface-path-id 3. service-policy {input | output} policy-map [shared-policy-instance instance-name] 4. Use one of these commands: • end • commit 5. show policy-map shared-policy-instance instance-name [input | output] location rack/slot/module DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 interface type interface-path-id Enters interface configuration mode and configures a subinterface. Example: RP/0/RSP0/CPU0:router(config)# interface gigabitethernet 0/1/0/0.1 Step 2 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 115 Configuring Modular QoS Service Packet Classification Attaching a Traffic Policy to an InterfaceCommand or Action Purpose Attaches a policy map to an input or output subinterface to be used as the service policy for that subinterface. service-policy {input | output} policy-map [shared-policy-instance instance-name] Step 3 Example: RP/0/RSP0/CPU0:router(config-if)# • In this example, the traffic policy evaluates all traffic leaving that interface. service-policy output policy1 shared-policy-instance Customer1 Step 4 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config)# commit ? Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. ? Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays statistics for the policy on the specified shared policy instance subinterface. show policy-map shared-policy-instance instance-name [input | output] location rack/slot/module Step 5 Example: RP/0/RSP0/CPU0:router# show policy-map shared-policy-instance Customer1 location 0/1/0/7.1 Attaching a Shared Policy Instance to Bundle Interfaces or EFP Bundles After the traffic class and traffic policy are created, you can optionally use the service-policy (interface) configuration command to attach a shared policy instance to bundle interfaces and to bundle EFPs, and to specify the direction in which the policy should be applied (either on packets coming into or leaving the subinterface). Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 116 OL-26077-02 Configuring Modular QoS Service Packet Classification Attaching a Traffic Policy to an InterfaceFor additional commands that can be entered in policy map class configuration mode, see the Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference. Prerequisites A traffic class and traffic policy must be created before attaching a shared policy instance to bundle interfaces or EFP bundles. Restrictions Shared policy instance across multiple physical interfaces is not supported. SUMMARY STEPS 1. configure 2. interface Bundle-Ether bundle-id 3. service-policy {input | output} policy-map [shared-policy-instance instance-name] 4. Use one of these commands: • end • commit 5. show policy-map shared-policy-instance instance-name [input | output] location location-id DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Enters interface configuration mode and configures a bundle interface. interface Bundle-Ether bundle-id Example: RP/0/RP1/CPU0:router(config)# interface Bundle-Ether 100.1 l2transport Step 2 Attaches a policy map to an input or output bundle interface to be used as the service policy for that subinterface. service-policy {input | output} policy-map [shared-policy-instance instance-name] Step 3 Example: RP/0/RSP0/CPU0:router(config-if)# • In this example, the traffic policy evaluates all traffic leaving that interface. service-policy output policy1 shared-policy-instance Customer1 Step 4 Use one of these commands: Saves configuration changes. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 117 Configuring Modular QoS Service Packet Classification Attaching a Traffic Policy to an InterfaceCommand or Action Purpose • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • end • commit Example: RP/0/RSP0/CPU0:router(config)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config)# commit ? Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. ? Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays statistics for the policy at the specified shared policy instance location. show policy-map shared-policy-instance instance-name [input | output] location location-id Example: RP/0/RSP0/CPU0:router# show policy-map Step 5 shared-policy-instance Customer1 location 0/rsp0/cpu0 Configuring Class-based Unconditional Packet Marking This configuration task explains how to configure the following class-based, unconditional packet marking features on your router: • IP precedence value • IP DSCP value • QoS group value (ingress only) • CoS value ( egress only on Layer 3 subinterfaces) • MPLS experimental value • Discard class Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 118 OL-26077-02 Configuring Modular QoS Service Packet Classification Configuring Class-based Unconditional Packet MarkingIPv4 and IPv6 QoS actions applied to MPLS tagged packets are not supported. The configuration is accepted, but no action is taken. Note Note Choose only two set commands per class. SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. set precedence 5. set dscp 6. set qos-group qos-group-value 7. set cos cos-value 8. set cos [inner] cos-value 9. set mpls experimental {imposition | topmost} exp-value 10. set srp-priority priority-value 11. set discard-class discard-class-value 12. set atm-clp 13. exit 14. exit 15. interface type interface-path-id 16. service-policy {input | output]} policy-map 17. Use one of these commands: • end • commit 18. show policy-map interface type interface-path-id [input | output] DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 119 Configuring Modular QoS Service Packet Classification Configuring Class-based Unconditional Packet MarkingCommand or Action Purpose Example: RP/0/RSP0/CPU0:router(config)# policy-map policy1 • Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Step 3 class class-name Enters policy class map configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class1 • Specifies the name of the class whose policy you want to create or change. Choose one set command per class Step 4 set precedence Sets the precedence value in the IP header. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# set precedence 1 • The tunnel keyword sets the IP precedence on the outer IP header. This option is available only on a Cisco XR 12000 Series Router with IPSec installed and configured. Step 5 set dscp Marks a packet by setting the DSCP in the ToS byte. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# set dscp 5 • The tunnel keyword sets the IP DSCP on the outer IP header. This option is available only on a Cisco XR 12000 Series Router with IPSec installed and configured. Step 6 set qos-group qos-group-value Sets the QoS group identifiers on IPv4 or MPLS packets. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# set qos-group 31 The set qos-group command is supported only on an ingress policy. Sets the specific IEEE 802.1Q Layer 2 CoS value of an outgoing packet. Values are from 0 to7. set cos cos-value Example: RP/0/RP0/CPU0:router(config-pmap-c)# set cos 7 Step 7 Sets the Layer 2 CoS value of an outgoing packet. • This command should be used by a router if a user wants to mark a packet that is being sent to a switch. Switches can leverage Layer 2 header information, including a CoS value marking. • Packets entering an interface cannot be set with a CoS value. Sets the specific IEEE 802.1Q Layer 2 CoS value of an outgoing packet. Values are from 0 to7. set cos [inner] cos-value Example: RP/0/RSP0/CPU0:router(config-pmap-c)# set cos 7 Step 8 Sets the Layer 2 CoS value of an outgoing packet. • This command should be used by a router if a user wants to mark a packet that is being sent to a switch. Switches can leverage Layer 2 header information, including a CoS value marking. • For Layer 2 interfaces, the set cos command: Is rejected on ingress or egress policies on a main interface. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 120 OL-26077-02 Configuring Modular QoS Service Packet Classification Configuring Class-based Unconditional Packet MarkingCommand or Action Purpose Is accepted but ignored on ingress policies on a subinterface. Is supported on egress policies on a subinterface. • For Layer 3 interfaces, the set cos command: Is ignored on ingress policies on a main interface. Is rejected on ingress policies on a subinterface. Issupported on egress policies on main interfaces and subinterfaces. Sets the experimental value of the MPLS packet top-most or imposition labels. set mpls experimental {imposition | topmost} exp-value Step 9 Example: RP/0/RSP0/CPU0:router(config-pmap-c)# set mpls experimental imposition 3 • imposition can be used only in service policies that are attached in the ingress policy. Step 10 set srp-priority priority-value Sets the spatial reuse protocol (SRP) priority value of an outgoing packet. Example: RP/0//CPU0:router(config-pmap-c)# set srp-priority 3 • This command can be used only in service policiesthat are attached in the output direction of an interface. Sets the discard class on IP Version 4 (IPv4) or Multiprotocol Label Switching (MPLS) packets. set discard-class discard-class-value Example: RP/0//CPU0:router(config-pmap-c)# set discard-class 3 Step 11 • This command can be used only in service policiesthat are attached in the ingress policy. set atm-clp Sets the cell loss priority (CLP) bit. Example: RP/0/0/CPU0:router(config-pmap-c)# set atm-clp Step 12 exit Returns the router to policy map configuration mode. Example: Step 13 RP/0/RSP0/CPU0:router(config-pmap-c)# exit exit Returns the router to global configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# exit Step 14 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 121 Configuring Modular QoS Service Packet Classification Configuring Class-based Unconditional Packet MarkingCommand or Action Purpose interface type interface-path-id Enters interface configuration mode and configures an interface. Example: RP/0/RSP0/CPU0:router(config)# interface pos 0/2/0/0 Step 15 Attaches a policy map to an input or output interface to be used as the service policy for that interface. service-policy {input | output]} policy-map Example: RP/0/RSP0/CPU0:router(config-if)# service-policy output policy1 Step 16 • In this example, the traffic policy evaluates all traffic leaving that interface. Step 17 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config-if)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config-if)# commit ? Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. ? Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. (Optional) Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface type interface-path-id [input | output] Example: RP/0/RSP0/CPU0:router# show policy-map interface pos 0/2/0/0 Step 18 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 122 OL-26077-02 Configuring Modular QoS Service Packet Classification Configuring Class-based Unconditional Packet MarkingConfiguring QoS Policy Propagation Using Border Gateway Protocol This section explains how to configure Policy Propagation Using Border Gateway Protocol (BGP) on a router based on BGP community lists, BGP autonomoussystem paths, accesslists,source prefix address, or destination prefix address. Policy Propagation Using BGP Configuration Task List Policy propagation using BGP allows you to classify packets by IP precedence and/or QoS group ID, based on BGP community lists, BGP autonomous system paths, access lists, source prefix address and destination prefix address. After a packet has been classified, you can use other quality-of-service featuressuch as weighted random early detection (WRED) to specify and enforce policies to fit your business model. Overview of Tasks To configure Policy Propagation Using BGP, perform the following basic tasks: • Configure BGP and Cisco Express Forwarding (CEF). To configure BGP, see Cisco IOS XR Routing Configuration Guide. To configure CEF, see Cisco IOS XR IP Address and Services Configuration Guide . • Configure a BGP community list or access list. • Define the route policy. Set the IP precedence and/or QoS group ID, based on the BGP community list, BGP autonomous system path, access list, source prefix address or destination prefix address. • Apply the route policy to BGP. • Configure QPPB on the desired interfaces. • Configure and enable a QoS Policy to use the above classification (IP precedence or QoS group ID). To configure committed access rate (CAR), WRED and tail drop, see the Configuring Modular QoS Congestion Avoidance on Cisco IOS XR Software module. Defining the Route Policy This task defines the route policy used to classify BGP prefixes with IP precedence or QoS group ID. Prerequisites Configure the BGP community list, or access list, for use in the route policy. Restrictions • IPv4 and IPv6 QPPB with egress QoS policy is supported on all Ethernet and SIP-700 line cards. • IPv4 QPPB with ingress QoS policy is supported on the first generation ASR9000 Ethernet line cards. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 123 Configuring Modular QoS Service Packet Classification Configuring QoS Policy Propagation Using Border Gateway ProtocolSUMMARY STEPS 1. configure 2. route-policy name 3. set qos-groupqos-group-value 4. Use one of these commands: • end • commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Enters route policy configuration mode and specifies the name of the route policy to be configured. route-policy name Example: RP/0/RSP0/CPU0:router(config)# route-policy r1 Step 2 Sets the QoS group identifiers. The set qos-group command is supported only on an ingress policy. set qos-groupqos-group-value Example: RP/0/RSP0/CPU0:router(config-pmap-c) # set qos-group 30 Step 3 Step 4 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config)# commit ? Entering no exitsthe configuration session and returnsthe router to EXEC mode without committing the configuration changes. ? Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 124 OL-26077-02 Configuring Modular QoS Service Packet Classification Defining the Route PolicyCommand or Action Purpose Applying the Route Policy to BGP This task applies the route policy to BGP. Prerequisites Configure BGP and CEF. SUMMARY STEPS 1. configure 2. router bgpas-number 3. address-familyaddress-prefix 4. table-policypolicy-name 5. Use one of these commands: • end • commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 router bgpas-number Enters BGP configuration mode. Example: RP/0/RSP0/CPU0:router(config) # router bgp 120 Enters address-family configuration mode, allowing you to configure an address family. address-familyaddress-prefix Example: RP/0/RSP0/CPU0:router(config-bgp) # address-family ipv4 unicast Step 3 Step 4 table-policypolicy-name Applying a routing policy. Example: RP/0/RSP0/CPU0:router(config-bgp-af) # table-policy qppb a1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 125 Configuring Modular QoS Service Packet Classification Applying the Route Policy to BGPCommand or Action Purpose Step 5 Use one of these commands: Saves configuration changes. • end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: • commit Example: RP/0/RSP0/CPU0:router(config)# end ? Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. or RP/0/RSP0/CPU0:router(config)# commit ? Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. ? Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Configuring QPPB on the Desired Interfaces This task applies QPPB to a specified interface. The traffic begins to be classified, based on matching prefixes in the route policy. The source or destination IP address of the traffic can be used to match the route policy. SUMMARY STEPS 1. configure 2. interface type interface-path-id 3. ipv4 | ipv6 bgp policy propagation input {ip-precedence | qos-group} {destination [ip-precedence {destination | source}] | source [ip-precedence {destination | source}] } RP/0/RSP0/CPU0:router(config)#ipv4 bgp policy propagation input qos-group destination Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 126 OL-26077-02 Configuring Modular QoS Service Packet Classification Configuring QPPB on the Desired InterfacesDETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Enters interface configuration mode and associates one or more interfacesto the VRF. interface type interface-path-id Example: RP/0/RSP0/CPU0:router(config)#interface POS 0/0/0/0 Step 2 ipv4 | ipv6 bgp policy propagation input {ip-precedence | qos-group} Enables QPPB on an interface {destination [ip-precedence {destination | source}] | source Step 3 [ip-precedence {destination | source}] } RP/0/RSP0/CPU0:router(config)#ipv4 bgp policy propagation input qos-group destination QPPB scenario Consider a scenario where in traffic is moving from Network1 to Network2 through (a single) router port1 and port2. If QPPB is enabled on port1, then, • for qos on ingress: attach an ingress policy on the interface port1. • for qos on egress: attach an egress policy on interface port2. Configuring Hierarchical Ingress Policing SUMMARY STEPS 1. 2. policy-map policy-name 3. class class-name 4. service-policy policy-name 5. police rate percent percentage 6. conform-action action 7. exceed-action action 8. end or commit Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 127 Configuring Modular QoS Service Packet Classification QPPB scenarioDETAILED STEPS Command or Action Purpose Enters global configuration mode. Example: RP/0//CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0//CPU0:router(config)# policy-map parent Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy Step 3 class class-name Enters policy map class configuration mode. Example: RP/0//CPU0:router(config-pmap)# class class-default Specifies the name of the class whose policy you want to create or change. service-policy policy-name Attaches a policy map to an input or output interface. Example: RP/0//CPU0:router(config-pmap-c)# service-policy child Step 4 Configurestraffic policing and enters policy map police configuration mode. police rate percent percentage Example: RP/0//CPU0:router(config-pmap-c)# police rate percent 50 Step 5 Configures the action to take on packets that conform to the rate limit. The allowed action is: conform-action action Example: RP/0//CPU0:router(config-pmap-c-police)# conform-action transmit Step 6 transmit—Transmits the packets. Configures the action to take on packets that exceed the rate limit. The allowed action is: exceed-action action Example: RP/0//CPU0:router(config-pmap-c-police)# exceed-action drop Step 7 drop—Drops the packet. Step 8 end or commit Saves configuration changes. Example: RP/0//CPU0:router(config-pmap-c-police)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 128 OL-26077-02 Configuring Modular QoS Service Packet Classification Configuring Hierarchical Ingress PolicingCommand or Action Purpose or RP/0//CPU0:router(config-pmap-c-police)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Configuration Examples for Configuring Modular QoS Packet Classification This section contains the following examples: Traffic Classes Defined: Example In the following example, two traffic classes are created and their match criteria are defined. For the first traffic class called class1, ACL 101 is used as the match criterion. For the second traffic class called class2, ACL 102 is used as the match criterion. Packets are checked against the contents of these ACLs to determine if they belong to the class. class-map class1 match access-group ipv4 101 exit ! class-map class2 match access-group ipv4 102 exit Use the not keyword with the match command to perform a match based on the values of a field that are not specified. The following example includes all packets in the class qos_example with a DSCP value other than 4, 8, or 10. class-map match-any qos_example match not dscp 4 8 10 ! end Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 129 Configuring Modular QoS Service Packet Classification Configuration Examples for Configuring Modular QoS Packet ClassificationTraffic Policy Created: Example In the following example, a traffic policy called policy1 is defined to contain policy specifications for the two classes—class1 and class2. The match criteria for these classes were defined in the traffic classes created in the Traffic Classes Defined: Example. For class1, the policy includes a bandwidth allocation request and a maximum byte limit for the queue reserved for the class. For class2, the policy specifies only a bandwidth allocation request. policy-map policy1 class class1 bandwidth 3000 queue-limit bytes 1000000000 exit ! class class2 bandwidth 2000 exit policy-map policy1 class class1 bandwidth 3000 kbps queue-limit 1000 packets ! class class2 bandwidth 2000 kbps ! class class-default ! end-policy-map ! end Traffic Policy Attached to an Interface: Example The following example shows how to attach an existing traffic policy to an interface (see the Traffic Classes Defined: Example). After you define a traffic policy with the policy-map command, you can attach it to one or more interfaces to specify the traffic policy for those interfaces by using the service-policy command in interface configuration mode. Although you can assign the same traffic policy to multiple interfaces, each interface can have only one traffic policy attached at the input and only one traffic policy attached at the output. interface gigabitethernet 0/1/0/9 service-policy output policy1 exit ! interface TenGigE 0/5/0/1 service-policy output policy1 exit Traffic Policy Attached to Multiple Subinterfaces: Example The following example shows how to attach an existing traffic policy to multiple subinterfaces. After you define a traffic policy with the policy-map command, you can attach it to one or more subinterfaces using the service policy command in subinterface configuration mode. interface gigabitethernet 0/1/0/0.1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 130 OL-26077-02 Configuring Modular QoS Service Packet Classification Traffic Policy Created: Exampleservice-policy input policy1 shared-policy-instance ethernet101 exit ! interface gigabitethernet 0/1/0/0.2 service-policy input policy1 shared-policy-instance ethernet101 exit Traffic Policy Attached to a Bundle Interface: Example The following example shows how to attach an existing traffic policy to a bundle interface. After you define a traffic policy with the policy-map command, you can attach it to one or more bundle subinterfaces using the service policy command in subinterface configuration mode. interface Bundle-Ether 100.1 service-policy tripleplaypolicy shared-policy-instance subscriber1 exit ! interface Bundle-Ether 100.2 service-policy output tripleplaypolicy shared-policy instance subscriber1 exit EFP Load Balancing with Shared Policy Instance: Example The following examples show how to configure load balancing of an EFP when SPI is implemented. For additional information on EFP load balancing on link bundles, see the Cisco IOS XR Interface and Hardware Component Configuration Guide. |Configuring a Bundle Interface: Example interface Bundle-Ether 50 interface gigabitethernet 0/1/0/5 bundle id 50 mode active interface gigabitethernet 0/1/0/8 bundle id 50 mode active Configuring Two Bundle EFPs with the Load Balance Options: Example This example configures the traffic for two bundle EFPs go over the same physical member link. interface Bundle-Ether 50.25 l2transport encapsulation dot1q 25 bundle load-balance hash-select 2 ! interface Bundle-Ether 50.36 l2transport encapsulation dot1q 36 bundle load-balance hash-select 2 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 131 Configuring Modular QoS Service Packet Classification Traffic Policy Attached to a Bundle Interface: ExampleDefault Traffic Class Configuration: Example The following example shows how to configure a traffic policy for the default class of the traffic policy called policy1. The default class is named class-default, consists of all other traffic, and is being shaped at 60 percent of the interface bandwidth. policy-map policy1 class class-default shape average percent 60 class-map match-any Command Configuration: Example The following example illustrates how packets are evaluated when multiple match criteria exist. Only one match criterion must be met for the packet in the class-map match-any command to be classified as a member of the traffic class (a logical OR operator). In the example, protocol IP OR QoS group 4 OR access group 101 have to be successful match criteria: class-map match-any class1 match protocol ipv4 match qos-group 4 match access-group ipv4 101 In the traffic class called class1, the match criteria are evaluated consecutively until a successful match criterion islocated. Each matching criterion is evaluated to see if the packet matchesthat criterion. If the packet matches at least one of the specified criteria, the packet is classified as a member of the traffic class. Note The match qos-group command is supported only on egress policies. Class-based, Unconditional Packet Marking Examples The following are typical class-based, unconditional packet marking examples: IP Precedence Marking Configuration: Example In the following example, a service policy called policy1 is created. This service policy is associated to a previously defined class map called class1 through the use of the class command, and then the service policy is attached to the output POS interface 0/1/0/0. The IP precedence bit in the ToS byte is set to 1: policy-map policy1 class class1 set precedence 1 ! interface pos 0/1/0/0 service-policy output policy1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 132 OL-26077-02 Configuring Modular QoS Service Packet Classification Default Traffic Class Configuration: ExampleIP DSCP Marking Configuration: Example In the following example, a service policy called policy1 is created. This service policy is associated to a previously defined class map through the use of the class command. In this example, it is assumed that a class map called class1 was previously configured. In the following example, the IP DSCP value in the ToS byte is set to 5: policy-map policy1 class class1 set dscp 5 class class2 set dscp ef After you configure the settings shown for voice packets at the edge, all intermediate routers are configured to provide low-latency treatment to the voice packets, as follows: class-map voice match dscp ef policy-map qos-policy class voice priority level 1 police rate percent 10 QoS Group Marking Configuration: Example In the following example, a service policy called policy1 is created. This service policy is associated to a class map called class1 through the use of the class command, and then the service policy is attached in the input direction on a GigabitEthernet interface 0/1/0/9. The qos-group value is set to 1. class-map match-any class1 match protocol ipv4 match access-group ipv4 101 policy-map policy1 class class1 set qos-group 1 ! interface gigabitethernet 0/1/0/9 service-policy input policy1 Note The set qos-group command is supported only on an ingress policy. CoS Marking Configuration: Example In the following example, a service policy called policy1 is created. This service policy is associated to a class map called class1 through the use of the class command, and then the service policy is attached in the output direction on a 10-Gigabit Ethernet interface, TenGigE0/1/0/0. The IEEE 802.1p (CoS) bits in the Layer 2 header are set to 1. class-map match-any class1 match protocol ipv4 match access-group ipv4 101 policy-map policy1 class class1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 133 Configuring Modular QoS Service Packet Classification Class-based, Unconditional Packet Marking Examplesset cos 1 ! interface TenGigE0/1/0/0 interface TenGigE0/1/0/0.100 service-policy output policy1 MPLS Experimental Bit Imposition Marking Configuration: Example In the following example, a service policy called policy1 is created. This service policy is associated to a class map called class1 through the use of the class command, and then the service policy is attached in the input direction on a 10-Gigabit Ethernet interface, TenGigE0/1/0/0. The MPLS EXP bits of all imposed labels are set to 1. class-map match-any class1 match protocol ipv4 match access-group ipv4 101 policy-map policy1 class class1 set mpls exp imposition 1 ! interface TenGigE0/1/0/0 service-policy input policy1 Note The set mpls exp imposition command is supported only on an ingress policy. MPLS Experimental Topmost Marking Configuration: Example In the following example, a service policy called policy1 is created. This service policy is associated to a class map called class1 through the use of the class command, and then the service policy is attached in the output direction on a 10-Gigabit Ethernet interface, TenGigE0/1/0/0. The MPLS EXP bits on the TOPMOST label are set to 1: class-map match-any class1 match mpls exp topmost 2 policy-map policy1 class class1 set mpls exp topmost 1 ! interface TenGigE0/1/0/0 service-policy output policy1 In-Place Policy Modification: Example In this example, the precedence is changed from 3 to 5 after the policy is defined and attached to an interface: Define a class: class-map match-any class1 match cos 7 end-class-map Define a policy map that uses the class: policy-map policy1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 134 OL-26077-02 Configuring Modular QoS Service Packet Classification In-Place Policy Modification: Exampleclass class1 set precedence 3 Attach the policy map to an interface: interface gigabitethernet 0/6/0/1 service-policy output policy1 commit Modify the precedence value of the policy map: policy-map policy1 class class1 set precedence 5 commit The modified policy policy1 takes effect on all the interfaces to which the policy is attached. Also, you can modify any class map used in the policy map. The changes made to the class map take effect on all the interfaces to which the policy is attached. Note Output from the show policy-map targets command indicates that the Gigabit Ethernet interface 0/1/0/0 has one policy map attached as a main policy (as opposed to being attached to a child policy in a hierarchical QoS configuration). Outgoing traffic on this interface is affected if the policy is modified: show policy-map targets Fri Jul 16 16:38:24.789 DST 1) Policymap: policy1 Type: qos Targets (applied as main policy): GigabitEthernet0/1/0/0 output Total targets: 1 Targets (applied as child policy): Total targets: 0 Additional References The following sections provide references related to implementing packet classification. Related Documents Related Topic Document Title Cisco ASR 9000 Series Aggregation Services Router Getting Started Guide Initial system bootup and configuration Cisco ASR 9000 Series Aggregation Services Router Master Command Listing Master command reference Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference QoS commands Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 135 Configuring Modular QoS Service Packet Classification Additional ReferencesRelated Topic Document Title “Configuring AAA Services on Cisco ASR 9000 Series Router” module of Cisco Cisco ASR 9000 Series Aggregation Services Router System Security Configuration Guide User groups and task IDs Standards Standards Title No new or modified standards are supported by — this feature, and support for existing standards has not been modified by this feature. MIBs MIBs MIBs Link To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/ cmtk/mibs.shtml — RFCs RFCs Title No new or modified RFCs are supported by this — feature, and support for existing RFCs has not been modified by this feature. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 136 OL-26077-02 Configuring Modular QoS Service Packet Classification StandardsTechnical Assistance Description Link The Cisco Technical Support website contains http://www.cisco.com/techsupport thousands of pages of searchable technical content, including links to products, technologies,solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 137 Configuring Modular QoS Service Packet Classification Technical Assistance Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 138 OL-26077-02 Configuring Modular QoS Service Packet Classification Technical AssistanceC H A P T E R 6 Modular QoS Deployment Scenarios This module provides deployment scenarios use cases for specific QoS features or for QoS implementations of features that are described in other technology guides, such as L2VPN or MPLS. Line Card, SIP, and SPA Support Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 802.1ad DEI yes no Frame Relay QoS no yes 2-Port Channelized OC-12c/DS0 SPA only IPHC QoS no L2VPN QoS yes yes 2-Port Channelized OC-12c/DS0 SPA only MLPPP/MLFR QoS no MPLS QoS yes yes QoS on Multicast VPN yes yes 2-Port Channelized OC-12c/DS0 SPA only QoS on NxDS0 Interfaces no Feature History for QoS Deployment Scenarios on Cisco ASR 9000 Series Routers Release Modification The L2VPN QoS feature was introduced on ASR 9000 Ethernet Line Cards. The MPLS QoS feature was introduced on ASR 9000 Ethernet Line Cards. Release 3.7.2 Release 3.9.0 The MLPPP QoS feature was introduced on the SIP 700 for the ASR 9000. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 139The QoS on Multicast VPN feature was introduced on ASR 9000 Ethernet Line Cards. Release 3.9.1 The 802.1ad DEI feature was introduced on the SIP 700 for the ASR 9000. The Frame Relay QoS feature was introduced on the SIP 700 for the ASR 9000. The IP Header Compression QoS feature was introduced on the SIP 700 for the ASR 9000. The L2VPN QoS feature was supported on the SIP 700 for the ASR 9000. The MLFR QoS feature was introduced on the SIP 700 for the ASR 9000. The suspend/resume approach was added for MLPPP and MLFR interfaces. The MPLS QoS feature was supported on the SIP 700 for the ASR 9000. The QoS on NxDS0 Interfaces feature was introduced on the SIP 700 for the ASR 9000. Release 4.0.0 Release 4.1.0 The VPLS and VPWS QoS feature was introduced. • 802.1ad DEI, page 140 • Frame Relay QoS, page 141 • IP Header Compression QoS, page 145 • L2VPN QoS, page 146 • MLPPP QoS/MLFR QoS, page 149 • MPLS QoS, page 151 • QoS on Multicast VPN, page 156 • QoS on NxDS0 Interfaces, page 158 • VPLS and VPWS QoS, page 159 • Related Information, page 161 802.1ad DEI You can classify traffic based on the Drop Eligible Indicator (DEI) bit that is present in 802.1ad frames and in 802.1ah frames. DEI support includes the ability to: • Police to a certain rate and, based on whether the traffic is conforming or exceeding, mark the DEI as 0 or 1. • On ingress, police and set up the discard class (even on an interface that is not configured for 802.1ad encapsulation). • On egress, mark the DEI based on the discard class value (802.1ad interfaces only). Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 140 OL-26077-02 Modular QoS Deployment Scenarios 802.1ad DEIYou can manage congestion based on the Drop Eligible Indicator (DEI) bit that is present in 802.1ad frames and 802.1ah frames. DEI support includes the ability to: • Do weighted random early detection (WRED) based on the value of the DEI bit. • Do active queue management during traffic congestion on an interface by giving preferential treatment to traffic (bigger thresholds) or set up smaller thresholds for out-of-profile traffic based on a DEI value. Mark DEI Based on a Policing Action: Example In this example, the police rate is set to 5 Mbps. Conforming traffic is marked with a DEI value of 0; traffic that exceeds the police rate is marked with a DEI value of 1. policy-map 1ad-mark-dei class c1 police rate 5 mbps conform-action set dei 0 exceed-action set dei 1 end-policy-map Mark DEI Based on Incoming Fields: Example In this example, 802.1ad CoS plus DEI is derived from the incoming 802.1q CoS. Packets with a CoS value of 0 are remarked with a DEI value of 1. class-map match-any remark-cos match cos 0 end-class-map policy-map p1 class remark-cos set dei 1 end-policy-map interface GigabitEthernet0/4/0/39.1 l2transport encapsulation dot1q 1 rewrite ingress tag push dot1ad 5 symmetric service-policy input p1 ! Congestion Management Using DEI: Example In this example, congestion is managed by dropping packets with a DEI value of 1 before dropping packets with a DEI value of 0. policy-map dei-sample class class-default random-detect dei 1 1000 6000 random-detect dei 0 5000 10000 end-policy-map Frame Relay QoS The main difference between Frame Relay QoS and other interface types is that you can perform: Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 141 Modular QoS Deployment Scenarios Mark DEI Based on a Policing Action: Example• Frame Relay DLCI classification • Frame Relay DE classification • Frame Relay DE marking A QoS policy can be applied only to a PVC under a Frame Relay subinterface; it cannot be applied directly to a Frame Relay subinterface. Note Frame Relay DLCI Classification This configuration allows users to match on the Frame Relay DLCI value of packets encapsulated in Frame Relay. Packets that are not Frame Relay encapsulated do not match this configuration. class-map foo match frame-relay list of dlci-values The list of DLCI values can contain ranges as well as individual values, as in this example: class-map foo match frame-relay dlci 1-100 150 200-300 Note DLCI matching is supported only on main interfaces. Frame Relay DE Classification This configuration allows the user to match Frame Relay packets that have the discard eligible (DE) bit set in the Frame Relay header: class-map fr_class match fr-de 1 To match Frame Relay DE bit 0, use this configuration: class-map match-not-fr-de match not fr-de 1 Note DE bit classification is not supported on Layer 3 interfaces. Frame Relay DE Marking In this example, the fr-de bit is set when traffic exceeds the policing committed information rate, so the downward system (when experiencing congestion) discards traffic with the fr-de bit set to 1. policy-map fr_de_marking class class-default Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 142 OL-26077-02 Modular QoS Deployment Scenarios Frame Relay DLCI Classificationpolice rate percent 50 conform-action transmit exceed-action set fr-de 1 ! ! end-policy-map Note DE bit marking is not supported on Layer 3 interfaces. Frame Relay QoS: Example In this example, parent_policy is applied to the Multilink Frame Relay main interface. There are two classes in parent_policy, which match on Frame Relay DLCIs. The Multilink Frame Relay main interface has two Frame Relay PVCs configured (DLCI 16, DLCI 17). show run int multi 0/2/1/0/1 Mon Aug 2 11:34:31.019 UTC interface Multilink0/2/1/0/1 service-policy output parent_policy encapsulation frame-relay frame-relay intf-type dce ! show run policy-map parent_policy Mon Aug 2 11:34:36.118 UTC policy-map parent_policy class parentQ_1 service-policy child_queuing_policy shape average 64 kbps ! class parentQ_2 service-policy child_queuing_policy shape average 1 mbps ! class class-default ! end-policy-map ! show run class-map parentQ_1 <----- class map parent class dlci=16 Mon Aug 2 11:34:43.363 UTC class-map match-any parentQ_1 match frame-relay dlci 16 end-class-map ! show run class-map parentQ_2 <----- class map parent class dlci=17 Mon Aug 2 11:34:45.647 UTC class-map match-any parentQ_2 match frame-relay dlci 17 end-class-map ! show run int multi 0/2/1/0/1.16 <------ dlci 16 pvc config Mon Aug 2 11:34:53.988 UTC interface Multilink0/2/1/0/1.16 point-to-point ipv4 address 192.1.1.1 255.255.255.0 pvc 16 encap cisco ! ! show run int multi 0/2/1/0/1.17 <------ dlci 17 pvc config Mon Aug 2 11:34:56.862 UTC interface Multilink0/2/1/0/1.17 point-to-point ipv4 address 192.1.2.1 255.255.255.0 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 143 Modular QoS Deployment Scenarios Frame Relay QoS: Examplepvc 17 encap cisco ! ! show run policy-map child_queuing_policy <--------- child policy-map Mon Aug 2 11:35:05.821 UTC policy-map child_queuing_policy class voice-ip priority level 1 police rate percent 20 ! ! class video bandwidth percent 40 ! class premium service-policy gchild_policy bandwidth percent 10 random-detect discard-class 2 10 ms 100 ms random-detect discard-class 3 20 ms 200 ms queue-limit 200 ms ! class best-effort bandwidth percent 20 queue-limit 200 ms ! class class-default ! end-policy-map ! show run policy-map gchild_policy <-------- grandchild policy map Mon Aug 2 11:35:15.428 UTC policy-map gchild_policy class premium_g1 police rate percent 10 ! set discard-class 2 ! class premium_g2 police rate percent 50 ! set discard-class 3 ! class class-default ! end-policy-map ! show run class-map <----------- shows all class map configs Mon Aug 2 11:35:19.479 UTC class-map match-any video match precedence 1 end-class-map ! class-map match-any premium match precedence 2 3 end-class-map ! class-map match-any voice-ip match precedence 0 end-class-map ! class-map match-any parentQ_1 match frame-relay dlci 16 end-class-map ! class-map match-any parentQ_2 match frame-relay dlci 17 end-class-map ! class-map match-any premium_g1 match precedence 2 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 144 OL-26077-02 Modular QoS Deployment Scenarios Frame Relay QoS: Exampleend-class-map ! class-map match-any premium_g2 match precedence 3 end-class-map ! class-map match-any best-effort match precedence 4 end-class-map ! IP Header Compression QoS An IP Header Compression (IPHC) profile can be enabled on an interface so that the IPHC profile applies only to packets that match a QoS service policy. In this case, the QoS service-policy class attributes determine which packets are compressed. This allows users to fine tune IPHC with greater granularity. Policy maps are attached to an interface using the service-policy command. IPHC action applies only to output service policies. IPHC is not supported on input service policies. (IPHC is supported in the input direction but there is no use case to configure IPHC in an input policy.) You can configure IPHC using QoS as follows: • Create a QoS policy with the compress header ip action. • Attach the IPHC profile to the interface using the ipv4 iphc profile profile_name mode service-policy command. • Attach the QoS policy with compress header ip action using the service-policy output command. You can also display IPHC statistics using the show policy-map interface command, asshown in the following example: show policy-map interface Serial0/0/3/0/3:0 output show policy-map int Serial0/0/3/0/3:0 output Mon May 18 22:06:14.698 UTC Serial0/0/3/0/3:0 output: p1 Class class-default Classification statistics (packets/bytes) (rate - kbps) Matched : 0/0 0 Transmitted : 0/0 0 Total Dropped : 0/0 0 Queueing statistics Queue ID : 0 High watermark (Unknown) : 0 Inst-queue-len (packets) : 0 Avg-queue-len (packets) : 0 Taildropped(packets/bytes) : 0/0 Compression Statistics Header ip rtp Sent Total (packets) : 880 Sent Compressed (packets) : 877 Sent full header (packets) : 342 Saved (bytes) : 31570 Sent (bytes) : 24750 Efficiency improvement factor : 2.27 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 145 Modular QoS Deployment Scenarios IP Header Compression QoSIP Header Compression QoS: Example In this example, IPHC is configured through QoS as an action under the class map using the compress header ip command. The packets are classified according to the criteria in the class maps. The policy map specifies which behavior to apply to which classes. IPHC is enabled using the compress header ip action for the class. An IPHC profile with a QoS service policy is attached to a serial interface. class-map match-all voice1 match precedence 2 class-map match-all voice2 match access-group acl_iphc access-list acl_iphc permit udp any range lower-bound src udp port 5000 upper-bound src udp port15000 any lower-bound udp dst port 5000 upper-bound dst udp port 15000 ipv4 access-list acl_iphc permit udp any range 5000 15000 any range 5000 15000 policy-map iphc_policy class iphc_class_1 compress header ip class iphc_class_2 compress header ip interface serial 0/1/0/1:1 ipv4 iphc profile Profile_3 mode service-policy service-policy output iphc_policy interface Serial 0/2/0/0/1/1/1:1 ipv4 address 10.0.0.1 255.255.255.252 ipv4 iphc profile Profile_3 mode service-policy service-policy output iphc_policy encapsulation ppp L2VPN QoS This section describes the following Frame Relay L2VPN deployment scenarios: • Frame Relay <-> Frame Relay over pseudowire • Frame Relay <-> Ethernet over pseudowire There are local-connect variants of these scenarios that do not go over a pseudowire. This discussion focuses on the pseudowire scenarios. Note Frame Relay <-> Frame Relay Over Pseudowire: Example This example shows that you can match based on the Frame Relay DLCI on the ingress Frame Relay interface on router PE1 and set the fr-de value. This configuration is carried over the L2VPN pseudowire. When the Frame Relay packet exits router PE2 through the Frame Relay l2transport interface, the fr-de value is intact. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 146 OL-26077-02 Modular QoS Deployment Scenarios IP Header Compression QoS: ExampleThis configuration allows you to manipulate and carry over the Frame Relay QoS values across L2VPN. Figure 2 shows the network topology. Figure 10: Frame Relay Over MPLS CE1 interface pos0/2/0/0.26 pvc 26 ipv4 add 10.0.0.1 255.0.0.0 PE1 interface pos0/2/0/0.26 l2transport pvc 26 l2vpn xconnect group frfr p2p p1 interface pos0/2/0/0.26 neighbor y.y.y.y pw-id 1001 !QoS Policy class-map matchdlci match frame-relay dlci 26 policy-map setde1 class matchdlci set fr-de 1 interface pos0/2/0/0 service-policy input setde1 PE2 interface pos0/3/0/0.26 l2transport pvc 26 l2vpn xconnect group frfr p2p p1 interface pos0/3/0/0.26 neighbor x.x.x.x pw-id 1001 CE2 interface pos0/3/0/0.26 pvc 26 ipv4 add 10.0.0.2 255.0.0.0 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 147 Modular QoS Deployment Scenarios Frame Relay <-> Frame Relay Over Pseudowire: ExampleFrame Relay <-> Ethernet Over Pseudowire: Example This example shows that you can match based on the fr-de value on the ingress Frame Relay l2transport interface on router PE1 and set a specific MPLS EXP value. When the MPLS packet exits the PE1 core interface, this EXP value is set. When the packet exits router PE2 through the Ethernet l2transport interface, this value is part of the Ethernet packet CoS field. This configuration allows you to carry over or map the QoS field from the Frame Relay network to the Ethernet network. Figure 3 shows the network topology. Figure 11: IP Interworking Over MPLS CE1 interface pos0/2/0/0.26 pvc 26 ipv4 add 10.0.0.1 255.0.0.0 PE1 interface pos0/2/0/0.26 l2transport pvc 26 l2vpn xconnect group freth p2p p1 interface pos0/2/0/0.26 neighbor y.y.y.y pw-id 1001 interworking ipv4 !QoS Policy class-map matchfrde match fr-de 1 policy-map setexp class matchfrde set mpls exp imposition 5 interface pos0/2/0/0.26 l2transport pvc 26 service-policy input setexp PE2 interface gig0/4/0/0.26 l2transport encapsulation dot1q 100 l2vpn xconnect group freth p2p p1 interface gig0/4/0/0.26 neighbor x.x.x.x pw-id 1001 interworking ipv4 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 148 OL-26077-02 Modular QoS Deployment Scenarios Frame Relay <-> Ethernet Over Pseudowire: ExampleCE2 interface gig0/4/0/0.26 encapsulation dot1q 100 ipv4 add 10.0.0.2 255.0.0.0 MLPPP QoS/MLFR QoS Multilink provides a mechanism for aggregating multiple serial links into a bundle. Bundles support more bandwidth, load balancing between links, and improved service availability by protecting against single points of failure. The service allows users to increase bandwidth by aggregating multiple low speed links, which can be more cost-effective than upgrading to a single higher speed link. This provides a cost-effective solution for users requiring leased line service with bandwidth greater than T1 rates but below T3 rates. Multilink interfaces can be configured with PPP encapsulation (MLPPP) or with Frame Relay encapsulation (MLFR). When a multilink interface is configured with Frame Relay encapsulation, subinterfaces can be configured below it. The total bandwidth available for the multilink interface can change dynamically when links are added or removed to or from a multilink interface. The total bandwidth available can also change if the member links change state operationally to up or down, or by modifying the suspended condition of the policy. QoS policies applied on such interfaces need to be updated based on the bandwidth changes. In this case, one of the following actions is taken: • Suspend the policy—Policy is suspended if the bandwidth requirements of the attached policy are more than the available bandwidth (which is reduced due to a member link going operationally down). Once the policy is suspended, any incoming or outgoing packets on that interface are not subject to QoS. A policy is suspended on ingress under these conditions: ? In Enhanced Hierarchical Ingress Policing, when the sum of child police rates is greater than the parent police conform rate ? Police peak rate is less than the police conform rate A policy is suspended on egress under these conditions: ? Minimum bandwidth rate + priority class police rate is greater than the interface rate ? Shape rate is less than the minimum bandwidth rate ? Priority class police conform rate is greater than the interface rate ? Priority class police peak rate is greater than the interface rate ? Police peak rate is less than the police conform rate • Resume the policy—Policy is resumed if the bandwidth requirements of the attached policy are less than or equal to the available bandwidth, which increased due to a member link going operationally up. A suspended policy can also be resumed by modifying the suspended condition of the policy map without any change in the member link status. • Update the policy—Active policy rates are updated to reflect the new available bandwidth. The available bandwidth could have increased or decreased, but the applied policy's bandwidth requirements can still be satisfied. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 149 Modular QoS Deployment Scenarios MLPPP QoS/MLFR QoSQoS statistics are not retained for the policy that transitions from an active state to a suspended state. If the policy is reactivated, all the previously collected statistics are lost and only the packets that pass through the interface after the reactivation are counted. The suspended policy can be modified to reduce its bandwidth requirements, so that it can be reactivated. A suspended policy can be modified while still attached to the interface. Multiclass MLPPP with QoS Multiclass Multilink Point-to-Point Protocol (MLPPP) can be used with QoS and configured using the encap-sequence command under a classin a policy map. The encap-sequence command specifiesthe MLPPP MCMP class ID for the packets in an MQC defined class. The valid values for the encap-sequence ID number are none, 1, 2, or 3. The none value is applicable only when the priority level is 1 and indicates that there is no MLPPP encapsulation. The values 1, 2, or 3 can be used with priority 1 or 2 classes or other classes with queuing actions. An encap-sequence ID number of zero (0) is used by the system and is reserved for the default class; it cannot be specified in any other classes. The encap-sequence ID numbers must be configured in numeric order. For example, you cannot assign an ID number of 3 unless you have already assigned 1 and 2. Note The number of encap-sequence ID numbers must be lessthan the number of MLPPP classesthat are negotiated between the peers via the multilink header. The user must ensure that the configuration is consistent as the system does not verify this. The ppp multilink multiclass remote apply command provides a way to ensure this. You can ensure that the number of classes using an encap-sequence ID number (including the default of 0) is less than the min-number value in the ppp multilink multiclass remote apply command. For example, if the min-number value is 4, you can only have three or fewer classes with encap-sequence ID numbers. The QoS policy validates the following conditions. If these conditions are not met, the policy is rejected: • The encap-sequence ID number is within the allowed values of 1 to 3. • When encap-sequence is configured for any class in a policy map, all classes in that policy map with priority level 1 must also contain an encap-sequence ID number. • The encap-sequence none configuration is restricted to classes with priority level 1. • The class-default does not contain an encap-sequence configuration. • Only classes containing a queuing action have the encap-sequence configuration. Note Classes that share the same encap-sequence ID number must have the same priority. A QoS policy map is configured as follows: config policy-map type qos policy-name class class-name action action action . . . Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 150 OL-26077-02 Modular QoS Deployment Scenarios Multiclass MLPPP with QoSThe following example shows how to configure a policy map for MLPPP: config policy-map foo class ip-prec-1 encap-sequence none police rate percent 10 priority level 1 ! class ip-prec-2 encap-sequence 1 shape average percent 80 ! class ip-prec-3 encap-sequence 1 bandwidth percent 10 ! class class-default ! end-policy-map ! MLPPP QoS/MLFR QoS: Example Because a bundle interface dynamically changes its bandwidth as the member links go up or down, QoS policies applied on such interfaces need to be updated based on the bandwidth changes. MPLS QoS The introductory text and topology diagrams are taken from “MPLS Fundamentals,” Luc De Ghein, Copyright 2007, Cisco Systems, Inc. Note For MPLS QoS, there are three deployment scenarios based on tunneling model: uniform mode, pipe mode, and short pipe mode. Table 2 shows an overview of the tunneling models. Tunneling Mode IP-to-Label Label-to-Label Label-to-IP Copy MPLS EXP to IP precedence/DiffServ Copy IP precedence /DiffServ MPLS EXP copied to MPLS EXP Uniform Preserve IP precedence /DiffServ Forwarding treatment based on MPLS EXP MPLS EXP set according to MPLS EXP copied service provider policy Pipe Preserve IP precedence /DiffServ Forwarding treatment based on IP precedence/DiffServ MPLS EXP set according to MPLS EXP copied service provider policy Short Pipe Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 151 Modular QoS Deployment Scenarios MLPPP QoS/MLFR QoS: ExampleMPLS Uniform Mode In uniform mode (shown in Figure 4), there is only one DiffServ marking that is relevant for a packet when traversing the MPLS network. If the DiffServ marking of the packet is modified within the MPLS network, the updates information is the one considered meaningful at the egress of the LSP. Any changes to the packet marking within the MPLS network are permanent and get propagated when the packet leaves the MPLS network. Figure 12: Uniform Mode MPLS Pipe Mode In pipe mode (shown in Figure 5), two markings are relevant for a packet when traversing the MPLS network. First, the marking used by intermediate nodes along the LSP span including the egress LSR. Second, the original marking carried by the packet before entering the MPLS network that will continue to be used once the packet leaves the MPLS network. Any changes to the packet marking within the MPLS network are not permanent and do not get propagated when the packet leaves the MPLS network. Note that the egress LSR still uses the marking that was used by intermediate LSRs. However, the egress LSR has to remove all labels imposed on the original packet. In order to preserve this marking carried in the labels, the edge LSR keeps an internal copy of the marking before removing the labels. This internal copy is used to Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 152 OL-26077-02 Modular QoS Deployment Scenarios MPLS Uniform Modeclassify the packet on the outbound interface (facing the CE) once the labels are removed. This is usually achieved using the set qos-group and match qos-group commands. Figure 13: Pipe Mode MPLS Short Pipe Mode The short pipe mode (shown in Figure 6), is a slight variation of the pipe mode. The only difference is that the egress LSR uses the original packet marking instead of using the marking used by the intermediate LSRs. Figure 14: Short Pipe Mode Uniform, Pipe, Short Pipe Modes: Ingress PE Example This example shows how to implement the MPLS DiffServ and demonstrates the configuration needed on the ingress PE. Only precedence 4 is being matched. Precedence 4 is mapped to EXP bits value 4 by the policer, unless the bandwidth is exceeded, in which case the EXP bits are recolored to the value 2. The egress interface configuration is not needed for the MPLS DiffServ uniform model, but it is added to show how to perform QoS on the EXP bits. !Ingress interface: class-map prec4 match precedence 4 ! policy-map set-MPLS-PHB Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 153 Modular QoS Deployment Scenarios MPLS Short Pipe Modeclass prec4 police rate 8000 kbps conform-action set mpls experimental imposition 4 exceed-action set mpls experimental imposition 2 ! interface GigabitEthernet0/0/0/1 service-policy input set-MPLS-PHB !Egress interface: class-map exp2and4 match mpls experimental topmost 2 4 ! policy-map output-qos class exp2and4 bandwidth percent 40 random-detect default ! interface GigabitEthernet0/0/0/2 service-policy output output-qos Uniform Mode: Egress PE Example On the egress PE, the EXP bits are copied to the precedence bits using the set qos-group and match qos-group commands. !Ingress interface: class-map exp2 match mpls experimental topmost 2 ! class-map exp4 match mpls experimental topmost 4 ! policy-map policy2 class exp2 set qos-group 2 class exp4 set qos-group 4 ! interface GigabitEthernet0/0/0/2 service-policy input policy2 !Egress interface: class-map qos2 match qos-group 2 class-map qos4 match qos-group 4 ! policy-map policy3 class qos2 set precedence 2 bandwidth percent 20 random-detect default class qos4 set precedence 4 bandwidth percent 20 random-detect default ! interface GigabitEthernet0/0/0/1 service-policy output policy3 Pipe Mode: Egress PE Example This example shows the configuration of the egress PE for the MPLS DiffServ pipe mode. The egress LSR does not copy the EXP bits to the precedence bits of the outgoing IP packet. The scheduling of the packets Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 154 OL-26077-02 Modular QoS Deployment Scenarios Uniform Mode: Egress PE Exampleon the egress interface is done indirectly on the EXP bits using the set qos-group and match qos-group commands. !Ingress interface: class-map exp2 match mpls experimental topmost 2 ! class-map exp4 match mpls experimental topmost 4 ! policy-map policy2 class exp2 set qos-group 2 class exp4 set qos-group 4 ! interface GigabitEthernet0/0/0/2 service-policy input policy2 !Egress interface: class-map qos2 match qos-group 2 class-map qos4 match qos-group 4 ! policy-map policy3 class qos2 bandwidth percent 20 random-detect default class qos4 bandwidth percent 20 random-detect default ! interface GigabitEthernet0/0/0/1 service-policy output policy3 Short Pipe Mode: Egress PE Example This example shows the configuration of the egress PE for the MPLS DiffServ short pipe mode. The egress LSR forwards the packet based on the precedence or differentiated services code point (DSCP) bits of the IP packet after removing the labels. The egress LSR does not copy the EXP bits to the precedence bits of the outgoing IP packet. ! Configuration is not needed for ingress interface !Egress interface: class-map prec4 match precedence 4 ! policy-map policy3 class prec4 bandwidth percent 40 random-detect precedence 4 100 ms 200 ms ! interface GigabitEthernet0/0/0/1 service-policy output policy3 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 155 Modular QoS Deployment Scenarios Short Pipe Mode: Egress PE ExampleQoS on Multicast VPN ASR 9000 Ethernet Line Cards The support for QoS services on a multicast VPN (mVPN) enabled network involves the marking of DSCP or precedence bits on the tunnel IP header. Thisfeature enables MPLS carriersto offer QoS on mVPN services. The mVPN network uses generic routing encapsulation (GRE) tunnels between provider edge (PE) devices. Multicast packets are placed in GRE tunnels for transmission across the MPLS core network. The ingress interfaces use the set precedence tunnel and set dscp tunnel commands (both conditional and unconditional) within an ingress policy applied to the ingressinterface.shows a typical mVPN network. When an IP packet arrives at PE1 on the ingress interface E1, the packet is sent out of the tunnel interface E2 into the core network by encapsulating the IP packet inside a GRE tunnel. Figure 15: mVPN Network If the set dscp tunnel command or the set precedence tunnel command is configured on the ingress interface E1, the DSCP or precedence values are set in the GRE tunnel header of the encapsulated packet being sent out of the interface E2. As a result: • The set dscp command or the set precedence command (conditional or unconditional) marks the DSCP or precedence values within the IP header. • The set dscp tunnel or the set precedence tunnel command (conditional or unconditional) marks the DSCP or precedence values within the GRE header. QoS on Multicast VPN: Example Supporting QoS in an mVPN-enabled network requires conditional and unconditional marking of the DSCP or precedence bits onto the tunnel header. Unconditional marking marks the DSCP or precedence tunnel as a policy action. Conditional marking marks the DSCP or precedence values on the tunnel header as a policer action (conform, exceed, or violate). Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 156 OL-26077-02 Modular QoS Deployment Scenarios QoS on Multicast VPNUnconditional Marking class-map c1 match vlan 1-10 policy-map p1 class c1 set precedence tunnel 3 Conditional Marking policy-map p2 class c1 police rate percent 50 conform action set dscp tunnel af11 exceed action set dscp tunnel af12 SIP 700 for the ASR 9000 The set precendence tunnel and set dscp tunnel commands are not supported but general Multicast VPN is supported, as shown in the following example. QoS on Multicast VPN: Example In this example, there are three services offered across the network: mobile, enterprise, and other services. Mobile traffic is classified as broadband 2G mobile traffic and 3G mobile traffic. Control traffic needs the highest priority and has priority level 1. Broadband 2G mobile traffic has priority level 2. A priority queue is associated with each of these traffic classes. Traffic in these classes is policed at a rate of 100 percent, which means that full line rate bandwidth is dedicated to these traffic classes. Remaining bandwidth is distributed across the Mcast_BBTV_Traffic class, Enterprise_Traffic class, and Enterprise_Low_Traffic class. policy-map CompanyA-Profile class Control_Traffic priority level 1 police rate percent 100 ! ! class BB_2GMobile_Traffic priority level 2 police rate percent 100 ! ! class Mcast_BBTV_Traffic bandwidth remaining ratio 1000 ! class 3GMobile_Traffic bandwidth remaining ratio 100 ! class Enterprise_Traffic bandwidth remaining ratio 10 ! class Enterprise_Low_Traffic bandwidth remaining ratio 1 ! Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 157 Modular QoS Deployment Scenarios SIP 700 for the ASR 9000class class-default ! end-policy-map QoS on NxDS0 Interfaces For QoS on NxDS0 interfaces, the shape, police, and queuing minimum rate is 8 kbps and granularity is 1 kbps. When QoS is applied to a low speed NxDS0 link, frame relay fragmentation (frf12) configuration is also recommended in order to provide low delay for real-time priority traffic. The common configurations on NxDS0 interfaces are: • One-level policy applied to a main interface without Frame Relay configured • Two-level policy applied to a subinterface with Frame Relay configured One-Level Policy Applied to Main Interface: Example show run int Serial0/2/1/0/1/1:0 Mon Aug 9 11:29:50.721 UTC interface Serial0/2/1/0/1/1:0 service-policy output fractional_T1_E1_policy ?--------policy applied to serial interface encapsulation frame-relay ! RP/0/RSP1/CPU0:viking-1#show run policy-map policy-map fractional_T1_E1_policy class Conversational priority level 1 police rate 64 kbps ! ! class Streaming-Interactive bandwidth remaining percent 35 ! class Background bandwidth remaining percent 15 ! class TCP-traffic bandwidth remaining percent 10 ! class class-default bandwidth remaining percent 40 ! end-policy-map Two-Level Policy Applied to a Subinterface: Example show run int Serial0/2/1/0/1/1:0 Mon Aug 9 11:29:50.721 UTC interface Serial0/2/1/0/1/1:0 encapsulation frame-relay frame-relay intf-type dce ! Mon Aug 9 11:29:37.150 UTC interface Serial0/2/1/0/1/1:0.16 point-to-point ipv4 address 192.1.1.1 255.255.255.0 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 158 OL-26077-02 Modular QoS Deployment Scenarios QoS on NxDS0 Interfacespvc 16 service-policy output parent_policy ?--------policy applied to serial subinterface encap cisco fragment end-to-end 350 ?-------------------frf12 enabled ! ! ! show run policy-map policy-map parent_policy class class-default shape average rate 768 kbps show run policy-map policy-map fractional_T1_E1_policy class Conversational priority level 1 police rate 64 kbps ! ! class Streaming-Interactive bandwidth remaining percent 35 ! class Background bandwidth remaining percent 15 ! class TCP-traffic bandwidth remaining percent 10 ! class class-default bandwidth remaining percent 40 ! end-policy-map VPLS and VPWS QoS To support QoS on virtual private LAN service (VPLS)-enabled and virtual private wire service (VPWS)-enabled networks, packets can be classified based on these match criteria: • Match on vpls broadcast (applicable to VPLS) • Match on vpls multicast (applicable to VPLS) • Match on vpls control (applicable to VPLS) • Match on ethertype arp (applicable to both VPLS and VPWS) VPLS-specific and VPWS-specific classification are performed only in the ingress direction. Note These guidelines apply to the VPLS and VPWS QoS feature: • Supported on ingress Layer 2 bundle and nonbundle subinterfaces. • Not supported on Layer 3 subinterfaces, but supported on ports with port inheritance policy. The system ignores VPLS classification on Layer 3 subinterfaces associated with the port. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 159 Modular QoS Deployment Scenarios VPLS and VPWS QoS• Match VPLS and match ethertype arp can be applied on a Layer 2 interface regardless of the Layer 2 service type, however VPLS classification is ignored on a non-VPLS Layer 2 interface type. Figure 9 illustrates a typical VPLS topology. The VPLS network is a mesh of pseudowires(PWs) interconnected to bridge domains in the routers. Each of the provider edge (PE) routers has a bridge domain. Each PW is a bridge port into the bridge domain. The customer edge (CE) connection into each PE router is an attachment circuit (AC) bridge port into the same bridge domain. QoS configuration commands are applied to the AC that connects to the CE router on the one end and the bridge domain of the PE router on the other. Figure 16: Typical VPLS Network Topology VPLS and VPWS QoS: Example This section contains a configuration example based on the components shown in Figure 9, and explains how the network matches packets based on the configured values. The policy-map and PE-to-CE connection are configured as follows on the PE1 router: class c1 match vpls multicast ! class c2 match vpls broadcast ! class c3 match vpls control ! class c4 match ethertype arp ! policy-map p1 class c1 set qos-group 3 set mpls experimental imposition 4 shape average percent 40 ! class c2 bandwidth remaining percent 10 set mpls experimental imposition 5 ! Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 160 OL-26077-02 Modular QoS Deployment Scenarios VPLS and VPWS QoS: Exampleclass c3 police rate percent 10 set mpls experimental imposition 6 ! class c4 bandwidth remaining percent 10 set mpls experimental imposition 7 ! class class-default ! end policy-map interface GigabitEthernet0/2/0/0 l2transport description PE to CE connection service-policy input p1 ! l2vpn bridge group examples bridge-domain vpls-bridge interface GigabitEthernet0/2/0/0 ! vfi pe12link neighbor 10.0.0.2 pw-id 12 ! ! vfi pe13link neighbor 10.0.0.3 pw-id 13 ! ! ! ! ! In the network designed and configured according to this example, and with VPLS and VPWS enabled, the packets that meet the match criteria receive QoS treatment according to the policy actions defined in the policy: • If a VPLS multicast packet arrives on the ingress interface of the PE router, it matches class c1. • If a VPLS broadcast packet arrives on the ingress interface of the PE router, it matches class c2. • If a VPLS control packet arrives on the ingress interface of the PE router with MAC address ranging from 01-80-C2-00-00-00 to 01-80-C2-00-00-3F, it matches class c3. • If an ARP packet arrives on the ingress interface of the PE router, it matches class c4. Related Information The information in this module focuses on the QoS implementation of features that are described in other technology guides. The following table indicates the guides where you can find more information about these features. Feature Guide “Configuring Modular QoS Packet Classification and Marking” and “Configuring Modular QoS Congestion Management” in this guide 802.1ad DEI Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 161 Modular QoS Deployment Scenarios Related InformationFeature Guide Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Configuration Guide Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Command Reference Frame Relay Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Configuration Guide Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Command Reference IP HeaderCompression Cisco ASR 9000 Series Aggregation Services Router L2VPN and Ethernet Services Configuration Guide Cisco ASR 9000 Series Aggregation Services Router L2VPN and Ethernet Services Command Reference L2VPN Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Configuration Guide Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Command Reference MLPPP/MLFR Cisco ASR 9000 Series Aggregation Services Router MPLS Configuration Guide Cisco ASR 9000 Series Aggregation Services Router MPLS Command Reference MPLS Cisco ASR 9000 Series Aggregation Services Router Multicast Configuration Guide Cisco ASR 9000 Series Aggregation Services Router Multicast Command Reference QoS on Multicast VPN Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Configuration Guide Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Command Reference QoS on NxDS0 Interfaces Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 162 OL-26077-02 Modular QoS Deployment Scenarios Related InformationC H A P T E R 7 Configuring Hierarchical Modular QoS Hierarchical QoS allows you to specify QoS behavior at multiple policy levels, which provides a high degree of granularity in traffic management. Line Card, SIP, and SPA Support Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 Enhanced Hierarchical Ingress no yes Policing Hierarchical Policing yes yes Hierarchical QoS yes yes Three-Parameter Scheduler yes yes Feature History for Hierarchical QoS on Cisco ASR 9000 Series Routers Release Modification The Hierarchical Policing feature was introduced on Cisco ASR 9000 Series Routers on ASR 9000 Ethernet Line Cards. The Hierarchical QoS feature was introduced on Cisco ASR 9000 Series Routers on ASR 9000 Ethernet Line Cards. The Three-Parameter Scheduler feature was introduced on Cisco ASR 9000 Series Routers on ASR 9000 Ethernet Line Cards. Release 3.7.1 The Hierarchical QoS feature wassupported on the SIP 700 for the ASR 9000. (two-level policies only) Release 3.9.0 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 163The Enhanced Hierarchical Ingress Policing feature was introduced on Cisco ASR 9000 Series Routers on the SIP 700 for the ASR 9000. The Hierarchical Policing feature was supported on Cisco ASR 9000 Series Routers on the SIP 700 for the ASR 9000. For the Hierarchical QoS feature, support was added for three-level policies on the SIP 700 for the ASR 9000. The Three-Parameter Scheduler feature was supported on the SIP 700 for the ASR 9000. Release 4.0.0 • How to Configure Hierarchical QoS, page 164 • Verifying the Configuration of Hierarchical Policies, page 180 • Additional References, page 181 How to Configure Hierarchical QoS When configuring hierarchical QoS, consider the following guidelines: • When defining polices,start at the bottom level of the hierarchy. For example, for a two-level hierarchical policy, define the bottom-level policy and then the top-level policy. For a three-level hierarchical policy, define the bottom-level policy, the middle-level policy, and then the top-level policy. • Do not specify the input or output keyword in the service-policy command when configuring a bottom-level policy within a top-level policy. • Configure bottom-level policies only in middle-level and top-level policies. Configuring the Three-Parameter Scheduler When configuring the Three-Parameter Scheduler, consider the following guidelines: • To use the three-parameter scheduler, a queueing class must be enabled. To enable a queueing class, you must configure at least one of the three parameters. When at least one parameter is configured, a queue is assigned to the class. • If you configure only one parameter, the scheduler uses default values for the other two parameters. • You can configure all 3 parameters in the same class. • Minimum bandwidth must be less than maximum bandwidth. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 164 OL-26077-02 Configuring Hierarchical Modular QoS How to Configure Hierarchical QoSASR 9000 Ethernet Line Cards SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. shape average {percent percentage | rate [units]} 5. exit 6. policy-map policy-name 7. class class-default 8. bandwidth {rate [units] | percent percentage-value} or bandwidth remaining [percent percentage-value | ratio ratio-value] or shape average {percent percentage | rate [units]} 9. service-policy policy-map-name 10. end 11. or commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 policy-map policy-name Creates or modifies the bottom-level policy. Example: RP/0/RSP0/CPU0:router(config)# policy-map bottom-child Step 2 Assignsthe traffic classthat you specify to the policy map. Enters policy map class configuration mode. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class Bronze Step 3 shape average {percent percentage | rate [units]} Shapes traffic to the indicated bit rate. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# shape average 1 mbps Step 4 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 165 Configuring Hierarchical Modular QoS Configuring the Three-Parameter SchedulerCommand or Action Purpose exit Exits policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 5 policy-map policy-name Creates or modifies the top-level policy. Example: RP/0/RSP0/CPU0:router(config-pmap)# policy-map Top-Parent Step 6 Step 7 class class-default Configures or modifies the parent class-default class. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class-default Note • You can configure only the class-default class in a parent policy. Do not configure any other traffic class. Specifies the minimum bandwidth allocated to a class as a percentage of link bandwidth. bandwidth {rate [units] | percent percentage-value} or bandwidth remaining [percent percentage-value Step 8 | ratio ratio-value] or shape average {percent percentage | rate [units]} Specifies how to allocate excess bandwidth to a class. Specifies maximum bandwidth as a percentage of link bandwidth (when other classes are not using all of their bandwidth share). Example: RP/0/RSP0/CPU0:router(config-pmap-c)# Note • You must configure at least one of the three bandwidth percent 30 parameters. or RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth remaining percent 80 or RP/0/RSP0/CPU0:router(config-pmap-c)# shape average percent 50 service-policy policy-map-name Applies a bottom-level policy to the top-level class-default class. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# service-policy Bottom-Child Step 9 Step 10 end Step 11 or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-pmap-c)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 166 OL-26077-02 Configuring Hierarchical Modular QoS Configuring the Three-Parameter SchedulerCommand or Action Purpose Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. SIP 700 for the ASR 9000 SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. bandwidth {rate [units] | percent percentage-value} or bandwidth remaining [percent percentage-value | ratio ratio-value] or shape average {percent percentage | rate [units]} 5. exit 6. policy-map policy-name 7. class class-default 8. shape average {percent percentage | rate [units]} 9. service-policy policy-map-name 10. end 11. or commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 167 Configuring Hierarchical Modular QoS Configuring the Three-Parameter SchedulerCommand or Action Purpose policy-map policy-name Creates or modifies the bottom-level policy. Example: RP/0/RSP0/CPU0:router(config)# policy-map bottom-child Step 2 Assignsthe traffic classthat you specify to the policy map. Enters policy map class configuration mode. class class-name Example: RP/0/RSP0/CPU0:router(config-pmap)# class Bronze Step 3 Specifies the minimum bandwidth allocated to a class as a percentage of link bandwidth. bandwidth {rate [units] | percent percentage-value} or bandwidth remaining [percent percentage-value Step 4 | ratio ratio-value] or shape average {percent percentage | rate [units]} Specifies how to allocate excess bandwidth to a class. Specifies maximum bandwidth as a percentage of link bandwidth (when other classes are not using all of their bandwidth share). Example: RP/0/RSP0/CPU0:router(config-pmap-c)# Note • You must configure at least one of the three bandwidth percent 30 parameters. or RP/0/RSP0/CPU0:router(config-pmap-c)# bandwidth remaining percent 80 or RP/0/RSP0/CPU0:router(config-pmap-c)# shape average percent 50 exit Exits policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# exit Step 5 policy-map policy-name Creates or modifies the top-level policy. Example: RP/0/RSP0/CPU0:router(config-pmap)# policy-map Top-Parent Step 6 Step 7 class class-default Configures or modifies the parent class-default class. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class-default Note • You can configure only the class-default class in a parent policy. Do not configure any other traffic class. shape average {percent percentage | rate [units]} (Optional) Shapes traffic to the indicated bit rate. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# shape average 1 mbps Step 8 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 168 OL-26077-02 Configuring Hierarchical Modular QoS Configuring the Three-Parameter SchedulerCommand or Action Purpose service-policy policy-map-name Applies a bottom-level policy to the top-level class-default class. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# service-policy Bottom-Child Step 9 Step 10 end Step 11 or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-pmap-c)# commit Entering yes saves configuration changes to the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Attaching Hierarchical Policies to Physical and Virtual Links To attach hierarchical policies to interfaces, subinterfaces, virtual circuits, and virtual LANs, use the service-policy {input | output} policy-map-name command. SUMMARY STEPS 1. configure 2. interface type interface-path-id 3. service-policy {input | output} policy-map-name 4. end 5. or commit Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 169 Configuring Hierarchical Modular QoS Attaching Hierarchical Policies to Physical and Virtual LinksDETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 interface type interface-path-id Specifies the interface to attach the hierarchical policy. Example: RP/0/RSP0/CPU0:router(config)# interface pos 0/2/0/0 Step 2 service-policy {input | output} Attaches the policy map you specify. policy-map-name Step 3 • input—Apply the QoS policy to inbound packets. Example: RP/0/RSP0/CPU0:router(config-if)# service-policy input All_Traffic • output—Apply the QoS policy to outbound packets. • policy-map-name—Name of a previously configured top-level policy map Step 4 end Step 5 or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-pmap-c)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting (yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-pmap-c)# commit Entering yessaves configuration changesto the running configuration file, exits the configuration session, and returns the router to EXEC mode. Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leavesthe router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 170 OL-26077-02 Configuring Hierarchical Modular QoS Attaching Hierarchical Policies to Physical and Virtual LinksConfiguring Enhanced Hierarchical Ingress Policing The difference between configuring enhanced hierarchical ingress policing and configuring hierarchical ingress policing is the addition of the child-conform-aware command. When used in the parent policer, the child-conform-aware command preventsthe parent policer from dropping any ingress traffic that conforms to the maximum rate specified in the child policer. Restrictions Enhanced Hierarchical Ingress Policing has the following limitations: • Ingress direction only. • Sum of all child policer rates cannot be greater than the parent policer rate. • Single-rate two-color policer (color blind) only. • Configurations that specify burst size in the police rate command are supported; configurations that specify peak burst become single-rate three-color policers and are therefore rejected. • Configure the child-conform-aware command only in the parent policer. SUMMARY STEPS 1. configure 2. policy-map policy-name 3. class class-name 4. service-policy policy-map-name 5. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-rate value [units]] [peak-burst peak-burst [burst-units]] 6. child-conform-aware 7. conform-action [drop | set options | transmit] 8. exceed-action [drop | set options | transmit] 9. end or commit DETAILED STEPS Command or Action Purpose configure Enters global configuration mode. Example: RP/0/RSP0/CPU0:router# configure Step 1 Step 2 policy-map policy-name Enters policy map configuration mode. Example: RP/0/RSP0/CPU0:router(config)# policy-map parent Creates or modifies a policy map that can be attached to one or more interfaces to specify a service policy. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 171 Configuring Hierarchical Modular QoS Configuring Enhanced Hierarchical Ingress PolicingCommand or Action Purpose Step 3 class class-name Enters policy map class configuration mode. Example: RP/0/RSP0/CPU0:router(config-pmap)# class class-default Specifies the name of the class whose policy you want to create or change. Applies the bottom-level policy map to the parent class-default class. service-policy policy-map-name Example: RP/0/RSP0/CPU0:router(config-pmap-c)# service-policy child Step 4 Note • Do not specify an input or output keyword. Configures traffic policing and enters policy map police configuration mode. police rate {value [units] | percent percentage} [burst burst-size [burst-units]] [peak-rate value [units]] [peak-burst peak-burst [burst-units]] Step 5 Example: RP/0/RSP0/CPU0:router(config-pmap-c)# police rate percent 50 Prevents the parent policer from dropping any ingress traffic that conforms to the maximum rate specified in a child policer. child-conform-aware Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# child-conform-aware Step 6 Configures the action to take on packets that conform to the rate limit. The allowed action is: conform-action [drop | set options | transmit] Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# conform-action transmit Step 7 transmit—Transmits the packets. Configures the action to take on packets that exceed the rate limit. The allowed action is: exceed-action [drop | set options | transmit] Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# exceed-action drop Step 8 drop—Drops the packet. Step 9 end or commit Saves configuration changes. Example: RP/0/RSP0/CPU0:router(config-pmap-c-police)# end • When you issue the end command, the system prompts you to commit changes: Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]: or RP/0/RSP0/CPU0:router(config-pmap-c-police)# commit Entering yes saves configuration changes to the running configuration file, exitsthe configuration session, and returns the router to EXEC mode. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 172 OL-26077-02 Configuring Hierarchical Modular QoS Configuring Enhanced Hierarchical Ingress PolicingCommand or Action Purpose Entering no exits the configuration session and returns the router to EXEC mode without committing the configuration changes. Entering cancel leaves the router in the current configuration session without exiting or committing the configuration changes. • Use the commit command to save the configuration changes to the running configuration file and remain within the configuration session. Two-Level Hierarchical Queueing Policy: Example The following example shows a two-level policy applied at the Multilink Frame Relay main interface. The same policy can be applied at Multilink PPP main interface. class-map match-any video match precedence 1 end-class-map ! class-map match-any premium match precedence 2 3 end-class-map ! class-map match-any voice-ip match precedence 0 end-class-map ! class-map match-any best-effort match precedence 4 end-class-map policy-map parent_shape class class-default service-policy child_policy shape average percent 90 ! end-policy-map ! policy-map child_policy class voice-ip priority level 1 police rate percent 20 ! ! class video bandwidth percent 40 ! class premium bandwidth percent 10 random-detect precedence 2 10 ms 100 ms random-detect precedence 3 20 ms 200 ms queue-limit 200 ms ! class best-effort Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 173 Configuring Hierarchical Modular QoS Two-Level Hierarchical Queueing Policy: Examplebandwidth percent 20 queue-limit 200 ms ! class class-default ! end-policy-map ! interface Multilink0/2/1/0/1 service-policy output parent_shape encapsulation frame-relay frame-relay intf-type dce Three-Level Hierarchical Queueing Policy: Examples Three-Level Hierarchical Queueing Policy: Examples In this example, policy grand-parent is applied to the main Ethernet interface. The grand-parent policy limits all outbound traffic of the interface up to 500 Mbps. The parent policy has class vlan1 and vlan2, and traffic in vlan1 or vlan2 is limited to 40 percent of 500 Mbps. The policy child_policy classifies traffic based on different services and allocates bandwidth for each class accordingly. class-map match-any video match precedence 1 end-class-map ! class-map match-any premium match precedence 2 3 end-class-map ! class-map match-any voice-ip match precedence 0 end-class-map ! class-map match-any best-effort match precedence 4 end-class-map class-map match-any vlan1 match vlan 1 end-class-map class-map match-any vlan2 match vlan 2 end-class-map policy-map grand-parent class class-default shape average 500 Mbps service-policy parent ! end-policy-map policy-map parent class vlan1 service-policy child_policy shape average percent 40 ! class vlan2 service-policy child_policy shape average percent 40 ! end-policy-map ! policy-map child_policy Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 174 OL-26077-02 Configuring Hierarchical Modular QoS Three-Level Hierarchical Queueing Policy: Examplesclass voice-ip priority level 1 police rate percent 20 ! ! class video bandwidth percent 40 ! class premium bandwidth percent 10 random-detect precedence 2 10 ms 100 ms random-detect precedence 3 20 ms 200 ms queue-limit 200 ms ! class best-effort bandwidth percent 20 queue-limit 200 ms ! class class-default ! end-policy-map interface GigabitEthernet0/0/0/9 service-policy output grand-parent SIP 700 for the ASR 9000 In this example, the policy parent_policy is applied to the Multilink Frame Relay main interface. The policy parent_policy hastwo classes, which match on Frame Relay DLCIs. The Multilink Frame Relay main interface has two Frame Relay PVCs configured (DLCI 16, DLCI 17). interface Multilink0/2/1/0/1 mtu 1504 service-policy output parent_policy encapsulation frame-relay frame-relay intf-type dce ! policy-map parent_policy class parentQ_1 service-policy child_queuing_policy shape average 64 kbps ! class parentQ_2 service-policy child_queuing_policy shape average 1 mbps ! class class-default ! end-policy-map ! class-map match-any parentQ_1 <----- class map parent class dlci=16 match frame-relay dlci 16 end-class-map ! class-map match-any parentQ_2 <----- class map parent class dlci=17 match frame-relay dlci 17 end-class-map ! interface Multilink0/2/1/0/1.16 point-to-point <------ dlci 16 pvc config ipv4 address 192.1.1.1 255.255.255.0 pvc 16 encap cisco ! ! interface Multilink0/2/1/0/1.17 point-to-point <------ dlci 17 pvc config Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 175 Configuring Hierarchical Modular QoS Three-Level Hierarchical Queueing Policy: Examplesipv4 address 192.1.2.1 255.255.255.0 pvc 17 encap cisco ! ! policy-map child_queuing_policy <--------- child policy map class voice-ip priority level 1 police rate percent 20 ! ! class video bandwidth percent 40 ! class premium service-policy gchild_policy bandwidth percent 10 random-detect discard-class 2 10 ms 100 ms random-detect discard-class 3 20 ms 200 ms queue-limit 200 ms ! class best-effort bandwidth percent 20 queue-limit 200 ms ! class class-default ! end-policy-map ! policy-map gchild_policy <-------- grandchild policy map class premium_g1 police rate percent 10 ! set discard-class 2 ! class premium_g2 police rate percent 50 ! set discard-class 3 ! class class-default ! end-policy-map ! show run class-map <----------- shows all class-map configs Mon Aug 2 11:35:19.479 UTC class-map match-any video match precedence 1 end-class-map ! class-map match-any premium match precedence 2 3 end-class-map ! class-map match-any voice-ip match precedence 0 end-class-map ! class-map match-any parentQ_1 match frame-relay dlci 16 end-class-map ! class-map match-any parentQ_2 match frame-relay dlci 17 end-class-map ! class-map match-any premium_g1 match precedence 2 end-class-map ! class-map match-any premium_g2 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 176 OL-26077-02 Configuring Hierarchical Modular QoS Three-Level Hierarchical Queueing Policy: Examplesmatch precedence 3 end-class-map ! class-map match-any best-effort match precedence 4 end-class-map Three-Parameter Scheduler: Examples Three-Parameter Scheduler: Examples This example shows how to configure a three-parameter scheduler in a two-level hierarchical policy. policy-map Bottom-ChildA class A1 shape average 400 kbps class A2 shape average 400 kbps policy-map Bottom-ChildB class B1 shape average 250 kbps class B2 shape average 450 kbps policy-map Top-Parent class parentA shape average 500 kbps bandwidth percent 30 bandwidth remaining percent 80 service-policy Bottom-ChildA class parentB shape average 500 kbps bandwidth percent 60 bandwidth remaining percent 10 service-policy Bottom-ChildB SIP 700 for the ASR 9000 This example shows how to configure a three-parameter scheduler in a two-level hierarchical policy. policy-map Bottom-Child class A bandwidth percent 30 bandwidth remaining percent 80 shape average percent 50 class B bandwidth percent 60 bandwidth remaining percent 10 class class-default exit policy-map Top-Parent class-default shape average 1 mbps service-policy Bottom-Child Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 177 Configuring Hierarchical Modular QoS Three-Parameter Scheduler: ExamplesHierarchical Policing: Examples Hierarchical Policing: Examples This example shows a two-level policy with police actions at each level. There are two classes in the top level, one for each customer. Aggregated traffic from each customer is subject to a rate limit as specified by the police rate command in the top level. Traffic in different classesin the bottom level islimited by an additional set of police actions to control different types of traffic for each customer. class-map match-any customera match vlan 10-14 class-map match-any customerb match vlan 15-19 class-map match-any prec1 match precedence 1 class-map match-any prec3 match precedence 3 policy-map parent class customera service-policy childa bandwidth remaining ratio 10 police rate percent 50 conform-action transmit exceed-action drop class customerb service-policy childb bandwidth remaining ratio 100 police rate percent 70 conform-action transmit exceed-action drop policy-map childa class prec1 police rate percent 25 conform-action transmit exceed-action drop class prec3 police rate percent 25 conform-action transmit exceed-action drop policy-map childb class prec1 police rate percent 30 conform-action transmit exceed-action drop class prec3 police rate percent 30 conform-action transmit exceed-action drop SIP 700 for the ASR 9000 In this example, policers are specified in the policy child in class Prec1 and class Prec3, and also in the class-default in the policy parent. The policers in the child policy, police traffic in class Prec1 at 30 percent (of 50 percent), police traffic in class Prec3 at 60 percent (of 50 percent) and police any other traffic at 10 percent (of 50 percent). Cumulatively, all traffic on the interface is policed at 50 percent of the interface rate by the policer in the parent policy. class-map match-any prec1 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 178 OL-26077-02 Configuring Hierarchical Modular QoS Hierarchical Policing: Examplesmatch precedence 1 class-map match-any prec3 match precedence 3 policy-map parent class class-default service-policy child police rate percent 50 conform-action transmit exceed-action drop policy-map child class prec1 police rate percent 30 conform-action transmit exceed-action drop class prec3 police rate percent 60 conform-action transmit exceed-action drop class class-default police rate percent 10 conform-action transmit exceed-action drop Attaching Service Policies to Physical and Virtual Links: Examples Physical Link: Example In this example, the p1 policy is applied to a Gigabit Ethernet interface: interface gigabitethernet 0/2/0/0 service-policy input p1 Virtual Link: Example In this example, the p2 policy is applied to the private virtual circuit (PVC) under a multilink Frame Relay subinterface. A QoS policy can be applied only to a PVC under a Frame Relay subinterface; it cannot be applied directly to a Frame Relay subinterface. interface Multilink0/2/1/0/1.16 point-to-point encapsulation frame-relay ipv4 address 192.1.1.1 255.255.255.0 pvc 16 service-policy output p2 encap cisco Enhanced Hierarchical Ingress Policing: Example This example shows parent and child policies in which two classes are defined in the child policy. In class AF1, the exceed action is set to an action other than to drop traffic. If the child-conform-aware command were not configured in the parent policy, the parent policer would drop traffic that matches the conform rate of the child policer but exceeds the conform rate of the parent policer. When used in the parent policer, the child-conform-aware command preventsthe parent policer from dropping any ingress traffic that conforms to the committed rate specified in the child policer. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 179 Configuring Hierarchical Modular QoS Attaching Service Policies to Physical and Virtual Links: ExamplesIn this example, class EF in the child policy is configured with a committed rate of 1 Mbps, a conform action and an exceed action. The traffic that is below 1 Mbps is presented to the parent policer with the MPLS EXP bit set to 4, and traffic that exceeds 1 Mbps is dropped. Class AF1 in the child policy is configured with a committed rate of 1 Mbps, a conform action and an exceed action. The traffic that is below 1 Mbps is presented to the parent policer with the MPLS EXP bit set to 3, and traffic that exceeds 1 Mbps is presented to the parent policer with the MPLS EXP bit set to 2. With this child policy configuration, the parent policer sees traffic from the child classes as exceeding its committed rate of 2 Mbps. Without the child-conform-aware command in the parent policer, the parent polices to 2 Mbps, which can result into dropping some conformed traffic from class EF in the child policy. When the child-conform-aware command is configured in the parent policer, the parent policer does not drop any traffic that conforms under the child policy. policy-map parent class class-default service-policy child police rate 2 mbps child-conform-aware conform-action transmit exceed-action drop policy-map child class EF police rate 1 mbps conform-action set mpls experimental imposition 4 exceed-action drop class AF1 police rate 1 mbps conform-action set mpls experimental imposition 3 exceed-action set mpls experimental imposition 2 Verifying the Configuration of Hierarchical Policies To verify hierarchical policies, enter any of the following commands in privileged EXEC mode: Displays policy configuration information for all classes configured for all service policies on the specified interface. show policy-map interface Displays QoS information for all classesin the service policy that is attached to the specified interface. show qos interface Displays the configuration of all class maps configured on the router. show running-config class-map Displays the configuration of all policy maps configured on the router. show running-config policy-map Displays the configuration of all classes contained in the policy map you specify. show running-config policy-map policy-map-name Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 180 OL-26077-02 Configuring Hierarchical Modular QoS Verifying the Configuration of Hierarchical PoliciesAdditional References The following sections provide references related to implementing Hierarchical QoS. Related Documents Related Topic Document Title Cisco ASR 9000 Series Aggregation Services Router Getting Started Guide Initial system bootup and configuration Cisco ASR 9000 Series Aggregation Services Router Master Command Listing Master command reference Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference QoS commands “Configuring AAA Services on Cisco ASR 9000 Series Router” module of Cisco Cisco ASR 9000 Series Aggregation Services Router System Security Configuration Guide User groups and task IDs Standards Standards Title No new or modified standards are supported by — this feature, and support for existing standards has not been modified by this feature. MIBs MIBs MIBs Link To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/ cmtk/mibs.shtml — Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 181 Configuring Hierarchical Modular QoS Additional ReferencesRFCs RFCs Title No new or modified RFCs are supported by this — feature, and support for existing RFCs has not been modified by this feature. Technical Assistance Description Link The Cisco Technical Support website contains http://www.cisco.com/techsupport thousands of pages of searchable technical content, including links to products, technologies,solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 182 OL-26077-02 Configuring Hierarchical Modular QoS RFCsC H A P T E R 8 Configuring Modular QoS on Link Bundles A link bundle is a group of one or more ports that are aggregated together and treated as a single link. This module describes QoS on link bundles. Line Card, SIP, and SPA Support Feature ASR 9000 Ethernet Line Cards SIP 700 for the ASR 9000 QoS on Link Bundles yes yes Feature History for Configuring QoS on Link Bundles on Cisco ASR 9000 Series Routers Release Modification The QoS on Link Bundles feature was introduced on ASR 9000 Ethernet Line Cards. Release 3.9.0 • Link Bundling Overview, page 183 • Load Balancing, page 184 • QoS and Link Bundling, page 185 • Additional References, page 186 Link Bundling Overview The Link Bundling feature allows you to group multiple point-to-point links together into one logical link and provide higher bidirectional bandwidth, redundancy, and load balancing between two routers. A virtual interface is assigned to the bundled link. The component links can be dynamically added and deleted from the virtual interface. The virtual interface istreated as a single interface on which one can configure an IP address and othersoftware features used by the link bundle. Packetssent to the link bundle are forwarded to one of the linksin the bundle. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 183A link bundle is simply a group of ports that are bundled together and act as a single link. The advantages of link bundles are as follows: • Multiple links can span several line cards to form a single interface. Thus, the failure of a single link does not cause a loss of connectivity. • Bundled interfaces increase bandwidth availability, because traffic is forwarded over all available members of the bundle. Therefore, traffic can flow on the available links if one of the links within a bundle fails. Bandwidth can be added without interrupting packet flow. All the individual links within a single bundle must be of the same type and the same speed. Cisco IOS XR software supports the following methods of forming bundles of Ethernet interfaces: • IEEE 802.3ad—Standard technology that employs a Link Aggregation Control Protocol (LACP) to ensure that all the member links in a bundle are compatible. Links that are incompatible or have failed are automatically removed from a bundle. • EtherChannel —Cisco proprietary technology that allows the user to configure links to join a bundle, but has no mechanisms to check whether the links in a bundle are compatible. Load Balancing Load balancing is supported on all links in the bundle. Load balancing function is a forwarding mechanism to distribute traffic over multiple links based on layer 3 routing information in the router. There are two types of load balancing schemes: • Per-Destination Load Balancing • Per-Packet Load Balancing When a traffic stream arrives at the router, per-packet load balancing allows the traffic to be evenly distributed among multiple equal cost links. Per-packet schemes make routing decision based on round-robin techniques, regardless of the individual source-destination hosts. Only Per-Destination Load Balancing is supported. Per-destination load balancing allows the router to distribute packets over one of the links in the bundle to achieve load sharing. The scheme isrealized through a hash calculating based on the source-destination address and user sessions. When the per-destination load balancing is enabled, all packets for a certain source-destination pair will go through the same link, though there are multiple links available. In other words, per-destination load balancing can ensure that packets for a certain source-destination pair could arrive in order. Layer 3 Load Balancing on Link Bundles By default, load balancing on Layer 2 link bundles is done based on the MAC SA/DA fields in the packet header. Layer 3 load balancing for link bundles is done on Ethernet Flow Points (EFPs) and is based on the IPv4 source and destination addressesin the packet.When Layer 3 service-specific load balancing is configured, all egressing bundles are load balanced based on the IPv4 source and destination addresses. When packets do not have IPv4 addresses, default load-balancing is used. Layer 3 load balancing for link bundles is enabled globally, using the following command: Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 184 OL-26077-02 Configuring Modular QoS on Link Bundles Load Balancinghw-module load-balance bundle l2-service l3-params QoS and Link Bundling All Quality of Service (QoS) features, currently supported on physical interfaces and subinterfaces, are also supported on all Link Bundle interfaces and subinterfaces. QoS is configured on Link Bundles in the same way that it is configured on individual interfaces. However, the following points should be noted: • When a QoS policy is applied on a bundle (ingress or egress directions), the policy is applied at each member interface. Any queues and policers in the policy map (ingress or egress directions) will be replicated on each bundle member. • If a QoS policy is not applied to a bundle interface or bundle VLAN, both the ingress and egress traffic will use the per link members port default queue. • Link bundle members may appear across multiple Network Processing Units and linecards. The shape rate specified in the bundle policymap is not an aggregate for all bundle members. The shape rate applied to the bundle will depend on the load balancing of the links. For example, if a policy map with a shape rate of 10 Mbps is applied to a bundle with two member links, and if the traffic is always load-balanced to the same member link, then an overall rate of 10 Mbps will apply to the bundle. However, if the traffic is load-balanced evenly between the two links, the overall shape rate for the bundle will be 20 Mbps. Example 1 shows how a traffic policy is applied on an Ethernet link bundle, in the ingress direction. The policy is applied to all interfaces that are members of the Ethernet link bundle. Example 1 Applying a Traffic Policy to an Ethernet Link Bundle interface Bundle-Ether bundle-id service-policy input policy-1 end QoS for POS link bundling For POS link bundles, percentage based bandwidth is supported for policers and output queues. Time based queue limit is supported for output queues. Input QoS Policy setup For input QoS, queuing is not supported and thus bandwidth is used for policer only. As a member link is added or removed from a bundle with input QoS configured, the aggregate bundle bandwidth for that affected line card will change. One input QoS policy instance is assigned for each SIP 700 line card that is part of the POS link bundle. Output QoS Policy setup When a member link is added to a bundle with output QoS configured, the policy-map of the bundle is applied to the member link. Example 2 shows the output QoS policy supported on POS link bundles. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 185 Configuring Modular QoS on Link Bundles QoS and Link BundlingExample 2 Output QoS policy supported on POS link bundles policy-map out-sample class voice priority level 1 police rate percent 10 class premium bandwidth percent 30 queue-limit 100 ms class class-default queue-limit 100 ms Additional References The following sections provide references related to implementing QoS on Link Bundles. Related Documents Related Topic Document Title Cisco ASR 9000 Series Aggregation Services Router Getting Started Guide Initial system bootup and configuration “Configuring Link Bundling on the Cisco ASR 9000 Series Router” module of Cisco ASR 9000 Series Aggregation Services Router Interface and Hardware Component Configuration Guide Link Bundling Cisco ASR 9000 Series Aggregation Services Router Master Command Listing Master command reference Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Command Reference QoS commands “Configuring AAA Services on Cisco ASR 9000 Series Router” module of Cisco Cisco ASR 9000 Series Aggregation Services Router System Security Configuration Guide User groups and task IDs Standards Standards Title No new or modified standards are supported by — this feature, and support for existing standards has not been modified by this feature. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 186 OL-26077-02 Configuring Modular QoS on Link Bundles Additional ReferencesMIBs MIBs MIBs Link To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/ cmtk/mibs.shtml — RFCs RFCs Title No new or modified RFCs are supported by this — feature, and support for existing RFCs has not been modified by this feature. Technical Assistance Description Link The Cisco Technical Support website contains http://www.cisco.com/techsupport thousands of pages of searchable technical content, including links to products, technologies,solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content. Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 187 Configuring Modular QoS on Link Bundles MIBs Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x 188 OL-26077-02 Configuring Modular QoS on Link Bundles Technical AssistanceI N D E X 802.1ad DEI 140 A AN ports 11 ANCP 11 ANCP adjacencies 9, 35 ANCP Adjacencies 10 ancp command 14 ANCP neighbors 16 ANCP Neighbors 22 ANCP Rate Adjustment 21, 26 ancp rate-adjustment command 21 ANCP Server Sender Name 22 B bandwidth command 67, 70, 71 Be 63 calculating 63 metering 63 See also excess burst.[Be 63 zzz] 63 bundle interfaces 101 C calculating 63 committed burst 63 excess burst 63 CBS, See committed burst. 62 class-based packet marking 118, 119, 120 configuring 118 set qos-group command 119, 120 class-map command 108 classification 2, 100, 101 QoS group 100 See IP precedence 101 classification (continued) summary 2 clear ancp neighbor 17, 18 clear ancp summary statistics 17, 18 commands 64 show interface 64 committed burst 62, 63 burst size 62 calculating 63 Configuring ANCP 10 conforming traffic 62 metering and conforming token bucket 62 congestion avoidance 4, 37 description 37 summary 4 CoS (class of service), defining classes 101 D default marking behavior 3 default traffic class 98 summary 98 tail drop 98 DEI 66, 102, 103 classification 102 congestion management 66 default marking 103 differentiated service model, classification 101 E EBS, See excess burst size. 63 Enabling ANCP 14 enhanced hierarchical ingress policing 171 configuring 171 exceeding token bucket 63 excess burst 63 calculation of 63 default size 63 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 IN-1excess burst (continued) police command 63 size 63 F Frame Relay QoS 141 G granularity 66 policer 66 H hierarchical ingress policing 65, 92 example 92 hierarchical policies 169, 180 attaching 169 verifying 180 I in-place policy modification 106, 134 (examples) 134 description 106 interface submode 113, 114, 115, 116, 117 service-policy command 113, 114, 115, 116, 117 interfaces 183 Link Bundling 183 IP header compression 145 IP precedence 100, 101, 102 QoS features supported 102 reset recommendation 102 default 102 edge router function 101 low-latency queueing (LLQ) 100 packet classification 101 IPv6 ACLs, QoS matching 96 L L2VPN QoS 146 M mapping 11 Mapping AN ports 18, 25 match access-group command 108, 109 match cos command 108, 109 match discard-class command 108, 109 match dscp command 108, 109 match precedence command 108, 110 match protocol command 108, 110 match qos-group command 108, 110 match vlan command 108, 110 MC-LAG 12 MLFR QoS 149 monitoring 64 bursts 64 MPLS QoS 151 MQC (modular QoS command-line interface), description 5 Multicast VPN 156 multiclass MLPPP with QoS 150 N Neighbor Adjacency Timing 10 NxDS0 interfaces 158 P packets 64 conforming or exceeding, determining 64 partitioning network, QoS packet marking 100 policers and shapers, description 55 policing 63 excess burst 63 policy map class submode 45, 46, 67, 70, 71, 119, 120, 121 bandwidth command 67, 70, 71 set cos command 119, 120, 121 set discard-class command 119, 121 set srp-priority command 119, 121 shape average command 45, 46 Port Down messages 11 Port Mapping 11 process restart 12 provider backbone bridge 3 default marking behavior 3 Q QoS (Quality of Service) 1, 2, 4, 55, 100 benefits 2 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x IN-2 OL-26077-02 IndexQoS (Quality of Service) (continued) characteristics 1 congestion mechanisms, policers and shapers 55 features 4, 100 class-based packet marking 100 traffic policing 4 traffic shaping 4 techniques 4, 55 congestion management 4, 55 queueing 55, 56 scheduling mechanism 55 strict priority 56 R Rate Adjustment 11 RFC 791, Internet Protocol 101 S service models, end-to-end, differentiated service 4 service-policy command 113, 114, 115, 116, 117 set cos command 119, 120, 121 set discard-class command 119, 121 set srp-priority command 119, 121 shape average command 45, 46 shape rate 11 show ancp neighbor 17, 18 show ancp neighbor summary 17, 18 show interface command 64 show policy-map interface command 113, 114, 115, 116, 117, 118 T token bucket 62 traffic class 97, 107 creating 107 major elements 97 traffic policer 58, 59, 64, 65 single-rate, two color policer 59 two-rate, three-color policer 64 peak information rate (PIR) 58 purpose 65 traffic policers and traffic shapers, use of traffic descriptor 97 traffic policing 4, 58, 59, 65 single-rate token bucket 59 description 58 packet marking 65 summary 4 traffic policy 98, 111, 113 attaching to an interface 113 creating 111 maximum number of traffic classes 98 purpose 98 traffic shaping 57 description 57 enabled 57 V verifying 180 hierarchical policies 180 VLAN subinterfaces 18 VPLS QoS 159 Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x OL-26077-02 IN-3 Index Cisco ASR 9000 Series Aggregation Services Router Modular Quality of Service Configuration Guide, Release 4.2.x IN-4 OL-26077-02 Index Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA http://www.cisco.com Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883 Cisco IOS XR XML API Guide Cisco IOS XR Software Release 4.1 April 2011 Text Part Number: OL-24657-01THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Cisco and the Cisco Logo are trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and other countries. A listing of Cisco's trademarks can be found at www.cisco.com/go/trademarks. Third party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1005R) Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental. Cisco IOS XR XML API Guide © 2011 Cisco Systems, Inc. All rights reserved.1 Cisco IOS XR XML API Guide OL-24657-01 C O N T E N T S Preface ix Changes to This Document ix Obtaining Documentation and Submitting a Service Request ix C H A P T E R 1 Cisco XML API Overview 1-1 Introduction 1-1 Definition of Terms 1-1 Cisco Management XML Interface 1-2 Cisco XML API and Router System Features 1-3 Cisco XML API Tags 1-3 Basic XML Request Content 1-4 Top-Level Structure 1-4 XML Declaration Tag 1-5 Request and Response Tags 1-5 ResultSummary Tag 1-5 Maximum Request Size 1-6 Minimum Response Content 1-6 Operation Type Tags 1-8 Native Data Operation Tags 1-8 Configuration Services Operation Tags 1-9 CLI Operation Tag 1-9 GetNext Operation Tag 1-9 Alarm Operation Tags 1-10 XML Request Batching 1-10 C H A P T E R 2 Cisco XML Router Configuration and Management 2-13 Target Configuration Overview 2-13 Configuration Operations 2-14 Additional Configuration Options Using XML 2-14 Locking the Running Configuration 2-15 Browsing the Target or Running Configuration 2-15 Getting Configuration Data 2-16 Browsing the Changed Configuration 2-17 Loading the Target Configuration 2-19Contents 2 Cisco IOS XR XML API Guide OL-24657-01 Setting the Target Configuration Explicitly 2-20 Saving the Target Configuration 2-21 Committing the Target Configuration 2-22 Commit Operation 2-22 Commit Errors 2-25 Loading a Failed Configuration 2-27 Unlocking the Running Configuration 2-28 Additional Router Configuration and Management Options Using XML 2-28 Getting Commit Changes 2-29 Loading Commit Changes 2-30 Clearing a Target Session 2-32 Rolling Back Configuration Changes to a Specified Commit Identifier 2-33 Rolling Back the Trial Configuration Changes Before the Trial Time Expires 2-33 Rolling Back Configuration Changes to a Specified Number of Commits 2-34 Getting Rollback Changes 2-35 Loading Rollback Changes 2-36 Getting Configuration History 2-38 Getting Configuration Commit List 2-41 Getting Configuration Session Information 2-43 Clear Configuration Session 2-44 Replacing the Current Running Configuration 2-45 Clear Configuration Inconsistency Alarm 2-46 C H A P T E R 3 Cisco XML Operational Requests and Fault Management 3-49 Operational Get Requests 3-49 Action Requests 3-50 Cisco XML and Fault Management 3-51 Configuration Change Notification 3-51 C H A P T E R 4 Cisco XML and Native Data Operations 4-53 Native Data Operation Content 4-53 Request Type Tag and Namespaces 4-54 Object Hierarchy 4-54 Main Hierarchy Structure 4-55 Dependencies Between Configuration Items 4-58 Null Value Representations 4-58 Operation Triggering 4-58 Native Data Operation Examples 4-59 Set Configuration Data Request: Example 4-60Contents 3 Cisco IOS XR XML API Guide OL-24657-01 Get Request: Example 4-62 Get Request of Nonexistent Data: Example 4-63 Delete Request: Example 4-65 GetDataSpaceInfo Request Example 4-66 C H A P T E R 5 Cisco XML and Native Data Access Techniques 5-67 Available Set of Native Data Access Techniques 5-67 XML Request for All Configuration Data 5-68 XML Request for All Configuration Data per Component 5-68 XML Request for All Data Within a Container 5-69 XML Request for Specific Data Items 5-71 XML Request with Combined Object Class Hierarchies 5-72 XML Request Using Wildcarding (Match Attribute) 5-75 XML Request for Specific Object Instances (Repeated Naming Information) 5-79 XML Request Using Operation Scope (Content Attribute) 5-82 Limiting the Number of Table Entries Returned (Count Attribute) 5-83 Custom Filtering (Filter Element) 5-85 XML Request Using the Mode Attribute 5-86 C H A P T E R 6 Cisco XML and Encapsulated CLI Operations 6-91 XML CLI Command Tags 6-91 CLI Command Limitations 6-92 C H A P T E R 7 Cisco XML and Large Data Retrieval 7-93 Iterators 7-93 Usage Guidelines 7-93 Examples Using Iterators to Retrieve Data 7-94 Large Response Division 7-97 Terminating an Iterator 7-97 Throttling 7-98 CPU Throttle Mechanism 7-99 Memory Throttle Mechanism 7-99 Streaming 7-99 Usage Guidelines 7-99 C H A P T E R 8 Cisco XML Security 8-101 Authentication 8-101 Authorization 8-101Contents 4 Cisco IOS XR XML API Guide OL-24657-01 Retrieving Task Permissions 8-102 Task Privileges 8-102 Task Names 8-103 Authorization Failure 8-104 Management Plane Protection 8-104 Inband Traffic 8-104 Out-of-Band Traffic 8-104 VRF 8-105 Access Control List 8-105 C H A P T E R 9 Cisco XML Schema Versioning 9-107 Major and Minor Version Numbers 9-107 Run-Time Use of Version Information 9-108 Placement of Version Information 9-109 Version Lag with the AllowVersionMisMatch Attribute Set as TRUE 9-110 Version Lag with the AllowVersionMismatch Attribute Set as FALSE 9-111 Version Creep with the AllowVersionMisMatch Attribute Set as TRUE 9-112 Version Creep with the AllowVersionMisMatch Attribute Set as FALSE 9-113 Retrieving Version Information 9-113 Retrieving Schema Detail 9-115 C H A P T E R 10 Alarms 10-117 Alarm Registration 10-117 Alarm Deregistration 10-118 Alarm Notification 10-119 C H A P T E R 11 Error Reporting in Cisco XML Responses 11-121 Types of Reported Errors 11-121 Error Attributes 11-122 Transport Errors 11-122 XML Parse Errors 11-122 XML Schema Errors 11-123 Operation Processing Errors 11-125 Error Codes and Messages 11-126Contents 5 Cisco IOS XR XML API Guide OL-24657-01 C H A P T E R 12 Summary of Cisco XML API Configuration Tags 12-127 C H A P T E R 13 XML Transport and Event Notifications 13-129 TTY-Based Transports 13-129 Enabling the TTY XML Agent 13-129 Enabling a Session from a Client 13-129 Sending XML Requests and Receiving Responses 13-130 Configuring Idle Session Timeout 13-130 Ending a Session 13-130 Errors That Result in No XML Response Being Produced 13-130 Dedicated Connection Based Transports 13-131 Enabling the Dedicated XML Agent 13-131 Enabling a Session from a Client 13-131 Sending XML Requests and Receiving Responses 13-132 Configuring Idle Session Timeout 13-132 Ending a Session 13-132 Errors That Result in No XML Response Being Produced 13-132 SSL Dedicated Connection based Transports 13-132 Enabling the SSL Dedicated XML Agent 13-133 Enabling a Session from a Client 13-133 Sending XML Requests and Receiving Responses 13-133 Configuring Idle Session Timeout 13-133 Ending a Session 13-134 Errors That Result in No XML Response Being Produced 13-134 C H A P T E R 14 Cisco XML Schemas 14-135 XML Schema Retrieval 14-135 Common XML Schemas 14-136 Component XML Schemas 14-136 Schema File Organization 14-136 Schema File Upgrades 14-137 C H A P T E R 15 Network Configuration Protocol 15-139 Starting a NETCONF Session 15-139 Ending a NETCONF Agent Session 15-140 Starting an SSH NETCONF Session 15-140 Ending an SSH NETCONF Agent Session 15-141 Configuring a NETCONF agent 15-141Contents 6 Cisco IOS XR XML API Guide OL-24657-01 Limitations of NETCONF in Cisco IOS XR 15-142 Configuration Datastores 15-142 Configuration Capabilities 15-142 Transport (RFC4741 and RFC4742) 15-142 Subtree Filtering (RFC4741) 15-142 Protocol Operations (RFC4741) 15-144 Event Notifications (RFC5277) 15-145 C H A P T E R 16 Cisco IOS XR Perl Scripting Toolkit 16-147 Cisco IOS XR Perl Scripting Toolkit Concepts 16-148 Security Implications for the Cisco IOS XR Perl Scripting Toolkit 16-148 Prerequisites for Installing the Cisco IOS XR Perl Scripting Toolkit 16-148 Installing the Cisco IOS XR Perl Scripting Toolkit 16-149 Using the Cisco IOS XR Perl XML API in a Perl Script 16-150 Handling Types of Errors for the Cisco IOS XR Perl XML API 16-150 Starting a Management Session on a Router 16-150 Closing a Management Session on a Router 16-152 Sending an XML Request to the Router 16-152 Using Response Objects 16-153 Using the Error Objects 16-154 Using the Configuration Services Methods 16-154 Using the Cisco IOS XR Perl Data Object Interface 16-157 Understanding the Perl Data Object Documentation 16-158 Generating the Perl Data Object Documentation 16-158 Creating Data Objects 16-159 Specifying the Schema Version to Use When Creating a Data Object 16-161 Using the Data Operation Methods on a Data Object 16-161 get_data Method 16-161 find_data Method 16-162 get_keys Method 16-162 get_entries Method 16-163 set_data Method 16-163 delete_data Method 16-164 Using the Batching API 16-164 batch_start Method 16-164 batch_send Method 16-165 Displaying Data and Keys Returned by the Data Operation Methods 16-165 Specifying the Session to Use for the Data Operation Methods 16-166Contents 7 Cisco IOS XR XML API Guide OL-24657-01 Cisco IOS XR Perl Notification and Alarm API 16-166 Registering for Alarms 16-166 Deregistering an Existing Alarm Registration 16-167 Deregistering All Registration on a Particular Session 16-167 Receiving an Alarm on a Management Session 16-167 Using the Debug and Logging Facilities 16-168 Debug Facility Overview 16-168 Logging Facility Overview 16-169 Examples of Using the Cisco IOS XR Perl XML API 16-170 Configuration Examples 16-171 Setting the IP Address of an Interface 16-171 Configuring a Simple BGP Neighbor 16-172 Adding a List of Neighbors to a BGP Neighbor Group 16-172 Displaying the Members of Each BGP Neighbor Group 16-173 Setting Up ISIS on an Interface 16-173 Finding the Circuit Type That is Currently Configured for an Interface for ISIS 16-173 Configuring a New Instance, Area, and Interface for OSPF 16-175 Getting a List of the Usernames That are Configured on the Router 16-175 Finding the IP Address of All Interfaces That Have IP Configured 16-175 Adding an Entry to the Access Control List 16-176 Denying Access to a Set of Interfaces from a Particular IP Address 16-176 Configuring a New Static Route Entry 16-177 Operational Examples 16-177 Retrieving the Operational Information for All Interfaces on the Router 16-178 Retrieving the Link State Database for a Particular Level for ISIS 16-178 Getting a List of All Interfaces on the System 16-179 Retrieving the Combined Interface and IP Information for Each Interface 16-179 Listing the Hostname and Interface for Each ISIS Neighbor 16-180 Recreating the Output of the show ip interfaces CLI Command 16-180 Producing a Textual Output Similar to the show bgp neighbors CLI Command 16-180 Displaying Tabular XML Data in a Generic HTML Table Using XSLT 16-181 Displaying the Interface State in a Customized HTML Table 16-182 Displaying the BGP Neighbor Operational Data in a Complex HTML Format 16-182 Performing Actions Whenever Certain Events Occur 16-183 Sample BGP Configuration 17-185 GL O S S A R Y I N D E XContents 8 Cisco IOS XR XML API Guide OL-24657-01ix Cisco IOS XR XML API Guide OL-24657-01 Preface The XML application programming interface (API) is available for use on any Cisco platform running Cisco IOS XR software. This document describes the XML API provided to developers of external management applications. The XML interface provides a mechanism for router configuration and monitoring using XML formatted request and response streams. The XML schemas referenced in this guide are used by the management application developer to integrate client applications with the router programmable interface. The preface contains these sections: • Changes to This Document, page ix • Obtaining Documentation and Submitting a Service Request, page ix Changes to This Document Table 1 lists the technical changes made to this document since it was first published. Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What’s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html Subscribe to the What’s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS Version 2.0. Table 1 Changes to This Document Revision Date Change Summary OL-24657-01 April 2011 Initial release of this document.x Cisco IOS XR XML API Guide OL-24657-01 PrefaceC H A P T E R 1-1 Cisco IOS XR XML API Guide OL-24657-01 1 Cisco XML API Overview This chapter contains these sections: • Introduction, page 1-1 • Cisco Management XML Interface, page 1-2 • Cisco XML API and Router System Features, page 1-3 • Cisco XML API Tags, page 1-3 Introduction This Cisco IOS XR XML API Guide explains how to use the Cisco XML API to configure routers or request information about configuration, management, or operation of the routers. The goal of this guide is to help management application developers write client applications to interact with the Cisco XML infrastructure on the router, and to use the Management XML API to build custom end-user interfaces for configuration and information retrieval and display. The XML application programming interface (API) provided by the router is an interface used for development of client applications and perl scripts to manage and monitor the router. The XML interface is specified by XML schemas. The XML API provides a mechanism, which exchanges XML formatted request and response streams, for router configuration and monitoring. Client applications can be used to configure the router or to request status information from the router, by encoding a request in XML API tags and sending it to the router. The router processes the request and sends the response to the client by again encoding the response in XML API tags. This guide describes the XML requests that can be sent by external client applications to access router management data, and also details the responses to the client by the router. Customers use a variety of vendor-specific CLI scripts to manage their routers because no alternative programmatic mechanism is available. In addition, a common framework has not been available to develop CLI scripts. In response to this need, the XML API provides the necessary common framework for development, deployment, and maintenance of router management. Note The XML API code is available for use on any Cisco platform that runs Cisco IOS XR software.1-2 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco Management XML Interface Definition of Terms Table 1-1 defines the words, acronyms, and actions used throughout this guide. Cisco Management XML Interface These topics, which are covered in detail in the sections that follow, outline information about the Cisco Management XML interface: • High-level structure of the XML request and response streams • Operation tag types and usage, including their XML format and content • Configuring the router using: – the two–stage “target configuration” mechanism provided by the configuration manager – features such as locking, loading, browsing, modifying, saving, and committing the configuration • Accessing the operational data of the router with XML Table 1-1 Definition of Terms Term Description AAA Authentication, authorization, and accounting. CLI Command-line interface. SSH Secure Shell. SSL Secure Sockets Layer. XML Extensible markup language. XML agent Process on the router that receives XML requests by XML clients, and is responsible to carry out the actions contained in the request and to return an XML response to the client. XML client External application that sends XML requests to the router and receives XML responses to those requests. XML operation Portion of an XML request that specifies an operation that the XML client wants the XML agent to perform. XML operation provider Code that carries out a particular XML operation including parsing the operation XML, performing the operation, and assembling the operation XML response. XML request XML document sent to the router containing a number of requested operations to be carried out. XML response Response to an XML request. XML schema XML document specifying the structure and possible contents of XML elements that can be contained in an XML document.1-3 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API and Router System Features • Working with native management data object class hierarchies to: – represent native data objects in XML – use techniques, including the use of wildcards and filters, for structuring XML requests that access the management data of interest, • Encapsulating CLI commands in XML • Error reporting to the client application • Using iterators for large scale data retrieval • Handling event notifications with XML • Enforcing authorization of client requests • Versioning of XML schemas • Generation and packaging of XML schemas • Transporting options that enable corresponding XML agents on the router • Using the Cisco IOS XR Perl Scripting Toolkit to manage a Cisco IOS XR router Cisco XML API and Router System Features Using the XML API, an external client application sends XML encoded management requests to an XML agent running on the router. The XML API readily supports available transport layers including terminal-based protocols such as Telnet, Secure Shell (SSH), dedicated-TCP connection, and Secure Sockets Layer (SSL) dedicated TCP connection. Before an XML session is established, the XML transport and XML agent must be enabled on the router. For more information, see Chapter 13, “XML Transport and Event Notifications.” A client request sent to the router must specify the different types of operations that are to be carried out. Three general types of management operations supported through XML are: • Native data access (get, set, delete, and so on) using the native management data model. • Configuration services for advanced configuration management through the Configuration Manager. • Traditional CLI access where CLI commands and command responses are encapsulated in XML. When a client request is received by an XML agent on the router, the request is routed to the appropriate XML operation provider in the internal Cisco XML API library for processing. After all the requested operations are processed, the XML agent receives the result and sends the XML encoded response stream on to the client. Cisco XML API Tags An external client application can access management data on the router through an exchange of well-structured XML-tagged request and response streams. The XML tagged request and response streams are described in these sections: • Basic XML Request Content, page 1-4 • XML Declaration Tag, page 1-5 • Operation Type Tags, page 1-81-4 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags • XML Request Batching, page 1-10 Basic XML Request Content This section describes the specific content and format of XML data exchanged between the client and the router for the purpose of router configuration and monitoring. Top-Level Structure The top level of every request sent by a client application to the router must begin with an XML declaration tag, followed by a request tag and one or more operation type tags. Similarly, every response returned by the router begins with an XML declaration tag followed by a response tag, one or more operation type tags, and a result summary tag with an error count. Each request contains operation tags for each supported operation type; these operation type tags can be repeated. The operation type tags contained in the response corresponds to those contained in the client request. Sample XML Request from Client Application . . . Operation-specific content goes here . . . Sample XML Response from Router . . . Operation-specific response data returned here . . . Note All examples in this document are formatted with line breaks and white space to aid readability. Actual XML request and response streams that are exchanged with the router do not include such line breaks and white space characters. This is because these elements would add significantly to the size of the XML data and impact the overall performance of the XML API. 1-5 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags XML Declaration Tag Each request and response exchanged between a client application and the router must begin with an XML declaration tag indicating which version of XML and (optionally) which character set is being used: Table 1-2 defines the attributes of the XML declaration that are defined by the XML specification. Request and Response Tags Following the XML declaration tag, the client application must enclose each request stream within a pair of start and end tags. Also, the system encloses each XML response within a pair of start and end tags. Major and minor version numbers are carried on the and elements to indicate the overall XML API version in use by the client application and router respectively. The XML API presents a synchronous interface to client applications. The and tags are used by the client to correlate request and response streams. A client application issues a request after which, the router returns a response. The client then issues another request, and so on. Therefore, the XML session between a client and the router consist of a series of alternating requests and response streams. The client application optionally includes a ClientID attribute within the tag. The value of the ClientID attribute must be an unsigned 32-bit integer value. If the tag contains a ClientID attribute, the router includes the same ClientID value in the corresponding tag. The ClientID value is treated as opaque data and ignored by the router. ResultSummary Tag The system adds a tag immediately before the end tag to indicate the overall result of the operation performed. This tag contains the attribute ErrorCount to indicate the total number of errors encountered. A value of 0 indicates no errors. If applicable, the ItemNotFound or ItemNotFoundBelow attributes are also included. See Table 1-3 for explanations of these attributes. Sample XML Response with ResultsSummary Tag . . Table 1-2 Attributes for XML Declaration Name Description Version Specifies the version of XML to be used. Only Version “1.0” is supported by the router. Note The version attribute is required. Encoding Specifies the standardized character set to be used. Only “UTF-8” is supported by the router. The router includes the encoding attribute in a response only if it is specified in the corresponding request. Note The encoding attribute is optional.1-6 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags Maximum Request Size The maximum size of an XML request or response is determined by the restrictions of the underlying transports. For more information on transport-specific limitations of request and response sizes, see Chapter 13, “XML Transport and Event Notifications.” Minimum Response Content If a or request has nothing to return, the router returns the original request and an appropriate empty operation type tag. The minimum response returned by the router with a single operation or and no result data, is shown in these examples: Sample XML Request from Client Application . . . Operation-specific content goes here . . . Sample XML Minimum Response from a Router If a request has nothing to return, the router returns the original request with an ItemNotFound attribute at the level. If a request has some ‘not found’ elements to return, the router returns the original request with an ItemNotFoundBelow attribute at the level. For each requested element that is not found, the router returns a NotFound attribute at the element level. For each requested element that is present, it returns the corresponding data. Table 1-3 defines the attributes when the request does not have any elements to return. Sample XML Request from Client Application (ItemNotFound) Table 1-3 Attributes for Elements Not Found Attribute Description ItemNotFound Empty response at the level. ItemNotFoundBelow Response with some requested elements that are not found at the level. NotFound Requested element is not found at the element level.1-7 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags act Loopback1 Sample XML Minimum Response from a Router (ItemNotFound) act Loopback1 Sample XML Request from Client Application (ItemNotFoundBelow) act Loopback0 Sample XML Minimum Response from a Router (ItemNotFoundBelow) 1-8 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags act Loopback0 desc-loop0 1.1.1.1 255.255.0.0 Operation Type Tags Following the tag, the client application must specify the operations to be carried out by the router. Three general types of operations are supported along with the operation for large responses. Native Data Operation Tags Native data operations provide basic access to the native management data model. Table 1-4 describes the native data operation tags. The XML schema definitions for the native data operation type tags are contained in the schema file native_data_operations.xsd. The native data operations are described further in Chapter 5, “Cisco XML and Native Data Access Techniques.” Table 1-4 Native Data Operation Tags Native Data Tag Description Gets the value of one or more configuration, operational, or action data items. Creates or modifies one or more configuration or action data items. Deletes one or more configuration data items. Gets the major and minor version numbers of one or more components. Retrieves native data branch names.1-9 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags Configuration Services Operation Tags Configuration services operations provide more advanced configuration management functions through the Configuration Manager. Table 1-5 describes the configuration services operation tags. The XML schema definitions for the configuration services operation type tags are contained in the schema file config_services_operations.xsd (see Chapter 14, “Cisco XML Schemas”). The configuration services operations are described further in Chapter 2, “Cisco XML Router Configuration and Management.” CLI Operation Tag CLI access provides support for XML encapsulated CLI commands and responses. For CLI access, a single tag is provided. The operation tag issues the request as a CLI command. The XML schema definitions for the CLI tag are contained in the schema file cli_operations.xsd (see Chapter 14, “Cisco XML Schemas”). The CLI operations are described further in Chapter 6, “Cisco XML and Encapsulated CLI Operations.” GetNext Operation Tag The tag is used to retrieve the next portion of a large response. It can be used as required to retrieve an oversize response following a request using one of the other operation types. The operation tag gets the next portion of a response. Iterators are supported for large requests. The XML schema definition for the operation type tag is contained in the schema file xml_api_protocol.xsd (see Chapter 14, “Cisco XML Schemas”). For more information about the operation, see Chapter 7, “Cisco XML and Large Data Retrieval.” Table 1-5 Configuration Services Operation Tags Tag Description Locks the running configuration. Unlocks the running configuration. Loads the target configuration from a binary file previously saved using the tag. Saves the target configuration to a binary file. Promotes the target configuration to the running configuration. Aborts or clears the current target configuration session. Rolls back the running configuration to a previous configuration state. Gets a list of configuration events. Gets a list of the user sessions currently configuring the box. Gets a list of commits that were made to the running configuration and can be rolled back. Clears a particular configuration session. Clears a configuration inconsistency alarm.1-10 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags Alarm Operation Tags The operation tag registers, unregisters, and receives alarm notifications. Table 1-6 lists the alarm operation tags. The XML schema definitions for the alarm operation tags are contained in the schema file alarm_operations.xsd (see Chapter 14, “Cisco XML Schemas”). XML Request Batching The XML interface supports the combining of several requests or operations into a single request. When multiple operations are specified in a single request, the response contains the same operation tags and in the same order as they appeared in the request. Batched requests are performed as a “best effort.” For example, in a case where operations 1 through 3 are in the request, even if operation 2 fails, operation 3 is attempted. If you want to perform two or more operations, and if the first one might return a large amount of data that is potentially larger than the size of one iterator chunk, you must place the subsequent operations within a separate XML request. If the operations are placed in the same request within the same tags, for example, potentially sharing part of the hierarchies with the first request, an error attribute that informs you that the operations cannot be serviced is returned on the relevant tags. For more information, see Chapter 5, “Cisco XML and Native Data Access Techniques.” This example shows a simple request containing six different operations: Sample XML Client Batched Requests . . . Get operation content goes here . . . . . . Set operation content goes here . . Table 1-6 List of Alarm Operation Tags Tag Description Registers to receive alarm notifications. Cancels a previous alarm notification registration.1-11 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags . . . . Get operation content goes here . . . Sample XML Response from the Router . . . . . . . . . Get response content returned here . . . . . . . . . . . . . . . . . . Get response content returned here . . . .1-12 Cisco IOS XR XML API Guide OL-24657-01 Chapter 1 Cisco XML API Overview Cisco XML API Tags . . . . . C H A P T E R 2-13 Cisco IOS XR XML API Guide OL-24657-01 2 Cisco XML Router Configuration and Management This chapter reviews the basic XML requests and responses used to configure and manage the router. The use of XML to configure the router is essentially an abstraction of a configuration editor in which client applications can load, browse, and modify configuration data without affecting the current running (that is, active) configuration on the router. This configuration that is being modified is called the "target configuration” and is not the running configuration on the router. The router’s running configuration can never be modified directly. All changes to the running configuration must go through the target configuration. Note Each client application session has its own target configuration, which is not visible to other client sessions. This chapter contains these sections: • Target Configuration Overview, page 2-13 • Configuration Operations, page 2-14 • Additional Router Configuration and Management Options Using XML, page 2-27 Target Configuration Overview The target configuration is effectively the current running configuration overlaid with the client-entered configuration. In other words, the target configuration is the client-intended configuration if the client were to commit changes. In terms of implementation, the target configuration is an operating system buffer that contains just the changes (set and delete) that are performed within the configuration session. A “client session” is synonymous with dedicated TCP, Telnet, Secure Shell (SSH) connection, or SSL dedicated connection and authentication, authorization, and accounting (AAA) login. The target configuration is created implicitly at the beginning of a client application session and must be promoted (that is, committed) to the running configuration explicitly by the client application in order to replace or become the running configuration. If the client session breaks, the current target configuration is aborted and any outstanding locks are released.2-14 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations Note Only the syntax of the target configuration is checked and verified to be compatible with the installed software image on the router. The semantics of the target configuration is checked only when the target configuration is promoted to the running configuration. Configuration Operations Note Only the tasks in the “Committing the Target Configuration” section are required to change the configuration on the router (that is, modifying and committing the target configuration). Use these configuration options from the client application to configure or modify the router with XML: • Locking the Running Configuration, page 2-14 • Browsing the Target or Running Configuration, page 2-15 – Getting Configuration Data, page 2-15 • Browsing the Changed Configuration, page 2-16 • Loading the Target Configuration, page 2-19 • Setting the Target Configuration Explicitly, page 2-20 • Saving the Target Configuration, page 2-21 • Committing the Target Configuration, page 2-22 – Loading a Failed Configuration, page 2-26 • Unlocking the Running Configuration, page 2-27 Locking the Running Configuration The client application uses the operation to obtain an exclusive lock on the running configuration in order to prevent modification by other users or applications. If the lock operation is successful, the response contains only the tag. If the lock operation fails, the response also contains ErrorCode and ErrorMsg attributes that indicates the cause of the lock failure. This example shows a request to lock the running configuration. This request corresponds to the command-line interface (CLI) command configure exclusive. Sample XML Request from the Client Application Sample XML Response from the Router 2-15 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations These conditions apply when the running configuration is locked: • The scope of the lock is the entire configuration “namespace.” • Only one client application can hold the lock on the running configuration at a time. If a client application attempts to lock the configuration while another application holds the lock, an error is returned. • If a client application has locked the running configuration, all other client applications can only read the running configuration, but cannot modify it (that is, they cannot commit changes to it). • No mechanism is provided to allow a client application to break the lock of another user. • If a client session is terminated, any outstanding locks are automatically released. • The XML API does not support timeouts for locks. • The operation is used to identify the user session holding the lock. Browsing the Target or Running Configuration The client application browses the target or current running configuration using the operation along with the request type tags. The client application optionally uses CLI commands encoded within XML tags to browse the configuration. The tag supports the optional Source attribute, which is used to specify the source of the configuration information returned from a operation. Getting Configuration Data Table 2-1 describes the Source options. Table 2-1 Source Options Option Description ChangedConfig Reads only from the changes made to the target configuration for the current session. This option effectively gets the configuration changes made from the current session since the last configuration commit. This option corresponds to the CLI command show configuration. CurrentConfig Reads from the current active running configuration. This option corresponds to the CLI command show configuration running. MergedConfig Reads from the target configuration for this session. This option should provide a view of the resultant running configuration if the current target configuration is committed without errors. For example, in the case of the “best effort” commit, some portions of the commit could fail, while others could succeed. MergedConfig is the default when the Source attribute is not specified on the operation. This option corresponds to the CLI command show configuration merge.2-16 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations If the operation fails, the response contains one or more ErrorCode and ErrorMsg attributes indicating the cause of the failure. This example shows a request used to browse the current Border Gateway Protocol (BGP) configuration: Sample XML Client Request to Browse the Current BGP Configuration Sample XML Response from the Router .. . . response data goes here . . . Browsing the Changed Configuration When a client application issues a request with a Source type of ChangedConfig, the response contains the OperationType attribute to indicate whether the returned changes to the target configuration were a result of or operations. Use to browse uncommitted target configuration changes. CommitChanges Reads from the commit database for the specified commit ID. This operation corresponds to the CLI command show configuration commit changes. RollbackChanges Reads from a set of rollback changes. This operation corresponds to the CLI command show configuration rollback-changes. Table 2-1 Source Options (continued) Option Description2-17 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations This example shows and operations that modify the BGP configuration followed by a request to browse the uncommitted BGP configuration changes. These requests correspond to these CLI commands: RP/0/RP0/CPU0:router# configure RP/0/RP0/CPU0:router(config)# router bgp 3 RP/0/RP0/CPU0:router(config-bgp)# default-metric 10 RP/0/RP0/CPU0:router(config-bgp)# no neighbor 10.0.101.8 RP/0/RP0/CPU0:router(config-bgp)# exit RP/0/RP0/CPU0:router# show configuration Sample XML to Modify the BGP Configuration 0 3 10 0 3 10.0.101.8 2-18 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations Sample XML Response from the Router Sample XML Client Request to Browse Uncommitted Target Configuration Changes Sample Secondary XML Response from the Router 0 3 true 10 0 3 2-19 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations 10.0.101.8 Loading the Target Configuration The client application uses the operation along with the tag to populate the target configuration with the contents of a binary configuration file previously saved on the router using the operation. Note At the current time, a configuration file saved using CLI is not loadable with XML . The configuration should have been saved using the XML operation. Using the operation is strictly optional. It can be used alone or with the and operations, as described in the section “Setting the Target Configuration Explicitly” section on page 2-20. Use the tag to name the file from which the configuration is to be loaded. When you use the tag to name the file from which the configuration is to be loaded, specify the complete path of the file to be loaded. If the load operation is successful, the response contains both the and tags. If the load operation fails, the response contains the ErrorCode and ErrorMsg attributes that indicate the cause of the load failure. This example shows a request to load the target configuration from the contents of the file my_bgp.cfg: Sample XML Client Request to Load the Target Configuration from a Named File disk0:/my_bgp.cfg Sample XML Response from the Router disk0:/my_bgp.cfg2-20 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations See also the “Setting the Target Configuration Explicitly” section on page 20. Setting the Target Configuration Explicitly The client application modifies the target configuration as required using the and operations. Note There are no separate “Create” and “Modify” operations, because a operation for an item can result in the creation of the item if it does not already exist in the configuration, and can result in the modification of the item if it does already exist. The client application can optionally use CLI commands encoded within XML tags to modify the target configuration. If the operation to modify the target configuration is successful, the response contains only the or tag. If the operation fails, the response includes the element or object hierarchy passed in the request along with one or more ErrorCode and ErrorMsg attributes indicating the cause of the failure. A syntax check is performed whenever the client application writes to the target configuration. A successful write to the target configuration, however, does not guarantee that the configuration change can succeed when a subsequent commit of the target configuration is attempted. For example, errors resulting from failed verifications may be returned from the commit. This example shows how to use a request to set the default metric and routing timers and disable neighbor change logging for a particular BGP autonomous system. This request corresponds to these CLI commands: RP/0/RP0/CPU0:router# configure RP/0/RP0/CPU0:router(config)# router bgp 3 RP/0/RP0/CPU0:router(config-bgp)# default-metric 10 RP/0/RP0/CPU0:router(config-bgp)# timers bgp 60 180 RP/0/RP0/CPU0:router(config-bgp)# exit Sample XML Client Request to Set Timers and Disable Neighbor Change Logging for a BGP Configuration 3 3 10 60 1802-21 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations Sample XML Response from the Router To replace a portion of the configuration, the client application should use a operation to remove the unwanted portion of the configuration followed by a operation to add the new configuration. An explicit “replace” option is not supported. For more information on replacing the configuration, see the “Replacing the Current Running Configuration” section on page 2-44. Saving the Target Configuration The client application uses the operation along with the tag to save the contents of the target configuration to a binary file on the router. Use the tag to name the file to which the configuration is to be saved. You must specify the complete path of the file to be saved when you use the tag. If the file already exists on the router, then an error is returned, unless the optional Boolean attribute Overwrite is included on the tag with a value of “true”. Note No mechanism is provided by the XML interface for “browsing” through the file directory structure. If the save operation is successful, the response contains both the and tags. If the save operation fails, the response also contains the ErrorCode and ErrorMsg attributes that indicate the cause of the failure. This example shows a request to save the contents of the target configuration to the file named my_bgp.cfg on the router: Sample XML Client Request to Save the Target Configuration to a File disk0:/my_bgp.cfg Sample XML Response from the Router 2-22 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations disk0:/my_bgp.cfg Committing the Target Configuration In order for the configuration in the target area to become part of the running configuration, the target configuration must be explicitly committed by the client application using the operation. Commit Operation Table 2-2 describes the six optional attributes that are specified with the operation. Table 2-2 Commit Operation Attributes Attribute Description Mode Use the Mode attribute to specify whether the target configuration should be committed on an Atomic or a BestEffort basis. In the case of a commit with the Atomic option, the entire configuration in the target area is committed only if the application of all of the configuration in the target area to the running configuration succeeds. If any errors occur, the commit operation is rolled back and the errors are returned to the client application. In the case of commit with the BestEffort option, the configuration is committed even if some configuration items fail during the commit operation. In this case too, the errors are returned to the client application. By default, the commit operation is performed on an Atomic basis. KeepFailedConfig Use this Boolean attribute to specify whether any configuration that fails during the commit operation should remain in the target configuration buffer. The default value for KeepFailedConfig is false. That is, by default the target configuration buffer is cleared after each commit. If a commit operation is performed with a KeepFailedConfig value of false, the user can then use the operation to load the failed configuration back into the target configuration buffer. The use of the KeepFailedConfig attribute makes sense only for the BestEffort commit mode. In the case of an Atomic commit, if something fails, the entire target configuration is kept intact (because nothing is committed). Label Use the Label attribute instead of the commit identifier wherever a commit identifier is expected, such as in the operation. The Label attribute is a unique user-specified label that is associated with the commit in the commit database. If specified, the label must begin with an alphabetic character and cannot match any existing label in the commit database. Comment Use the Comment attribute as a user-specified comment to be associated with the commit in the router commit database.2-23 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations If the commit operation is successful, the response contains only the tag, along with a unique CommitID and any other attributes specified in the request. If the commit operation fails, the failed configuration is returned in the response. This example shows a request to commit the target configuration using the Atomic option. The request corresponds to the commit label BGPUpdate1 comment BGP config update CLI command. Sample XML Client Request to Commit the Target Configuration Using the Atomic Option Sample XML Response from the Router This example shows a request to commit for a 50-second period. The request corresponds to the commit confirmed 50 CLI command. Confirmed Use the Confirmed attribute as a commit request, which sends the target configuration to a trial commit. The confirmed request has a value of 30 to 300 seconds. If the user sends a commit request without the Confirmed attribute within the specified period, the changes are committed; otherwise, the changes are rolled back after the specified period is over. If the user sends a commit request again with the Confirmed attribute, the target configuration is sent to the trial commit. Replace Use this boolean attribute to specify whether the commit operation should replace the entire configuration running on the router with the contents of the target configuration buffer. The default value for Replace is false. The Replace attribute should be used with caution. Caution The new configuration must contain the necessary configuration to maintain the XML session, for example, “xml agent” or “xml agent tty” along with the configuration for the management interface. Otherwise, the XML session is terminated. IgnoreOtherSessions Use this boolean attribute to specify whether the commit operation should be allowed to go through without an error when one or more commits have occurred from other configuration sessions since the current session started or since the last commit was made from this session. The default value for IgnoreOtherSessions is false. Table 2-2 Commit Operation Attributes (continued) Attribute Description2-24 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations Sample XML Client Request to Commit for a 50-second Period Sample XML Response from the Router These points should be noted with regard to committing the target configuration: • After each successful commit operation, a commit record is created in the router commit database. The router maintains up to 100 entries in the commit database corresponding to the last 100 commits. Each commit is assigned a unique identifier, such as “1000000075,” which is saved with the commit information in the database. The commit identifier is used in subsequent operations such as commit changes or to a previous commit (using the tag). • Configuration changes in the target configuration are merged with the running configuration when committed. If a client application is to perform a replace of the configuration, the client must first remove the unwanted configuration using a operation and then add the new configuration using a operation. An explicit replace option is not supported. For more information on replacing the configuration, see the “Replacing the Current Running Configuration” section on page 2-44. • Applying the configuration for a trial period (“try-and-apply”) is not supported for this release. • If the client application never commits, the target configuration is automatically destroyed when the client session is terminated. No other timeouts are supported. • To confirm the commit with the Confirmed attribute, the user has to send an explicit without the Confirmed attribute or send a without the “Confirmed” attribute along with any other configurations. Commit Errors If any configuration entered into the target configuration fails to makes its way to the running configuration as the result of a operation (for example, the configuration contains a semantic error and is therefore rejected by a back-end application’s verifier function), all of the failed configuration is returned in the response along with the appropriate ErrorCode and ErrrorMsg attributes indicating the cause of each failure. The OperationType attribute is used to indicate whether the failure was a result of a requested or operation. In the case of a operation failure, the value to be set is included in the commit response. This example shows and operations to modify the BGP configuration followed by a request resulting in failures for both requested operations. This request corresponds to these CLI commands: RP/0/RP0/CPU0:router# configure RP/0/RP0/CPU0:router(config)# router bgp 4 RP/0/RP0/CPU0:router(config-bgp)# default-metric 10 RP/0/RP0/CPU0:router(config-bgp)# exit RP/0/RP0/CPU0:router(config)# commit best-effort2-25 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations Sample XML Client Request to Modify the Target Configuration 0 4 10 Sample XML Response from the Router Sample Request to Commit the Target Configuration Sample XML Response from the Router Showing Failures for Both Requested Operations 4 4 2-26 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Configuration Operations 10 For more information, see the “Loading a Failed Configuration” section on page 2-26. Loading a Failed Configuration The client application uses the operation along with the tag to populate the target configuration with the failed configuration from the most recent operation. Loading the failed configuration in this way is equivalent to specifying a “true” value for the KeepFailedConfig attribute in the operation. If the load operation is successful, the response contains both the and tags. If the load fails, the response can also contain the ErrorCode and ErrorMsg attributes that indicate the cause of the load failure. This example shows a request to load and display the failed configuration from the last operation. This request corresponds to the show configuration failed CLI command. Sample XML Client Request to Load the Failed Configuration from the Last Operation Sample XML Response from the Router 0 4 true 2-27 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML 10 Unlocking the Running Configuration The client application must use the operation to release the exclusive lock on the running configuration for the current session prior to terminating the session. If the unlock operation is successful, the response contains only the tag. If the unlock operation fails, the response can also contain the ErrorCode and ErrorMsg attributes that indicate the cause of the unlock failure. This example shows a request to unlock the running configuration. This request corresponds to the exit CLI command when it is used after the configuration mode is entered through the configure exclusive CLI command. Sample XML Client Request to Unlock the Running Configuration Sample XML Response from the Router Additional Router Configuration and Management Options Using XML These sections describe the optional configuration and router management tasks available to the client application: • Getting Commit Changes, page 2-28 • Loading Commit Changes, page 2-29 • Clearing a Target Session, page 2-31 • Rolling Back Configuration Changes to a Specified Commit Identifier, page 2-32 • Rolling Back the Trial Configuration Changes Before the Trial Time Expires, page 2-32 • Rolling Back Configuration Changes to a Specified Number of Commits, page 2-332-28 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML • Getting Rollback Changes, page 2-34 • Loading Rollback Changes, page 2-35 • Getting Configuration History, page 2-37 • Getting Configuration Commit List, page 2-40 • Getting Configuration Session Information, page 2-42 • Clear Configuration Session, page 2-43 • Replacing the Current Running Configuration, page 2-44 • Clear Configuration Inconsistency Alarm, page 2-45 Getting Commit Changes When a client application successfully commits the target configuration to the running configuration, the configuration manager writes a single configuration change event to the system message logging (syslog). As a result, an event notification is written to the Alarm Channel and subsequently forwarded to any registered configuration agents. Table 2-3 describes the event notification. This example shows a configuration change notification: RP/0/1/CPU0:Jul 25 18:23:21.810 : config[65725]: %MGBL-CONFIG-6-DB_COMMIT : Configuration committed by user 'lab'. Use 'show configuration commit changes 1000000001' to view the changes Upon receiving the configuration change notification, a client application can then use the operation to load and browse the changed configuration. The client application can read a set of commit changes using the operation along with the request type tag when it includes the Source attribute option CommitChanges. One of the additional attributes, either ForCommitID or SinceCommitID, must also be used to specify the commit identifier or commit label for which the commit changes should be retrieved. This example shows the use of the ForCommitID attribute to show the commit changes for a specific commit. This request corresponds to the show configuration commit changes 1000000075 CLI command. Sample XML Request to Show Specified Commit Changes Using the ForCommitID Attribute Table 2-3 Event Notification Notification Description userid Name of the user who performed the commit operation. timestamp Date and time of the commit. commit Unique ID associated with the commit.2-29 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Response from the Router . . changed config returned here . . . This example shows the use of the SinceCommitID attribute to show the commit changes made since a specific commit. This request corresponds to the show configuration commit changes since 1000000072 CLI command. Sample XML Request to Show Specified Commit Changes Using the SinceCommitID Attribute Sample XML Response from the Router OperationType=”....> . . changed config returned here . . . Loading Commit Changes The client application can load a set of commit changes into the target configuration buffer using the Load operation and CommitChanges tag along with one of the additional tags ForCommitID, SinceCommitID, or Previous. After the completion of the Load operation, the client application can then modify and commit the commit changes like any other configuration. If the load succeeds, the response contains both the Load and CommitChanges tags. If the load fails, the response also contains the ErrorCode and ErrorMsg attributes indicating the cause of the load failure.2-30 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML This example shows the use of the Load operation and CommitChanges tag along with the ForCommitID tag to load the commit changes for a specific commit into the target configuration buffer. This request corresponds to the load commit changes 1000000072 CLI command. Sample XML Request to Load Commit Changes with the ForCommitID tag 1000000072 Sample XML Response from the Router 1000000072 This example shows the use of the Load operation and CommitChanges tag along with the SinceCommitID tag to load the commit changes since (and including) a specific commit into the target configuration buffer. This request corresponds to the load commit changes since 1000000072 CLI command. Sample XML Request to Load Commit Changes with the SinceCommitID tag 1000000072 Sample XML Response from the Router 1000000072 2-31 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML This example shows the use of the Load operation and CommitChanges tag along with the Previous tag to load the commit changes for the most recent four commits into the target configuration buffer. This request corresponds to the load commit changes last 4 CLI command. Sample XML Request to Load Commit Changes with the Previous tag 4 Sample XML Response from the Router 4 Clearing a Target Session Prior to committing the target configuration to the active running configuration, the client application can use the operation to clear the target configuration session. This operation has the effect of clearing the contents of the target configuration, thus removing any changes made to the target configuration since the last commit. The clear operation does not end the target configuration session, but results in the discarding of any uncommitted changes from the target configuration. If the clear operation is successful, the response contains just the tag. If the clear operation fails, the response can also contain the ErrorCode and ErrorMsg attributes that indicate the cause of the clear failure. This example shows a request to clear the current target configuration session. This request corresponds to the clear CLI command. Sample XML Request to Clear the Current Target Configuration Session Sample XML Response from a Router 2-32 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Rolling Back Configuration Changes to a Specified Commit Identifier The client application uses the operation with the tag to roll back the configuration changes made since (and including) the commit by specifying a commit identifier or commit label. If the roll back operation is successful, the response contains both the and tags. If the roll back operation fails, the response can also contain the ErrorCode and ErrorMsg attributes that indicate the cause of the roll back failure. Table 2-4 describes the optional attributes that are specified with the operation by the client application when rolling back to a commit identifier. This example shows a request to roll back the configuration changes to a specified commit identifier. This request corresponds to the rollback configuration to 1000000072 CLI command. Sample XML Request to Roll Back the Configuration Changes to a Specified Commit Identifier 1000000072 Sample XML Response from the Router 1000000072 Note The commit identifier can also be obtained by using the operation described in the section “Getting Configuration History” section on page 2-37. Rolling Back the Trial Configuration Changes Before the Trial Time Expires When the user sends a commit request with the Confirmed attribute, a trial configuration session is created. If the user then sends a confirmed commit, the trial configuration changes are committed. If the user wants to roll back the trial configuration changes before the trial time expires, the user can use the operation. Table 2-4 Optional Attributes for Rollback Operation (Commit Identifier) Attribute Description Label Unique user-specified label to be associated with the rollback in the router commit database. If specified, the label must begin with an alphabetic character and cannot match any existing label in the router commit database. Comment User-specified comment to be associated with the rollback in the router commit database.2-33 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Note No optional attributes can be used when is specified. This example shows a request to roll back the trial configuration changes: Sample XML Request to Roll Back the Trial Configuration Before the Trial Time Expires Sample XML Response from the Router Rolling Back Configuration Changes to a Specified Number of Commits The client application uses the operation with the tag to roll back the configuration changes made during the most recent [x] commits, where [x] is a number ranging from 0 to the number of saved commits in the commit database. If the value is specified as “0”, nothing is rolled back. The target configuration must be unlocked at the time the operation is requested. If the roll back operation is successful, the response contains both the and tags. If the roll back operation fails, the response can also contain the ErrorCode and ErrorMsg attributes that indicate the cause of the rollback failure. Table 2-5 describes the optional attributes that are specified with the operation by the client application when rolling back a specified number of commits. This example shows a request to roll back the configuration changes made during the previous three commits. This request corresponds to the rollback configuration last 3 CLI command. Table 2-5 Optional Attributes for Rollback Operation (Number of Commits) Attribute Description Label Unique user-specified label to be associated with the rollback in the router commit database. If specified, the label must begin with an alphabetic character and cannot match any existing label in the router commit database. Comment User-specified comment to be associated with the rollback in the router commit database.2-34 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Request to Roll Back Configuration Changes to a Specified Number of Commits 3 Sample XML Response from the Router 3 Getting Rollback Changes The client application can read a set of rollback changes using the operation along with the request type tag when it includes both the Source attribute option RollbackChanges and one of the additional attributes ToCommitID or PreviousCommits. The set of roll back changes are the changes that are applied when the operation is performed using the same parameters. It is recommended that the client application read or verify the set of roll back changes before performing the roll back. This example shows the use of the ToCommitID attribute to get the rollback changes for rolling back to a specific commit. This request corresponds to the show configuration rollback-changes to 1000000072 CLI command. Sample XML Client Request to Get Rollback Changes Using the ToCommitID Attribute Sample XML Response from the Router OperationType=”....> . . rollback changes returned here . . . 2-35 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML This example shows the use of the PreviousCommits attribute to get the roll back changes for rolling back a specified number of commits. This request corresponds to the show configuration rollback-changes last 4 CLI command. Sample XML Client Request to Get Roll Back Changes Using the PreviousCommits Attribute Sample XML Response from the Router OperationType=”....> . . rollback changes returned here . . . < ResultSummary ErrorCount="0"/> Loading Rollback Changes The client application can load a set of rollback changes into the target configuration buffer using the Load operation and RollbackChanges tag along with one of the additional tags ForCommitID, ToCommidID, or Previous. After the completion of the Load operation, the client application can then modify and commit the rollback changes like with any other configuration. If the load succeeds, the response contains both the Load and RollbackChanges tags. If the load fails, the response also contains the ErrorCode and ErrorMsg attributes indicating the cause of the load failure. This example shows the use of the Load operation and RollbackChanges tag along with the ForCommitID tag to load the rollback changes for a specific commit into the target configuration buffer. This request corresponds to the load rollback changes 1000000072 CLI command. Sample XML Client to Load Rollback Changes with the ForCommitID tag 1000000072 2-36 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Response from the Router 1000000072 This example shows the use of the Load operation and RollbackChanges tag along with the ToCommitID tag to load the rollback changes up to (and including) a specific commit into the target configuration buffer. This request corresponds to the load rollback changes to 1000000072 CLI command. Sample XML Client to Load Rollback Changes with the ToCommitID tag 1000000072 Sample XML Response from the Router 1000000072 This example shows the use of the Load operation and RollbackChanges tag along with the Previous tag to load the rollback changes for the most recent four commits into the target configuration buffer. This request corresponds to the load rollback changes last 4 CLI command. Sample XML Client to Load Rollback Changes with the Previous tag 4 2-37 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Response from the Router 4 Getting Configuration History The client application uses the operation to get information regarding these configuration events: • Commit • Online insertion and removal (OIR) events, also known as remove and replace • Router shutdown synchronization • cfs check rebuild of persistent configuration from running configuration • Startup application of admin and SDR configuration, noting alternate configuration fallback specification • Configuration inconsistency including failed configuration or other similar reasons Table 2-6 describes the optional attributes available with the operation. The operation corresponds to the show configuration history CLI command. This example shows a request to list the information associated with the previous three commits. This request corresponds to the show configuration commit history first 6 detail CLI command. Table 2-6 Optional Attributes to Get Configuration History Attribute Description Maximum Maximum number of entries to be returned from the commit history file. The range of entries that can be returned are from 0 to 1500. If the Maximum attribute is not included in the request, or if the value of the Maximum attribute is greater than the actual number of entries in the commit history file, all entries in the commit history files are returned. The commit entries are returned with the most recent commit history information appearing first in the list. EventType Type of event records to be displayed from the configuration history file. If this attribute is not included in the request, all types of event records are returned. The EventType attribute expects one of these values: All, Alarm, CFS-Check, Commit, OIR, Shutdown, or Startup. Reverse Reverse attribute has a value of true. If it is specified, the most recent records are displayed first; otherwise, the oldest records are displayed first. Details Used to display detailed information. The Detail attribute has a value of either true or false and the default is false.2-38 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Request to List Configuration History Information for the Previous Three Commits Sample XML Response from the Router CFS-Check 1300262221 lab vty2 Commit 1300262224 1000000627 lab vty2 CLI Commit 1300262231 2-39 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML 1000000628 lab vty0 CLI Commit 1300262239 1000000629 lab vty0 CLI Commit 1300262246 1000000630 lab vty0 CLI 2-40 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Commit 1300262255 1000000631 lab vty0 CLI Getting Configuration Commit List The client application can use the operation to get information regarding the most recent commits to the running configuration. Table 2-7 describes the information that is returned for each configuration commit session. Table 2-7 Returned Session Information Name Description Unique ID associated with the commit. <2-42 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Getting Configuration Session Information The client application uses the operation to get the list of all users configuring the router. In the case where the configuration is locked, the list identifies the user holding the lock. Table 2-8 describes the information that is returned for each configuration session. The Detail attribute can be specified with . This attribute specifies whether the detailed information is required. False is the default value. Table 2-9 describes the additional information that is returned when the Detail attribute is used. This example shows a request to get the list of users currently configuring the router. This request corresponds to the show configuration sessions detail CLI command. Sample XML Request to Get List of Users Configuring the Router Sample XML Response from the Router 00000000-0005f109-00000000 Table 2-8 Returned Session Information Returned Session Information Session Information Description Unique autogenerated ID for the configuration session. Name of the user who created the configuration session. Line used to connect to the router. User-friendly name of the client application that created the configuration session. Date and time of the creation of the configuration session. Boolean operation indicating whether the session has an exclusive lock on the running configuration. Table 2-9 Returned Session Information with the Detail Attribute Returned Session Information Session Information Description Process name Process ID Node ID Session time elapsed, in seconds.2-43 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML lab con0_0_CPU0 1303317929 false false CLI 389385 config 0 0 CPU0 2183 Clear Configuration Session The client application can use the operation to clear a particular configuration session. The SessionID attribute specifies the session to be cleared. This example shows a request to clear a configuration session. This request corresponds to the clear configuration sessions 00000000-000a00c9-00000000 CLI command.2-44 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Request to Get List of Users Configuring the Router Sample XML Response from the Router Replacing the Current Running Configuration A client application replaces the current running configuration on the router with a users configuration file. Performg these operations in sequence: 1. Lock the configuration. 2. Load the desired off-the-box configuration into the target configuration using one or more operations (assuming that the entire desired configuration is available in XML format, perhaps from a previous of the entire configuration). As an alternative, use an appropriate copy command enclosed within tags. 3. Commit the target configuration specifying the Replace attribute with a value of true. These examples illustrate these steps: Sample XML Request to Lock the Current Running Configuration Sample XML Response from the Router 2-45 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Request to Set the Current Running Configuration . . . configuration data goes here . . . Sample XML Response from the Router Sample XML Request to Commit the Target Configuration Sample XML Response from the Router Clear Configuration Inconsistency Alarm The client application uses the operation to clear a bi-state configuration inconsistency alarm. If the clear operation is successful, the response contains only the tag. If the clear operation fails, the response also contains the ErrorCode and ErrorMsg attributes, indicating the cause of the clear failure. This example shows a request to clear the configuration inconsistency alarm in user mode. This request corresponds to the clear configuration inconsistency CLI command. Sample XML Request to Clear the Configuration Inconsistency Alarm 2-46 Cisco IOS XR XML API Guide OL-24657-01 Chapter 2 Cisco XML Router Configuration and Management Additional Router Configuration and Management Options Using XML Sample XML Response from the Router C H A P T E R 3-49 Cisco IOS XR XML API Guide OL-24657-01 3 Cisco XML Operational Requests and Fault Management A client application can send an XML request to get router operational information using either a native data request along with the tag, or the equivalent CLI command. Although the CLI is more familiar to users, the advantage of using the request is that the response data is encoded in XML format instead of being only uninterpreted text enclosed within tags. This chapter contains these sections: • Operational Get Requests, page 3-49 • Action Requests, page 3-50 Operational Get Requests The content and format of operational requests are described in additional detail in Chapter 4, “Cisco XML and Native Data Operations.” This example shows a request to retrieve the global Border Gateway Protocol (BGP) process information. This request returns BGP process information similar to that displayed by the show ip bgp process detail CLI command. Sample XML Client Request to Get BGP Information Sample XML Response from the Router 3-50 Cisco IOS XR XML API Guide OL-24657-01 Chapter 3 Cisco XML Operational Requests and Fault Management Action Requests 0 0 .... more response content here ... Action Requests A client application can send a request along with the tag to trigger unique actions on the router. For example, an object may be set with an action request to inform the router to clear a particular counter or reset some functionality. Most often this operation involves setting the value of a Boolean object to “true”. This example shows an action request to clear the BGP performance statistics information. This request is equivalent to the clear bgp performance-statistics CLI command. Sample XML Request to Clear BGP Performance Statistics Information true 3-51 Cisco IOS XR XML API Guide OL-24657-01 Chapter 3 Cisco XML Operational Requests and Fault Management Action Requests Sample XML Response from the Router In addition, this example shows an action request to clear the peer drop information for all BGP neighbors. This request is equivalent to the clear bgp peer-drops * CLI command. Sample XML Request to Clear Peer Drop Information for All BGP Neighbors true Sample XML Response from the Router Cisco XML and Fault Management When a client application successfully commits the target configuration to the router’s running configuration, the configuration manager writes a single configuration change event to system message logging (syslog). As a result, a fault management event notification is written to the Alarm Channel and subsequently forwarded to any registered configuration agents. Configuration Change Notification Table 3-1 provides event notification for configuration changes information. Table 3-1 Event Notifications for Configuration Changes Event Notification Description userid Name of the user who performed the commit operation.3-52 Cisco IOS XR XML API Guide OL-24657-01 Chapter 3 Cisco XML Operational Requests and Fault Management Action Requests This example shows a configuration change notification: RP/0/RP0/CPU0:Sep 18 09:43:42.747 : %CLIENTLIBCFGMGR-6-CONFIG_CHANGE : A configuration commit by user root occurred at ’Wed Sep 18 09:43:42 2004 ’. The configuration changes are saved on the router in file: 010208180943.0 Upon receiving the configuration change notification, a client application can then use the and operations to load and browse the changed configuration. timestamp Date and time of the commit. commit Unique ID associated with the commit. Table 3-1 Event Notifications for Configuration Changes (continued) Event Notification DescriptionC H A P T E R 4-53 Cisco IOS XR XML API Guide OL-24657-01 4 Cisco XML and Native Data Operations Native data operations , , and provide basic access to configuration and operational data residing on the router. This chapter describes the content of native data operations and provides an example of each operation type. Native Data Operation Content The content of native data operations includes the request type and relevant object class hierarchy as described in these sections: • Request Type Tag and Namespaces, page 4-54 • Object Hierarchy, page 4-54 • Dependencies Between Configuration Items, page 4-58 • Null Value Representations, page 4-58 • Operation Triggering, page 4-58 • Native Data Operation Examples, page 4-59 This example shows a native data operation request: Sample XML Client Native Data Operation Request . . . object hierarchy goes here . . . 4-54 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content Sample XML Response from the Router . . . response content returned here . . . Request Type Tag and Namespaces The request type tag must follow the operation type tag within a native data operation request. Table 4-1 describes the type of request that must be specified as applying to one of the namespaces. Object Hierarchy A hierarchy of elements is included to specify the items to get, set, or delete, and so on, after the request type tag is specified. The precise hierarchy is defined by the XML component schemas. Note You should use only the supported XML schema objects; therefore, do not attempt to write a request for other objects. The XML schema information is mapped to the XML instance. Table 4-1 Namespace Descriptions Namespace Description Provides access to the router configuration data analogous to CLI configuration commands. The allowed operations on configuration data are , , and . Provides access to the router operational data and is analogous to CLI show commands. The only operation allowed on operational data is . Provides access to the action data, for example, the clear commands. The only allowed operation on action data is . Provides access to the router administration operational data. The only operation allowed on administration operational data is . Provides access to the router administration action data; for example, the clear commands. The only allowed operation on administration action data is .4-55 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content Main Hierarchy Structure The main structure of the hierarchy consists of the native data model organized as a tree of nodes, where related data items appear in the same branch of the tree. At each level of the tree, a node is a container of further, more specific, sets of related data, or a leaf that holds an actual value. For example, the first element in the configuration data model is , which contains all possible configuration items. The children of this element are more specific groups of configuration, such as for Border Gateway Protocol (BGP) configuration and for Intermediate System-to-Intermediate System (ISIS) configuration. Beneath the element, data is further compartmentalized with the element for global BGP configuration and element for per-entity BGP configuration. This compartmentalization continues down to the elements that hold the values, the values being the character data of the element. This example shows the main hierarchy structure: . . . . . . 10 . . . . . . . . . . . . Data can be retrieved at any level in the hierarchy. One particular data item can be examined, or all of the data items in a branch of the tree can be returned in one request. Similarly, configuration data can be deleted at any granularity—one item can be deleted, or a whole branch of related configuration can be deleted. So, for example, all BGP configuration can be deleted in one request, or just the value of the default metric. Hierarchy Tables One special type of container element is a table. Tables can hold any number of keyed entries, and are used when there can be multiple instances of an entity. For example, BGP has a table of multiple neighbors, each of which has a unique IP address "key" to identify it. In this case, the table element is 4-56 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content , and its child element signifying a particular neighbor is . To specify the key, an extension to the basic parent-child hierarchy is used, where a element appears under the child element, containing the key to the table entry. This example shows hierarchy tables: . . . 10.0.101.6 0 6 10.0.101.7 0 6 . . . . . . Use tables to access a specific data item for an entry (for example, getting the remote autonomous system number for neighbor 10.0.101.6), or all data for an entry, or even all data for all entries. Tables also provide the extra feature of allowing the list of entries in the table to be returned. Returned entries from tables can be used to show all neighbors configured; for example, without showing all their data.4-57 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content Tables in the operational data model often have a further feature when retrieving their entries. The tables can be filtered on particular criteria to return just the set of entries that fulfill those criteria. For instance, the table of BGP neighbors can be filtered on address family or autonomous system number or update group, or all three. To apply a filter to a table, use another extension to the basic parent-child hierarchy, where a element appears under the table element, containing the criteria to filter on. This example shows table filtering: one IPv4Unicast Leaf Nodes The leaf nodes hold values and are generally simple one-value items where the element representing the leaf node uses character data to specify the value (as in 10 in the example in the “Main Hierarchy Structure” section on page 4-55. In some cases there may be more than one value to specify—for example, when you configure the administrative distance for an address family (the element), three values must be given together. Specifying more than one value is achieved by adding further child elements to the leaf, each of which indicates the particular value being configured. This example shows leaf nodes: . . . 20 250 200 . . . 4-58 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content Sometimes there may be even more structure to the values (with additional levels in the hierarchy beneath the tag as a means for grouping the related parts of the data together), although they are still only “setable” or “getable” as one entity. The extreme example of this is that in some of the information returned from the operational data model, all the values pertaining to the status of a particular object may be grouped as one leaf. For example, a request to retrieve a particular BGP path status returns all the values associated with that path. Dependencies Between Configuration Items Dependencies between configuration items are not articulated in the XML schema nor are they enforced by the XML infrastructure; for example, if item A is this value, then item B must be one of these values, and so forth. The back-end for the Cisco IOS XR applications is responsible for preventing inconsistent configuration from being set. In addition, the management agents are responsible for carrying out the appropriate operations on dependent configuration items through the XML interface. Null Value Representations The standard attribute “xsi:nil” is used with a value of “true” when a null value is specified for an element in an XML request or response document. This example shows how to specify a null value for the element : 60 Any element that can be set to “nil” in an XML instance has the attribute “nillable” set to “true” in the XML schema definition for that element. For example: Any XML instance document that uses the nil mechanism must declare the “XML Schema for Instance Documents” namespace, which contains the “xsi:nil” definition. Responses to native data operations returned from the router declares the namespace in the operation tag. For example: Operation Triggering When structuring an XML request, the user should remember the general rule regarding what to specify in the XML for an operation to take place: As a client XML request is parsed by the router, the specified operation takes place whenever a closing tag is encountered after a series of one or more opening tags (but only when the closing tag is not the tag). This example shows a request to get the confederation peer information for a particular BGP autonomous system. In this example, the operation is triggered when the tag is encountered. Sample XML Client Request to Trigger a Operation for BGP Timer Values 4-59 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content 0 3 Sample XML Response from the Router 0 3 0 10 true 4-60 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content Native Data Operation Examples These sections provide examples of the basic , , and operations: • Set Configuration Data Request: Example, page 4-60 • Get Request: Example, page 4-62 • Get Request of Nonexistent Data: Example, page 4-63 • Delete Request: Example, page 4-65 • GetDataSpaceInfo Request Example, page 4-66 Set Configuration Data Request: Example This example shows a native data request to set several configuration values for a particular BGP neighbor. Because the operation in this example is successful, the response contains only the operation and request type tags. This request is equivalent to these CLI commands: router bgp 3 address-family ipv4 unicast! address-family ipv4 multicast! neighbor 10.0.101.6 remote-as 6 ebgp-multihop 255 address-family ipv4 unicast orf route-policy BGP_pass all capability orf prefix both ! address-family ipv4 multicast orf route-policy BGP_pass all ! ! ! Sample XML Client Request to Configuration Values for a BGP Neighbor 0 3 true IPv4Unicast true 4-61 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content IPv4Multicast true 10.0.101.6 0 6 255 false IPv4Unicast true BGP_pass_all Both IPv4Multicast true BGP_pass_all Sample XML Response from the Router 4-62 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content Get Request: Example This example shows a native data request to get the address independent configuration values for a specified BGP neighbor (using the same values set in the previous example). Sample XML Client Request to Configuration Values for a BGP Neighbor 0 3 10.0.101.6 Sample XML Response from the Router 0 3 10.0.101.6 4-63 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content 0 6 255 false IPv4Unicast true BGP_pass_all Both IPv4Multicast true BGP_pass_all Get Request of Nonexistent Data: Example This example shows a native data request to get the configuration values for a particular BGP neighbor; this is similar to the previous example. However, in this example the client application is requesting the configuration for a nonexistent neighbor. Instead of returning an error, the router returns the requested object class hierarchy, but without any data. Note Whenever an application attempts to get nonexistent data, the router does not treat this as an error and returns the empty object hierarchy in the response. Sample XML Client Request to Configuration Data for a Nonexistent BGP Neighbor 0 4-64 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content 3 10.0.101.99 Sample XML Response from the Router 0 3 10.0.101.99 4-65 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content Delete Request: Example This example shows a native data request to delete the address-independent configuration for a particular BGP neighbor. Note that if a request is made to delete an item that does not exist in the current configuration, an error is not returned to the client application. So in this example, the returned result is the same as in the previous example: the empty tag, whether or not the specified BGP neighbor exists. This request is equivalent to these CLI commands: router bgp 3 no neighbor 10.0.101.9 exit Sample XML Client Request to the Address-Independent Configuration Data for a BGP Neighbor 0 3 10.0.101.6 Sample XML Response from the Router 4-66 Cisco IOS XR XML API Guide OL-24657-01 Chapter 4 Cisco XML and Native Data Operations Native Data Operation Content GetDataSpaceInfo Request Example This example shows a operation used to retrieve the native data branch names dynamically. This is useful, for example, for writing a client application that can issue a operation without having to hardcode the branch names. The operation can be invoked instead to retrieve the branch names. The returned branch names can then be included in a subsequent request. Sample XML Client Request to Retrieve Native Data Sample XML Response from the Router C H A P T E R 5-67 Cisco IOS XR XML API Guide OL-24657-01 5 Cisco XML and Native Data Access Techniques This chapter describes the various techniques or strategies you can use to structure native data operation requests to access the information needed within the XML schema object class hierarchy. Available Set of Native Data Access Techniques The available native data access techniques are: • Request all data in the configuration hierarchy. See the “XML Request for All Configuration Data” section on page 5-68. • Request all configuration data for a component. See the “XML Request for All Configuration Data per Component” section on page 5-68. • Request all data within a container. See the “XML Request for Specific Data Items” section on page 5-71. • Combine object class hierarchies within a request. See the “XML Request with Combined Object Class Hierarchies” section on page 5-72. • Use wildcards in order to apply an operation to a set of entries within a table (Match attribute). See the “XML Request Using Wildcarding (Match Attribute)” section on page 5-75. • Repeat naming information in order to apply an operation to multiple instances of an object. See the “XML Request for Specific Object Instances (Repeated Naming Information)” section on page 5-80. • Perform a one-level in order to “list” the naming information for each entry within a table (Content attribute). See the “XML Request Using Operation Scope (Content Attribute)” section on page 5-82. • Specify the maximum number of table entries to be returned in a response (Count attribute). See the “Limiting the Number of Table Entries Returned (Count Attribute)” section on page 5-83. • Use custom filters to filter table entries (Filter element). See the “Custom Filtering (Filter Element)” section on page 5-85. • Use the Mode attribute. See the “XML Request Using the Mode Attribute” section on page 5-86 The actual data returned in a request depends on the value of the Source attribute. Note The term “container” is used in this document as a general reference to any grouping of related data, for example, all of the configuration data for a particular Border Gateway Protocol (BGP) neighbor. The term “table” is used more specifically to denote a type of container that holds a list of named 5-68 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques homogeneous objects. For example, the BGP neighbor address table contains a list of neighbor addresses, each of which is identified by its IP address. All table entries in the XML API are identified by the unique value of their element. XML Request for All Configuration Data Use the empty tag to retrieve the entire configuration object class hierarchy. This example shows how to get the entire configuration hierarchy by specifying the empty tag: Sample XML Client Request to the Entire Configuration Object Class Hierarchy Sample XML Response from the Router . . . response data goes here . . . XML Request for All Configuration Data per Component All the configuration data for a component is retrieved by specifying the highest level tag for the component. In this example, all the configuration data for BGP is retrieved by specifying the empty tag: Sample XML Client Request for All BGP Configuration Data 5-69 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample XML Response from the Router . . . response data goes here . . . XML Request for All Data Within a Container All data within a container is retrieved by specifying the configuration or operational object class hierarchy down to the containers of interest, including any naming information as appropriate. This example shows how to retrieve the configuration for the BGP neighbor with address 10.0.101.6: Sample XML Client Request to Get All Address Family-Independent Configuration Data Within a BGP Neighbor Container 0 3 5-70 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques 10.0.101.6 Sample XML Response from the Router 0 3 10.0.101.6 0 6 255 false IPv4Unicast true oBGP_pass_all Both IPv4Multicast true BGP_pass_all 5-71 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques XML Request for Specific Data Items The value of a specific data item (leaf object) can be retrieved by specifying the configuration or operational object class hierarchy down to the item of interest, including any naming information as appropriate. This example shows how to retrieve the values of the two data items and for the BGP neighbor with address 10.0.101.6: Sample XML Client Request for Two Specific Data Items: RemoteAS and EBGPMultihop 0 3 10.0.101.6 Sample XML Response from the Router 5-72 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques 0 3 10.0.101.6 255 XML Request with Combined Object Class Hierarchies Multiple object class hierarchies can be specified in a request. For example, a portion of the hierarchy can be repeated, and multiple instances of a child object class can be included under a parent. The object class hierarchy may also be compressed into the most “efficient” XML. In other words, it is not necessary to repeat hierarchies within a request. Before combining multiple operations inside one tag, these limitations should be noted for Release 3.0. Any operations that request multiple items of data must be sent in a separate XML request. They include: • An operation to retrieve all data beneath a container. For more information, See the“XML Request for All Data Within a Container” section on page 5-69. • An operation to retrieve the list of entries in a table. For more information, See the “XML Request Using Operation Scope (Content Attribute)” section on page 5-82. • An operation which includes a wildcard. For more information, See the “XML Request Using Wildcarding (Match Attribute)” section on page 5-75. If an attempt is made to make such an operation followed by another operation within the same request, this error is returned: XML Service Library detected the ‘fatal’ condition. The XML document which led to this response contained a request for a potentially large amount of data, which could return a set of iterators. The document also contained further requests for data, but these must be sent in a separate XML document, in order to ensure that they are serviced. The error indicates that the operations must be separated out into separate XML requests.5-73 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques These two examples illustrate two different object class hierarchies that retrieve the same data: the value of the leaf object and for the BGP neighbor with the address 10.0.101.6 and all of the configuration data for the BGP neighbor with the address 10.0.101.7: Example 1: Verbose Form of a Request Using Duplicated Object Class Hierarchies Sample XML Client Request for Specific Configuration Data Values 0 3 10.0.101.6 0 AS>3 10.0.101.7 5-74 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample XML Response from the Router . . . response data returned here for neighbor 10.0.101.6 . . . . . . response data returned here neighbor 10.0.101.7 . . . Example 2: Compact Form of a Request Using Compressed Object Class Hierarchies Sample XML Client Request 0 3 10.0.101.6 5-75 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques 10.0.101.7 Sample XML Response from the Router . . . response data returned here for both neighbors . . . XML Request Using Wildcarding (Match Attribute) Wildcarding of naming information is provided by means of the Match attribute. Match=“*” can be used on any Naming attribute within a or operation to effectively specify a wildcarded value for that attribute. The operation applies to all instances of the requested objects. If no match is found, the response message contains MatchFoundBelow=”false” in the class, and MatchFound=”false” in the class that specified Match=”*” and no match found. These attributes are not added (with a value of true) in the response if a match is found. Note Although partial wildcarding of NodeIDs is not available in XML, each element of the NodeID has to be wildcarded, similar to the support on the CLI of */*/* as the only wildcards supported for locations. This example shows how to use the Match attribute to get the value for all configured BGP neighbors: Sample XML Client Request Using the Match Attribute Wildcarding 5-76 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques 0 3 Sample XML Response from the Router 0 3 10.0.101.1 1 10.0.101.2 2 10.0.101.3 3 ... data for more neighbors returned here ...5-77 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques This example shows the response message when there is no match found for the request with wildcarding: Sample XML Client Request for No Match Found with Wildcarding 3 3 Sample XML Response from the Router 3 3 5-78 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques
Regular expression matching of naming information is provided by means of the Match attribute. Match=“” can be used on any Naming attribute within a operation to specify a filtering criteria to filter table entries. These rules apply to the filtering criteria: • The character, ‘*’ , is treated same as the ‘.*’ character. (matches everything) • Meta character ‘^’ (beginning of line) and ‘$’ (end of line) are always attached to the regular expression string specified by ‘Match’ attribute. • A regular expression string without any meta characters is treated as an exact match. Sample Request of the Configured ACL Entries That End With ‘SAA’: ACL entries that match this request: TCLSAA, 100SAA, SAA ACL entries that do NOT match this request: TCLSAA1 Sample Request That Returns all of the Configured GigabitEthernet Ports in Slot 5: act 5-79 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Interface names that match this request: GigabitEthernet0/5/0/0, GigabitEthernet0/5/0/1, and so forth. Interface names that do not match this request: GigabitEthernet0/4/0/0 Sample Request That Returns the Configured Loopback Interfaces Between Loopback100 and Loopback199: act Interface names that match this request: Loopback100,…,Loopback199 Interface names that do not match this request: Loopback1000, Loopback1990 Sample Request That Returns Only Loopback1 (if it is configured): act Interface names that match this request: Loopback1 Interface names that do not match this request: Loopback10, Loopback100, and so forth The request above, thus, is equivalent to this request: act Loopback1 5-80 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Limitation: Regular expression matching can only be specified in the first table of an XML request. XML Request for Specific Object Instances (Repeated Naming Information) Wildcarding allows the client application to effectively specify all instances of a particular object. Similarly, the client application might have a need to specify only a limited set of instances of an object. Specifying object instances can be done by simply repeating the naming information in the request. This example shows how to retrieve the address independent configuration for three different BGP neighbors; that is, the neighbors with addresses 10.0.101.1, 10.0.101.6, and 10.0.101.8, by repeating the naming information, once for each desired instance: Sample XML Client Request Using Repeated Naming Information for BGP Instances 0 3 10.0.101.1 10.0.101.6 10.0.101.8 5-81 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample XML Response from the Router 0 3 10.0.101.1 ... data returned for 1st neighbor ... 10.0.101.6 ... data returned for 2nd neighbor ... 10.0.101.6 ... data returned for 3rd neighbor ... 5-82 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques XML Request Using Operation Scope (Content Attribute) The Content attribute is used on any table element in order to specify the scope of a operation. Table 5-1 describes the content attribute values are supported. If the Content attribute is specified on a nontable element, it is ignored. Also, note that the Content and Count attributes can be used together on the same table element. This example displays the Content attribute that is used to list all configured BGP neighbors: Sample XML Client Request Using the All Content Attribute 0 3 Sample XML Response from the Router 0 Table 5-1 Content Attributes Content Attribute Description All Used to get all leaf items and their values. All is the default when the Content attribute is not specified on a table element. Entries Used to get the Naming information for each entry within a specified table object class. Entries provides a one-level get capability.5-83 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques 3 10.0.101.1 10.0.101.2 10.0.101.3 10.0.101.4 ... more neighbors returned here ... Limiting the Number of Table Entries Returned (Count Attribute) The Count attribute is used on any table element within a operation to specify the maximum number of table entries to be returned in a response. When the Count attribute is specified, the naming information within the request is used to identify the starting point within the table, that is, the first table entry of interest. If no naming information is specified, the response starts at the beginning of the table. For a table whose entries are containers, the Count attribute can be used only if the Content attribute is also specified with a value of Entries. This restriction does not apply to a table whose children are leaf nodes. As an alternative to the use of the Count attribute, the XML interface supports the retrieval of large XML responses in blocks through iterators. 5-84 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques This example shows how to use the Count attribute to retrieve the configuration information for the first five BGP neighbors starting with the address 10.0.101.1: Sample XML Client Request Using the Count Attribute 0 3 10.0.101.1 Sample XML Response from the Router 0 3 10.0.101.1 5-85 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques 10.0.101.2 ... data returned for remaining neighbors here ... Custom Filtering (Filter Element) Some of the tables from the operational namespace support the selection of rows of interest based on predefined filtering criteria. Filters can be applied to such tables in order to reduce the number of table entries retrieved in a request. Client applications specify filtering criteria for such tables by using the tag and including the filter specific parameters as defined in the XML schema definition for that table. If no table entries match the specified filter criteria, the response contains the object class hierarchy down to the specified table, but does not include any table entries. The Content attribute can be used with a filter to specify the scope of a request. In this example, the filter is used to retrieve operational information for all neighbors in autonomous system 6: Sample XML Client Request Using Filtering one 6 5-86 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample Filtered XML Response from the Router one 6 ... data for 1st neighbor returned here ... ... data for 2nd neighbor returned here returned here ... ... data for remaining neighbors returned here ... XML Request Using the Mode Attribute The client application modifies the target configuration as needed using the and operations. The XML interface supports the combining of several operations into a single request. When multiple configuring operations are specified in a single request, they are performed on a “best effort” basis by default. For example, in a case where configuring operations 1 through 3 are in the request and even if operation 2 fails, operation 3 is attempted and operation 1 result remains in the target configuration. To perform the request on an atomic basis, use the Mode attribute with the value Atomic in the . If any errors occur, the target configuration is cleared and the errors are returned to the client application.5-87 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample XML Client Request with the Attribute Mode=”Atomic” 20 Sample XML Response from the Router Sample XML Client Request with an Invalid Set Operation (Best-Effort) 20 <--- This is an invalid XML set operation Sample XML Response from the Router 5-88 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques Note This request is performed on a best effort basis. The SNMP timeout configuration has no error and is committed. Sample XML Request and Response of Commit Change for ForCommitID="1000000443" 20 Sample XML Client Request with the Attribute Mode=”Atomic” and with an Invalid Set Operation 20 5-89 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access Techniques <--- This is an invalid XML set operation Sample XML Response from the Router Note The target configuration buffer is cleared and no configuration is committed.5-90 Cisco IOS XR XML API Guide OL-24657-01 Chapter 5 Cisco XML and Native Data Access Techniques Available Set of Native Data Access TechniquesC H A P T E R 6-91 Cisco IOS XR XML API Guide OL-24657-01 6 Cisco XML and Encapsulated CLI Operations XML interface for the router provides support for XML encapsulated CLI commands and responses. This chapter provides information on XML CLI command tags. XML CLI Command Tags A client application can request a CLI command by encoding the text for the command within a pair of start and end tags, tags, and tags. The router responds with the uninterpreted CLI text result. Note XML encapsulated CLI commands use the same target configuration as the corresponding XML operations , , and . When used for CLI operations, the tag supports the optional Operation attribute, which can take one of the values listed in Table 6-1. This example uses the operation tag: Sample XML Client Request for CLI Command Using CLI Tags router bgp 3 Table 6-1 Operational Attribute Values Operational Attribute Value Operational Attribute Value Description Apply Specifies that the commands should be executed or applied (default). Help Gets help on the last command in the list of commands sent in the request. There should not be any empty lines after the last command (because the last command is considered to be the one on the last line). CommandCompletion Completes the last keyword of the last command. Apart from not allowing empty lines at the end of the list of commands sent in the request, when this option is used, there should not be any white spaces after the partial keyword to be completed.6-92 Cisco IOS XR XML API Guide OL-24657-01 Chapter 6 Cisco XML and Encapsulated CLI Operations XML CLI Command Tags default-metric 10 timers bgp 80 160 exit commit sh config commit changes last 1 Sample XML Response from the Router Building configuration... router bgp 3 timers bgp 80 160 default-metric 10 end CLI Command Limitations The CLI commands, which are supported through XML, are limited to CLI configuration commands and EXEC mode show commands (and responses) that are wrapped in tags. These commands and conditions are not supported: • The do configuration mode command. • EXEC mode commands other than show commands except for these items: – show history – show user – show users – show terminal • Administration EXEC mode commands • Iterators for responses to commands issued through XML. For example, iterators are not supported for the output of the show run and show configuration commands. • Sending a request in format and getting back an XML encoded response. • Sending an XML encoded request and getting back a response in format. • Only one XML request can be issued at a time across all client sessions on the router.C H A P T E R 7-93 Cisco IOS XR XML API Guide OL-24657-01 7 Cisco XML and Large Data Retrieval XML for the router supports the retrieval of large XML responses in blocks (for example, chunks or sections). These sections provide information about large data retrieval: • Iterators, page 7-93 • Throttling, page 7-98 • Streaming, page 7-99 Iterators When a client application makes a request, the resulting response data size is checked to determine whether it is larger than a predetermined block size. If the response data is not larger than the predetermined block size, the complete data is returned in a normal response. If the response data is larger than the block size, the first set of data is returned according to the block size along with a decremented iterator ID included as the value of the IteratorID attribute. The client must then send requests including the iterator ID until all data is retrieved. The client application knows that all data is retrieved when it receives a response that does not contain an IteratorID attribute. Usage Guidelines These points should be noted by the client application when iterators are used: • The block size is a configurable value specific to each transport mechanism on the router; that is, the XML agent for the dedicated TCP connection and Secure Shell (SSH), Telnet, or Secure Sockets Layer (SSL) dedicated TCP connection. Use this command to configure the iteration size: xml agent [tty | ssl] iteration on size <1-100000> Specify the iteration size in KB. The default is 48 KB.7-94 Cisco IOS XR XML API Guide OL-24657-01 Chapter 7 Cisco XML and Large Data Retrieval Iterators Note The iteration command includes the option to turn off the XML response iterator. However, we do not recommend turning off the iterator because of the large memory usage that occurs temporarily. • The block size refers to the entire XML response, not just the payload portion of the response. • Large responses are divided based on the requested block size, not the contents. However, each response is always a complete XML document. • Requests containing multiple operations are treated as a single entity when the block size and IteratorID are applied. As a result, the IteratorID is an attribute of the tag, never of an individual operation. • If the client application sends a request that includes an operation resulting in the need for an iterator to return all the response data, any further operations contained within that request are rejected. The rejected operations are resent in another request. • The IteratorID is an unsigned 32-bit value that should be treated as opaque data by the client application. Furthermore, the client application should not assume that the IteratorID is constant between operations. To reduce memory overhead and avoid memory starvation of the router, these limitations are placed on the number of allowed iterators: • The maximum number of iterators allowed at any one time on a given client session is 10. • The maximum number of iterators allowed at any one time for all client sessions is 100. If a request is issued that results in an iterated response, it is counted as one iterator, regardless of the number of operations required to retrieve all of the response data. For example, a request may require 10, 100, or more operations to retrieve all the associated data, but during this process only one iterator is being used. Also, an iterator is considered to be in use until all of the response data associated with that iterator (the original request) is retrieved or the iterator is terminated with the Abort attribute. Examples Using Iterators to Retrieve Data This example shows a client request that utilizes an iterator to retrieve all global Border Gateway Protocol (BGP) configuration data for a specified autonomous system: Sample XML Client Request to Retrieve All BGP Configuration Data 0 3 7-95 Cisco IOS XR XML API Guide OL-24657-01 Chapter 7 Cisco XML and Large Data Retrieval Iterators Sample XML Response from the Router Containing the First Block of Retrieved Data 0 3 ... 1st block of data returned here ... Second XML Client Request Using the Iterator to Retrieve the Next Block of BGP Configuration Data Sample XML Response from the Router Containing the Second Block of Retrieved Data 0 3 7-96 Cisco IOS XR XML API Guide OL-24657-01 Chapter 7 Cisco XML and Large Data Retrieval Iterators Third XML Client Request Using the Iterator to Retrieve the Next Block of BGP Configuration Data Sample XML Response from the Router Containing Third Block of Retrieved Data 0 3 ... 3rd block of data returned here ... Final XML Client Request Using the Iterator to Retrieve the Last Block of BGP Configuration Data Final XML Response from the Router Containing the Final Block of Retrieved Data 0 3 ... Final block of data returned here ... 7-97 Cisco IOS XR XML API Guide OL-24657-01 Chapter 7 Cisco XML and Large Data Retrieval Iterators Large Response Division The default behavior for large response division is that large responses are divided based on the requested block size. To specify a different basis for the division, use the IterateAtFirstTableGet attribute in the tag. Sample XML Request with attribute IterateAtFirstTable Terminating an Iterator A client application may terminate an iterator without retrieving all of the response data by including an Abort attribute with a value of “true” on the operation. A client application that does not complete or terminate its requests risks running out of iterators. This example shows a client request using the Abort attribute to terminate an iterator: Sample XML Request 0 7-98 Cisco IOS XR XML API Guide OL-24657-01 Chapter 7 Cisco XML and Large Data Retrieval Throttling 3 Sample XML Response from the Router 0 3 ... 1st block of data returned here ... Sample XML Request Using the Abort Attribute to Terminate an Iterator Sample XML Response from the Router Throttling XML response data could be large resulting in high CPU utilization or high memory usage when constructing the XML response. Throttling mechanisms in the XML agent provide a means for external users or an NMS to control the impact to the system.7-99 Cisco IOS XR XML API Guide OL-24657-01 Chapter 7 Cisco XML and Large Data Retrieval Streaming CPU Throttle Mechanism The CPU throttle mechanism in the XML agent controls the number of tags to process per second. The higher the number of tags that are specified, the higher the CPU utilization and faster response. The lower number of tags means less CPU utilization and slower response. To configure the number of tags, use this command: xml agent [tty | ssl] throttle process-rate <1000-30000> Memory Throttle Mechanism The memory throttle mechanism in the XML agent controls the maximum XML response size in MB. If this size is exceeded, this error message is returned in the XML response. > XML> > To configure the size of the memory usage per session, use this command: xml agent [tty | ssl] throttle memory <100-600> The default is 300 MB. Streaming As the XML agent retrieves the data from the source, the output of a response is streamed. This process is similar to iterators, but the XML client does not run the GetNext IteratorID to handle large response data size. Usage Guidelines Use these guidelines when streaming is used by the client application: • Iteration must be off. xml agent [tty | ssl] iteration off • The sub-response block size is a configurable value specific to each transport mechanisms on the router: the XML agent for the dedicated TCP connection and Secure Shell (SSH), Telnet, or Secure Sockets Layer (SSL) dedicated TCP connection. Use this command to configure the streaming size. Specify the streaming size in KB. The default is 48 KB. xml agent [tty | ssl] streaming on size <1-100000>7-100 Cisco IOS XR XML API Guide OL-24657-01 Chapter 7 Cisco XML and Large Data Retrieval StreamingC H A P T E R 8-101 Cisco IOS XR XML API Guide OL-24657-01 8 Cisco XML Security Specific security privileges are required for a client application requesting information from the router. This chapter contains these sections: • Authentication, page 8-101 • Authorization, page 8-101 • Retrieving Task Permissions, page 8-102 • Task Privileges, page 8-102 • Task Names, page 8-103 • Authorization Failure, page 8-104 • Management Plane Protection, page 8-104 • VRF, page 8-105 • Access Control List, page 8-105 Authentication User authentication through authentication, authorization, and accounting (AAA) is handled on the router by the transport-specific XML agent and is not exposed through the XML interface. Authorization Every operation request by a client application is authorized. If the client is not authorized to perform an operation, the operation is not performed by the router and an error is returned. Authorization of client requests is handled through the standard AAA “task permissions” mechanism. The XML agent caches the AAA user credentials obtained from the user authentication process, and then each client provides these to the XML infrastructure on the router. As a result, no AAA information needs to be passed in the XML request from the client application. Each object class in the schema has a task ID associated with it. A client application’s capabilities and privileges in terms of task IDs are exposed by AAA through a show command. A client application can use the XML interface to retrieve the capabilities prior to sending configuration requests to the router. A client application requesting an operation through the XML interface must have the appropriate task privileges enabled or assigned for any objects accessed in the operation:8-102 Cisco IOS XR XML API Guide OL-24657-01 Chapter 8 Cisco XML Security Retrieving Task Permissions • operations require AAA “read” privileges. • and operations require AAA “write” privileges. The “configuration services” operations through configuration manager can also require the appropriate predefined task privileges. If an operation requested by a client application fails authorization, an appropriate element is returned in the response sent to the client. For “native data” operations, the element is associated with the specific element or object classes where the authorization error occurred. Retrieving Task Permissions A client application’s capabilities and privileges in terms of task permissions are exposed by AAA through CLI show commands. A client application can also use the XML interface to programatically retrieve the current AAA capabilities from the router. This retrieval can be done by issuing the appropriate request to the component. This example shows a request to retrieve all of the AAA configuration from the router: Sample XLM Request to Retrieve AAA Configuration Information Sample XML Response from the Router . . . AAA configuration returned here . . . Task Privileges A client application requesting a native data operation through the XML interface must have the appropriate task privileges enabled or assigned for any items accessed in the operation: • , , and operations require AAA “read” privileges. • and operations require AAA “write” privileges.8-103 Cisco IOS XR XML API Guide OL-24657-01 Chapter 8 Cisco XML Security Task Names The “configuration services” operations through the configuration manager can also require the appropriate predefined task privileges. Task Names Each object (that is, data item or table) exposed through the XML interface and accessible to the client application has one or more task names associated with it. The task names are published in the XML schema documents as annotations. For example, the complex type definition for the top-level element in the Border Gateway Protocol (BGP) configuration schema contains this annotation: Container 18 0 bgp native_data_operations Configuration Here is another example from a different component schema. This annotation includes a list of task names. 1 0 ouni mpls-te Task names indicate what permissions are required to access the data below the object. In the example, the task names ouni and mpls-te are specified for the object. The task names apply to the object and are inherited by all the descendants of the object in the schema. In other words, the task names that apply to a particular object are the task names specified for the object and the task names of all ancestors for which there is a task name specified in the schema. The TaskGrouping attribute specifies the logical relationship among the task names when multiple task names are specified for a particular object. For example, for a client application to issue a request for the object containing the preceding annotation, the corresponding AAA user credentials must have read permissions set for both the ouni and mpls-te tasks (and any tasks inherited by the object). The possible values for the TaskGrouping attribute are And, Or, and Single. The value Single is used when there is only a single task name specified for the object.8-104 Cisco IOS XR XML API Guide OL-24657-01 Chapter 8 Cisco XML Security Authorization Failure Authorization Failure If an operation requested by a client application fails authorization, an appropriate element is returned in the response sent to the client. For “native data” operations, the element is associated with the specific element or object where the authorization error occurred. If a client application issues a request to retrieve all data below a container object, and if any subsections of that data require permissions that the user does not have, then an error is not returned. Instead, the subsection of data is not included in the response. Management Plane Protection Management Plane Protection (MPP) provides a mechanism for securing management traffic on the router. Without MPP, a management service’s traffic can come through any interface with a network address, which could be a security risk. MPP is effective when XML is configured. Inband Traffic To configure the MPP for inband traffic, use the command in this example: RP/0/0/CPU0:router(config)#control-plane management-plane inband interface [interface type] allow [protocol|all] where the protocol is XML. RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$Ethernet 0/0/0/0 allow XML ? peer Configure peer address on this interface RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$Ethernet 0/0/0/0 allow XML peer ? address Configure peer address on this interface RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$Ethernet 0/0/0/0 allow XML peer address ? ipv4 Configure peer IPv4 address on this interface ipv6 Configure peer IPv6 address on this interface RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$Ethernet 0/0/0/0 allow XML peer address Out-of-Band Traffic To configure the MPP for out-of-band traffic, use the command in this example: RP/0/0/CPU0:router(config)#control-plane management-plane out-of-band interface [interface type] allow [protocol|all] where the protocol is XML. RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$gabitEthernet 0/0/0/1 allow XML ? peer Configure peer address on this interface RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$gabitEthernet 0/0/0/1 allow XML peer ? address Configure peer address on this interface 8-105 Cisco IOS XR XML API Guide OL-24657-01 Chapter 8 Cisco XML Security VRF RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$ XML peer address ? ipv4 Configure peer IPv4 address on this interface ipv6 Configure peer IPv6 address on this interface RP/0/RSP0/CPU0:PE44_ASR-9010(config)#$ XML peer address VRF XML agents can be configured to virtual route forwarding (VRF) aware. • To configure the dedicated agent [ssl] to receive or send messages through VRF, use this command: RP/0/0/CPU0:router(config)#xml agent [ssl] vrf • To configure the dedicated [ssl] agent NOT to receive or send messages through the default VRF, use this command: RP/0/0/CPU0:Router(config)#xml agent [ssl] vrf default shutdown Access Control List To configure an access control list (ACL) for XML agents, use this command: RP/0/0/CPU0:router(config)#xml agent [ssl] vrf access-list IPv6 Access List Example xml agent [ssl] vrf ipv6 access-list IPv4 and IPv6 Access Lists Example xml agent [ssl] vrf ipv4 access-list ipv6 access-list ! ! Note This method to configure an IPv4 access-list is still supported (for backward compatibility) but hidden from CLI help. xml agent [ssl] vrf access-list ! !8-106 Cisco IOS XR XML API Guide OL-24657-01 Chapter 8 Cisco XML Security Access Control ListC H A P T E R 9-107 Cisco IOS XR XML API Guide OL-24657-01 9 Cisco XML Schema Versioning Before the router can carry out a client application request, it must verify version compatibility between the client request and router component versions. Major and minor version numbers are included on the and elements to indicate the overall XML application programming interface (API) version in use by the client application and router. In addition, each component XML schema exposed through the XML API has a major and minor version number associated with it. This chapter describes the format of the version information exchanged between the client application and the router, and how the router uses this information at run time to check version compatibility. This chapter contains these sections: • Major and Minor Version Numbers, page 9-107 • Run-Time Use of Version Information, page 9-108 • Retrieving Version Information, page 9-113 • Retrieving Schema Detail, page 9-115 Major and Minor Version Numbers The top-level or root object (that is, element) in each component XML schema carries the major and minor version numbers for that schema. A minor version change is defined as an addition to the XML schema. All other changes, including deletions and semantic changes, are considered major version changes. The version numbers are documented in the header comment contained in the XML schema file. They are also available as annotations included as part of the complex type definition for the top-level schema element. This enables you to programmatically extract the version numbers from the XML schema file to include in XML request instances sent to the router. The version numbers are carried in the XML instances using the MajorVersion and MinorVersion attributes. This example shows the relevant portion of the complex type definition for an element that carries version information: BGP Configuration Commands Container 24 0 9-108 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Run-Time Use of Version Information bgp native_data_operations Configuration . . . . . .. The attribute group VersionAttributeGroup is defined as: Common version information attributes Run-Time Use of Version Information Each XML request must contain the major and minor version numbers of the client at the appropriate locations in the XML. These version numbers are compared to the version numbers running on the router. The behavior of the router, whether the request is accepted or rejected, depends on the value set for the AllowVersion MisMatch attribute. All requests are accepted when the AllowVersionMismatch attribute is set as TRUE. The request is then accepted or rejected based on these rules when the AllowVersionMismatch attribute is set as FALSE: • If there is a major version discrepancy, then the request fails. • If there is a minor version lag, that is, the client minor version is behind that of the router, then the request is attempted. • If there is a minor version creep, that is, the client minor version is ahead of that of the router, then the request fails. • If the version information has not been included in the request, then the request fails. • The default value is used when the request does not specify the AllowVersionMismatch attribute. The default value is currently set as TRUE. Each XML response can also contain the version numbers at the appropriate locations in the XML.9-109 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Run-Time Use of Version Information Note If the client minor version is behind that of the router, then the response may contain elements that are not recognized by the client application. The client application must be able to handle these additional elements. Placement of Version Information This example shows the placement of the MajorVersion and MinorVersion attributes within a client request to retrieve the global BGP configuration data for a specified autonomous system: Sample Client Request Showing Placement of Version Information 0 3 Sample XML Response from the Router 0 3 ... data returned here ... 9-110 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Run-Time Use of Version Information Version Lag with the AllowVersionMisMatch Attribute Set as TRUE The example shows a request and response with a version mismatch. In this case, because the AllowVersionMismatch attribute is set as TRUE, the request is attempted. This is also the default behavior when AllowVersionMismatch attribute is not specified in the request. The router attempts the request and if the request is successful returns a VersionMismatchExists attribute at the appropriate point within the response along with a VersionMismatchExistsBelow attribute on the operation tag. Note The version number, which is returned in the response, is the version running on the router. The versions in this example are hypothetical. Sample XML Client Request with a Version Mismatch 0 3 Sample XML Response from the Router VersionMismatchExists=”true”> 0 3 ... data returned here ... 9-111 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Run-Time Use of Version Information Version Lag with the AllowVersionMismatch Attribute Set as FALSE The example shows a request and response with a version mismatch, but the request specifies the AllowVersionMisMatch attribute as FALSE. In this case, the client minor version is behind the router, so the request is still attempted, but VersionMismatchExists and VersionMismatchExistsBelow attributes are not returned in the response. Note The version number returned is the response is the version number running on the router. The versions in this example are hypothetical. Sample XML Client Request with the AllowVersionMismatch Attribute Set as False 0 3 Sample XML Response from the Router 0 3 ... data returned here ... 9-112 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Run-Time Use of Version Information Version Creep with the AllowVersionMisMatch Attribute Set as TRUE The example shows a request and response with a version mismatch. In this case, the client is the AllowVersionMismatch attribute and is set as TRUE. The request is attempted. Note The version number returned is the response is the version number running on the router. The versions in this example are hypothetical. Sample XML Request with an AllowVersion Mismatch Attribute Set as TRUE 0 3 Sample XML Response from the Router VersionMismatchExists=”true”> 0 3 ... data returned here ... 9-113 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Retrieving Version Information Version Creep with the AllowVersionMisMatch Attribute Set as FALSE The example shows a request and response with a version mismatch. In this case, the client minor version is ahead of the router minor version, which results in an error response. Sample XML Request with an AllowVersion Mismatch Attribute Set as FALSE Sample XML Response from the Router ErrorMsg="'XML Service Library' detected the 'warning' condition 'An error was encountered in the XML beneath this operation tag'" > Retrieving Version Information The version of the XML schemas running on the router can be retrieved using the tag followed by the appropriate tags identifying the names of the desired components. In this example, the tag is used to retrieve the major and minor version numbers for the BGP component configuration schema: Sample XML Request to Retrieve Major and Minor Version Numbers Sample XML Response from the Router 9-114 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Retrieving Version Information This example shows how to retrieve the version information for all configuration schemas available on the router: Sample XML Request to Retrieve Version Information for All Configuration Schemas Sample XML Response from the Router .... .... ... 9-115 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Retrieving Schema Detail Retrieving Schema Detail The SchemaDetail boolean attribute can now be specified on the operation to instruct the router to return additional schema detail in the response. If the SchemaDetail attribute is specified in the request, each schema entity in the response contains three additional boolean attributes listed in Table 9-1. This example shows a request and response with the SchemaDetail attribute: Sample XML Client Request for Schema Detail Sample XML Response from the Router ... . .. Table 9-1 Content Attributes Content Attribute Description ContainsNaming Indicates whether or not the schema entity contains naming information. Getable Indicates whether or not operations are supported for this schema. Setable Indicates whether or not operations are supported for this schema.9-116 Cisco IOS XR XML API Guide OL-24657-01 Chapter 9 Cisco XML Schema Versioning Retrieving Schema Detail C H A P T E R 10-117 Cisco IOS XR XML API Guide OL-24657-01 10 Alarms The Cisco IOS XR XML API supports the registration and receipt of notifications; for example, asynchronous responses such as alarms, over any transport. The system supports alarms and event notifications over XML/SSH. An asynchronous registration request is followed by a synchronous response and any number of asynchronous responses. If a client wants to stop receiving a particular set of asynchronous responses at a later stage, the client sends a deregistration request. One type of notification that is supported by the Cisco IOS XR XML API is alarms; for example, syslog messages. The alarms that are received are restricted by a filter, which is specified in the registration request. An alarm registration request is followed by a synchronous response. If successful, the synchronous response contains a RegistrationID, which is used by the client to uniquely identify the applicable registration. A client can make many alarm registrations. If a client wants to stop receiving a particular set of alarms at a later stage, the client can send a deregistration request for the relevant RegistrationID or all Registration IDs for the session. When an asynchronous response is received that contains an alarm, the registration that resulted in the alarm is determined from the RegistrationID. These sections describe the XML used for every operation: • Alarm Registration, page 10-117 • Alarm Deregistration, page 10-118 • Alarm Notification, page 10-119 Alarm Registration Alarm registration and deregistration requests and responses and alarm notifications use the operation tag to distinguish them from other types of XML operations. A registration request contains the tag, which is followed by several tags that specify the filter requirement. If registration for all alarms is required, no filter is specified. These filter criteria are listed: • SourceID • Category • Group • Context • Code10-118 Cisco IOS XR XML API Guide OL-24657-01 Chapter 10 Alarms Alarm Deregistration • Severity • BiStateOnly If it succeeds, the response contains a tag with a RegistrationID attribute. If it fails, the filter tag that caused the error appears with an error message attribute. This example shows a registration request to receive all alarms for configuration change; for example, commit notifications: Sample XML Request from the Client Application CONFIG DB_COMMIT Sample XML Response from the Router Response MajorVersion="1" MinorVersion="0"> Note If a second registration is made with the same filter, or if the filters with two registrations overlap, these alarms that match both registrations are received twice. In general, each alarm is received once for each registration that it matches. If a session ends (for example, the connection is dropped), all registrations are automatically canceled. Alarm Deregistration An alarm deregistration request consists of the operation tag followed by the tag, with the optional attribute RegistrationID. If RegistrationID is specified, the value must be that returned from a previous registration request. The registration with that ID must not have already been deregistered or an error is returned. If it is not specified, the request results in all alarm registrations for that session being deregistered. This example shows a deregistration request for the RegistrationID returned from the registration request example: Sample XML Request from the Client Application 10-119 Cisco IOS XR XML API Guide OL-24657-01 Chapter 10 Alarms Alarm Notification Sample XML Response from the Router Alarm Notification Alarm notifications are contained within a pair of tags to distinguish them from normal responses. Each notification contains one or more alarms, each of which is contained within a pair of tags. The tags have an attribute RegistrationID, where the value is the RegistrationID returned in the registration that resulted in the alarm. The tags contain these fields for the alarm: • SourceID • EventID • Timestamp • Category • Group • Code • Severity • State • CorrelationID • AdditionalText This example shows the configuration commit alarm notification: RP/0/0/CPU0 84 1077270612 MGBL CONFIG DB_COMMIT Informational NotAvailable 0 config[65704]: %MGBL-CONFIG-6-DB_COMMIT : Configuration committed by user 'admin'. Use 'show commit changes 1000000490' to view the changes. 10-120 Cisco IOS XR XML API Guide OL-24657-01 Chapter 10 Alarms Alarm NotificationC H A P T E R 11-121 Cisco IOS XR XML API Guide OL-24657-01 11 Error Reporting in Cisco XML Responses The XML responses returned by the router contains error information as appropriate, including the operation, object, and cause of the error when possible. The error codes and messages returned from the router may originate in the XML agent or in one of the other infrastructure layers; for example, the XML Service Library, XML Parser Library, or Configuration Manager. Types of Reported Errors Table 11-1 lists the types of potential errors in XML Responses. These error categories are described in these sections: • Error Attributes, page 11-122 • Transport Errors, page 11-122 • XML Parse Errors, page 11-122 • XML Schema Errors, page 11-123 Table 11-1 Reported Error Types Error Type Description Transport errors Transport-specific errors are detected within the XML agent (and include failed authentication attempts). XML parse errors XML format or syntax errors are detected by the XML Parser Library (and include errors resulting from malformed XML, mismatched XML tags, and so on). XML schema errors XML schema errors are detected by the XML operation provider within the infrastructure (and include errors resulting from invalid operation types, invalid object hierarchies, values out of range, and so on). Operation processing errors Operation processing errors are errors encountered during the processing of an operation, typically as a result of committing the target configuration (and include errors returned from Configuration Manager and the infrastructure such as failed authorization attempts, and “invalid configuration errors” returned from the back-end Cisco IOS XR applications). 11-122 Cisco IOS XR XML API Guide OL-24657-01 Chapter 11 Error Reporting in Cisco XML Responses Types of Reported Errors • Operation Processing Errors, page 11-125 • Error Codes and Messages, page 11-126 Error Attributes If one or more errors occur during the processing of a requested operation, the corresponding XML response includes error information for each element or object class in error. The error information is included in the form of ErrorCode and ErrorMsg attributes providing a relevant error code and error message respectively. If one or more errors occur during the processing of an operation, error information is included for each error at the appropriate point in the response. In addition, error attributes are added at the operation element level. As a result, the client application does not have to search through the entire response to determine if an error has occurred. However, the client can still search through the response to identify each of the specific error conditions. Transport Errors Transport-specific errors, including failed authentication attempts, are handled by the appropriate XML agent. XML Parse Errors This general category of errors includes those resulting from malformed XML and mismatched XML tags. The router checks each XML request, but does not validate the request against an XML schema. If the XML contains invalid syntax and thus fails the well-formedness check, the error indication is returned in the form of error attributes placed at the appropriate point in the response. In such cases, the response may not contain the same XML as was received in the request, but just the portions to the point where the syntax error was encountered. In this example, the client application sends a request to the router that contains mismatched tags, that is, the opening tag is not paired with a closing tag. This example illustrates the format and placement of the error attributes. Note The actual error codes and messages might be different than what is shown in this example. Also, the actual error attributes does not contain new line characters. Sample XML Client Request Containing Mismatched Tags 0 311-123 Cisco IOS XR XML API Guide OL-24657-01 Chapter 11 Error Reporting in Cisco XML Responses Types of Reported Errors Sample XML Response from the Router XML Schema Errors XML schema errors are detected by the XML operation providers. This general category of errors includes those resulting from invalid operation types, invalid object hierarchies, and invalid naming or value elements. However, some schema errors may go undetected because, as previously noted, the router does not validate the request against an XML schema. In this example, the client application has requested a operation specifying an object that does not exist at this location in the Border Gateway Protocol (BGP) component hierarchy. This example illustrates the format and placement of the error attributes. Note The actual error codes and messages may be different than those shown in the example. Sample XML Client Request Specifying an Invalid Object Hierarchy 0 3 10 11-124 Cisco IOS XR XML API Guide OL-24657-01 Chapter 11 Error Reporting in Cisco XML Responses Types of Reported Errors Sample XML Response from the Router 0 3 This example also illustrates a schema error. In this case, the client application has requested a operation specifying a value for the object that is not within the range of valid values for this item. Sample XML Request Specifying an Invalid Object Value Range 0 3 6000 11-125 Cisco IOS XR XML API Guide OL-24657-01 Chapter 11 Error Reporting in Cisco XML Responses Types of Reported Errors Sample XML Response from the Router 0 3 Operation Processing Errors Operation processing errors include errors encountered during the processing of an operation, typically as a result of committing the target configuration after previous or operations. While processing an operation, errors are returned from Configuration Manager and the infrastructure, failed authorization attempts occur, and “invalid configuration errors” are returned from the back-end Cisco IOS XR applications. This example illustrates an operation processing error resulting from a request specifying an unrecognized iterator ID: Sample XML Client Request and Processing Error Sample XML Response from the Router 11-126 Cisco IOS XR XML API Guide OL-24657-01 Chapter 11 Error Reporting in Cisco XML Responses Types of Reported Errors Error Codes and Messages The error codes and messages returned from the router may originate in any one of several components. The error codes (cerrnos) returned from these layers are 32-bit integer values. In general, for a given error condition, the error message returned in the XML is the same as the error message displayed on the CLI.C H A P T E R 12-127 Cisco IOS XR XML API Guide OL-24657-01 12 Summary of Cisco XML API Configuration Tags Table 12-1 provides the CLI to XML application programming interface (API) tag mapping for the router target configuration. Table 12-1 CLI Command or Operation to XML Tag Mapping CLI Command or Operation XML Tag To end, abort, or exit 1 (from top config mode) 2 clear show config with show config running with show config merge with show config failed with followed by with configure exclusive 3 4 To change the selected config with To delete the selected config with commit best-effort commit show config failed with show commit changes commitid with show commit changes since commitid with rollback configuration to commitid with rollback configuration last number with show rollback changes to commitid with show rollback changes last number with 12-128 Cisco IOS XR XML API Guide OL-24657-01 Chapter 12 Summary of Cisco XML API Configuration Tags show rollback points show configuration sessions 1. These CLI operations end the configuration session and unlock the running configuration session if it is locked. 2. This XML tag releases the lock on a running configuration but does not end the configuration session. 3. This CLI command starts a new configuration session and locks the running configuration. 4. This XML tag locks the running configuration from a configuration session that is already in progress. Table 12-1 CLI Command or Operation to XML Tag Mapping (continued) CLI Command or Operation XML TagC H A P T E R 13-129 Cisco IOS XR XML API Guide OL-24657-01 13 XML Transport and Event Notifications This chapter contains these sections: • TTY-Based Transports, page 13-129 • Dedicated Connection Based Transports, page 13-131 • SSL Dedicated Connection based Transports, page 13-133 TTY-Based Transports These sections describe how to use the TTY-based transports: • Enabling the TTY XML Agent, page 13-129 • Enabling a Session from a Client, page 13-130 • Sending XML Requests and Receiving Responses, page 13-130 • Configuring Idle Session Timeout, page 13-132 • Ending a Session, page 13-130 • Errors That Result in No XML Response Being Produced, page 13-131 Enabling the TTY XML Agent To enable the TTY agent on the router, which is ready to handle incoming XML sessions over Telnet and Secured Shell (SSH), enter the xml agent tty command, as shown in this example: RP/0/RP0/CPU0:router# configure RP/0/RP0/CPU0:router(config)# xml agent tty RP/0/RP0/CPU0:router(config)# commit RP/0/RP0/CPU0:router(config)# exit For more information about the xml agent tty command, see Cisco IOS XR System Management Configuration Guide. TTY (SSH) agent is telnet based, so IPv6 addressing is supported.13-130 Cisco IOS XR XML API Guide OL-24657-01 Chapter 13 XML Transport and Event Notifications TTY-Based Transports Enabling a Session from a Client To enable a session from a remote client, invoke SSH or Telnet to establish a connection with the management port on the router. When prompted by the transport protocol, enter a valid username and password. After you have successfully logged on, enter xml at the router prompt to be in XML mode. A maximum of 50 XML sessions total can be started over a dedicated port, TTY, SSH, and Secure Sockets Layer (SSL) dedicated port. Note You should use, if configured, either the management port or any of the external interfaces rather than a connection to the console or auxiliary port. The management port can have a significantly higher bandwidth and offer better performance. Sending XML Requests and Receiving Responses To send an XML request, write the request to the Telnet/SSH session. The session can be used interactively; for example, typing or pasting the XML at the XML> prompt from a window. Note The XML request must be followed by a new-line character; for example, press Return, before the request is processed. Any responses, either synchronous or asynchronous, are also displayed in the session window. The end of a synchronous response is always represented with and asynchronous responses (for example), notifications, end with . The client application is single threaded in the context of one session and sends requests synchronously; for example, requests must not be sent until the response to the previous request is received. Configuring Idle Session Timeout When a session times out, the resource from that session is reclaimed. By default, XML agents do not have an idle session timeout. To configure the idle session timeout in minutes for the XML agents, use this command: xml agent [tty | ssl] session timeout <1-1440> Ending a Session If you are using a session interactively from a terminal window, you can close the window. To manually exit the session, at the prompt: 1. Enter the exit command to end XML mode. 2. Enter the exit command to end the Telnet/SSH session.13-131 Cisco IOS XR XML API Guide OL-24657-01 Chapter 13 XML Transport and Event Notifications Dedicated Connection Based Transports Errors That Result in No XML Response Being Produced If the XML infrastructure is unable to return an XML response, the TTY agent returns an error code and message in the this format: ERROR: 0x%x %s\n Dedicated Connection Based Transports These sections describe how to use the dedicated connection-based transports: • Enabling the Dedicated XML Agent, page 13-131 • Enabling a Session from a Client, page 13-132 • Sending XML Requests and Receiving Responses, page 13-132 • Configuring Idle Session Timeout, page 13-132 • Ending a Session, page 13-132 • Errors That Result in No XML Response Being Produced, page 13-132 Enabling the Dedicated XML Agent To enable the dedicated agent on the router, which is ready to handle incoming XML sessions over a dedicated TCP port (38751), enter the xml agent command, as shown in the following example: RP/0/RP0/CPU0:router# configure RP/0/RP0/CPU0:router(config)# xml agent RP/0/RP0/CPU0:router(config)# aaa authorization exec default local RP/0/RP0/CPU0:router(config)# commit RP/0/RP0/CPU0:router(config)# exit For more information about the xml agent command, see Cisco IOS XR System Management Configuration Guide. The default addressing protocol for the XML dedicated agent is • IPv4 enabled • IPv6 disabled To configure a dedicated agent to receive and send messages through IPv6 protocol: xml agent ipv6 enable To configure dedicated agent to disable IPv4 protocol xml agent ipv4 disable To receive and send messages only through IPv6 protocol: xml agent ipv4 disable xml agent ipv6 enable13-132 Cisco IOS XR XML API Guide OL-24657-01 Chapter 13 XML Transport and Event Notifications Dedicated Connection Based Transports Enabling a Session from a Client To enable a session from a remote client, establish a TCP connection with the dedicated port (38751) on the router. When prompted, enter a valid username and password. After you have successfully logged on, the session is in XML mode and is ready to receive XML requests. A maximum of 50 XML sessions total can be started over dedicated port, TTY, SSH, and SSL dedicated port. Sending XML Requests and Receiving Responses To send an XML request, write the request to the established session. The session can be used interactively; for example, typing or pasting the XML at the XML> prompt from a window. Note The XML request must be followed by a new-line character; for example, press Return, before the request is processed. Any responses, either synchronous or asynchronous, are also displayed in the session window. The end of a synchronous response is always represented with and asynchronous responses (for example), notifications, end with . The client application is single threaded in the context of one session and sends requests synchronously; for example, requests must not be sent until the response to the previous request is received. Configuring Idle Session Timeout When a session times out, the resource from that session is reclaimed. By default, XML agents do not have an idle session timeout. To configure the idle session timeout in minutes for the XML agents, use this command: xml agent [tty | ssl] session timeout <1-1440> Ending a Session If you are using a session interactively from a terminal window, you can close the window. To manually exit the session, at the prompt: 1. Enter the exit command to end XML mode. 2. Enter the exit command to end the Telnet/SSH session. Errors That Result in No XML Response Being Produced If the XML infrastructure is unable to return an XML response, the TTY agent returns an error code and message in this format: ERROR: 0x%x %s\n13-133 Cisco IOS XR XML API Guide OL-24657-01 Chapter 13 XML Transport and Event Notifications SSL Dedicated Connection based Transports SSL Dedicated Connection based Transports These sections describe how to use the dedicated connection based transports: • Enabling the SSL Dedicated XML Agent, page 13-133 • Enabling a Session from a Client, page 13-133 • Sending XML Requests and Receiving Responses, page 13-133 • Configuring Idle Session Timeout, page 13-134 • Ending a Session, page 13-134 • Errors That Result in No XML Response Being Produced, page 13-134 Enabling the SSL Dedicated XML Agent To enable the SSL dedicated agent on the router, which is ready to handle incoming XML sessions over dedicated TCP port (38752), enter the xml agent command, as shown in this example: RP/0/RP0/CPU0:router# configure RP/0/RP0/CPU0:router(config)# xml agent ssl RP/0/RP0/CPU0:router(config)# aaa authorization exec default local RP/0/RP0/CPU0:router(config)# commit RP/0/RP0/CPU0:router(config)# exit Note The k9sec package is required to use the SSL agent. The configuration is rejected during a commit when the k9sec package is not active on the system. When the k9sec package is deactivated after configuring the SSL agent, the agent is not available. The SSL dedicated agent uses IPSec, so IPv6 addressing is supported. Enabling a Session from a Client To enable a session from a remote client, establish a TCP connection with the dedicated port (38752) on the router. When prompted, enter a valid username and password. After you have successfully logged on, the session is in XML mode and is ready to receive XML requests. A maximum of 50 XML sessions can be started over a dedicated port, TTY, SSH, and a SSL dedicated port. Sending XML Requests and Receiving Responses To send an XML request, write the request to the established session. The session can be used interactively; for example, typing or pasting the XML at the XML> prompt from a window. The XML request must be followed by a new-line character. For example, press Return before the request is processed. Any responses, either synchronous or asynchronous, are also displayed in the session window. The end of a synchronous response is always represented with . Asynchronous responses end with . 13-134 Cisco IOS XR XML API Guide OL-24657-01 Chapter 13 XML Transport and Event Notifications SSL Dedicated Connection based Transports The client application is single threaded in the context of one session and sends requests synchronously. Requests must not be sent until the response to the previous request is received. Configuring Idle Session Timeout When a session times out, the resource from that session is reclaimed. By default, XML agents do not have an idle session timeout. To configure the idle session timeout in minutes for the XML agents, use this command: xml agent [tty | ssl] session timeout <1-1440> Ending a Session If you are using a session interactively from a terminal window, you can close the window. To manually exit the session, at the prompt: 1. Enter the exit command to end XML mode. 2. Enter the exit command to end the Telnet/SSH session. Errors That Result in No XML Response Being Produced If the XML infrastructure is unable to return an XML response, the SSL dedicated agent returns an error code and message in this format: ERROR: 0x%x %s\n C H A P T E R 14-135 Cisco IOS XR XML API Guide OL-24657-01 14 Cisco XML Schemas This chapter contains information about common XML schemas. The structure and allowable content of the XML request and response instances supported by the Cisco IOS XR XML application programming interface (API) are documented by means of XML schemas (.xsd files). The XML schemas are documented using the standard World Wide Web Consortium (W3C) XML schema language, which provides a much more powerful and flexible mechanism for describing schemas than can be achieved using Document Type Definitions (DTDs). The set of XML schemas consists of a small set of common high-level schemas and a larger number of component-specific schemas as described in this chapter. For more information on the W3C XML Schema standard, see this URL: http://www.w3.org/XML/Schema This chapter contains these sections: • XML Schema Retrieval, page 14-135 • Common XML Schemas, page 14-136 • Component XML Schemas, page 14-136 XML Schema Retrieval The XML schemas that belong to the features in a particular package are obtained as a .tar file from cisco.com. To retrieve the XML schemas, you must: 1. Click this URL to display the Downloads page: http://tools.cisco.com/support/downloads/go/Redirect.x?mdfid=268437899 Note Select Downloads. Only customer or partner viewers can access the Download Software page. Guest users will get an error. 2. Select Cisco IOS XR Software. 3. Select IOS XR XML Schemas. 4. Select the XML schema for your platform. Once untarred, all the XML schema files appear as a flat directory of .xsd files and can be opened with any XML schema viewing application, such as XMLSpy.14-136 Cisco IOS XR XML API Guide OL-24657-01 Chapter 14 Cisco XML Schemas Common XML Schemas Common XML Schemas Among the .xsd files that belong to a BASE package are the common Cisco IOS XR XML schemas that include definitions of the high-level XML request and response instances, operations, and common datatypes. These common XML schemas are listed: • alarm_operations.xsd • config_services_operations.xsd • cli_operations.xsd • common_datatypes.xsd • xml_api_common.xsd • xml_api_protocol.xsd • native_data_common.xsd • native_data_operations.xsd Component XML Schemas In addition to the common XML schemas, component XML schemas (such as native data) are provided and contain the data model for each feature. There is typically one component XML schema for each major type of data supported by the component—configuration, operational, action, administration operational, and administration action data—plus any complex data type definitions in the operational space. Note Sometimes common schema files exist for a component that contain resources used by the component’s other schema files (for example, the data types to be used by both configuration data and operational data). You should use only the XML objects that are defined in the XML schema files. You should not use any unpublished objects that may be shown in the XML returned from the router. Schema File Organization There is no hard link from the high-level XML request schemas (namespace_types.xsd) and the component schemas. Instead, links appear in the component schemas in the form of include elements that specify the file in which the parent element exists. The name of the component .xsd file also indicates where in the hierarchy the file’s contents reside. If the file ends with _cfg.xsd, it appears as a child of “Configuration”; if it ends with _if_cfg.xsd, it appears as a child of “InterfaceConfiguration”, and so on. In addition, the comment header in each .xsd file names the parent object of each top level object in the schema.14-137 Cisco IOS XR XML API Guide OL-24657-01 Chapter 14 Cisco XML Schemas Component XML Schemas Schema File Upgrades If a new version of a schema file becomes available (or has to be uploaded to the router as part of an upgrade), the new version of the file can replace the old version of the file in a straight swap. All other files are unaffected. Therefore, if a component is replaced, only the .xsd files pertaining to that component is replaced.14-138 Cisco IOS XR XML API Guide OL-24657-01 Chapter 14 Cisco XML Schemas Component XML SchemasC H A P T E R 15-139 Cisco IOS XR XML API Guide OL-24657-01 15 Network Configuration Protocol Network Configuration Protocol (NETCONF) defines an XML-based interface between a network device and a network management system to provide a mechanism to manage, configure, and monitor a network device. In Cisco IOS-XR, NMS applications use defined XML schemas to manage network devices from multiple vendors. These capabilities are supported from a Cisco IOS XR agent to a client: • TTY NETCONF session—Logon through telnet and then enter the netconf command. • SSH NETCONF session—Logon through SSH and then enter the netconf command. This example shows a message that the agent sends to a client: urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:capability:candidate:1.0 4 These sections about NETCONF are covered: • Starting a NETCONF Session, page 15-139 • Ending a NETCONF Agent Session, page 15-140 • Starting an SSH NETCONF Session, page 15-140 • Ending an SSH NETCONF Agent Session, page 15-141 • Configuring a NETCONF agent, page 15-141 • Limitations of NETCONF in Cisco IOS XR, page 15-142 Starting a NETCONF Session To start a NETCONF session, enter the netconf command from the exec prompt (through telnet or SSH). This example shows how to start a TTY NETCONF agent session: client(/users/ore)> telnet 1.66.32.82 Trying 1.66.32.82... Connected to 1.66.32.82.15-140 Cisco IOS XR XML API Guide OL-24657-01 Chapter 15 Network Configuration Protocol Ending a NETCONF Agent Session Escape character is '^]'. User Access Verification Username: Password: RP/0/1/CPU0:Router# netconf echo format urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:capability:candidate:1.0 4 ]]>]]> When a new session is created, the NETCONF agent immediately sends out a message with capabilities. At the end of each message transmission, the NETCONF agent sends the EOD marker ‘]]>]]>’ The NETCONF agent does not display a prompt like the XML agent does (XML>). The NETCONF TTY agent does not echo back the received messages and does not format returning messages by default. These capabilities can be added by using the ‘echo’ and ‘format’ options. The client is also required to send a message with capabilities. Ending a NETCONF Agent Session Unlike the XML agent, the client ends the session by sending a request. ]]>]]> The agent replies with an tag and then closes the session. ]]>]]> Starting an SSH NETCONF Session This example shows how to start an SSH NETCONF agent session: client(/users/ore)> ssh lab@1.66.32.82 lab@1.66.32.82's password: RP/0/1/CPU0:gsrb#netconf echo format 15-141 Cisco IOS XR XML API Guide OL-24657-01 Chapter 15 Network Configuration Protocol Ending an SSH NETCONF Agent Session urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:capability:candidate:1.0 4 ]]>]]> The client can also directly start a NETCONF session by specifying the netconf command on the ssh command line: client(/users/ore)> ssh lab@1.66.32.82 netconf echo format lab@1.66.32.82's password: urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:capability:candidate:1.0 4 ]]>]]> Ending an SSH NETCONF Agent Session This example shows how to end an SSH NETCONF agent session: ]]>]]> The agent replies with an tag and then closes the session. ]]>]]> Configuring a NETCONF agent To configure a NETCONF TTY agent, use the netconf agent tty command. Use the throttle and session timeout parameters as you would with the XML TTY agent. netconf agent tty throttle (memory | process-rate) session timeout To enable the NETCONF SSH agent, use this command: ssh server v2 netconf agent tty15-142 Cisco IOS XR XML API Guide OL-24657-01 Chapter 15 Network Configuration Protocol Limitations of NETCONF in Cisco IOS XR Limitations of NETCONF in Cisco IOS XR This sections identifies the limitations of NETCONF in Cisco IOS XR Software. Configuration Datastores Cisco IOS XR supports these configuration datastores: • Cisco IOS XR does not support the configuration datastore. Configuration Capabilities Cisco IOS XR supports these configuration capabilities: • Candidate Configuration Capability urn:ietf:params:netconf:capability:candidate:1.0 Cisco IOS XR does not support these configuration capabilities: • Writable-Running Capability urn:ietf:params:netconf:capability:writable-running:1.0 • Confirmed Commit Capability urn:ietf:params:netconf:capability:confirmed-commit:1.0 Transport (RFC4741 and RFC4742) These transport operations are supported: • Connection-oriented operation • Authentication • SSH Transport—Shell based SSH. IANA-assigned TCP port <830> for NETCONF SSH is not supported. • Other transport Subtree Filtering (RFC4741) NETCONF has these subtree filtering limitations in Cisco IOS XR: • Namespace Selection—Filtering based on specified namespace. This is not supported because Cisco IOS XR does not publish schema name spaces. • Attribute Match Expressions—Filtering is done by matching a specified attribute value. This filtering with the “Match” attribute can be specified only in Table classes. See this example: 15-143 Cisco IOS XR XML API Guide OL-24657-01 Chapter 15 Network Configuration Protocol Limitations of NETCONF in Cisco IOS XR act • Containment Nodes—Filtering is done by specifying nodes (classes) that have child nodes (classes). This filtering is by specifying container classes. See this example: • Selection Nodes—Filtering is done by specifying leaf nodes. This filtering specifies leaf classes. See this example: act GigabitEthernet0/3/0/1 • Content Match Nodes—Filtering is done by exactly matching the content of a leaf node. This filtering is done by specifying naming the class value for table classes. See this example: 15-144 Cisco IOS XR XML API Guide OL-24657-01 Chapter 15 Network Configuration Protocol Limitations of NETCONF in Cisco IOS XR act Loopback0 According to the RFC, a request using an empty content match node should return all elements of all entries of the table. For example, for this request, the response should return elements of all the entries of : In Cisco IOS XR, this request is not supported and is errored out. Protocol Operations (RFC4741) These protocol operations are supported in Cisco IOS XR: • get—Root level query that returns both the entire configuration and state data is not supported • get-config • edit-config • lock • unlock • close-session • commit (by the Candidate Configuration Capability) • discard-change (by the Candidate Configuration Capability) 15-145 Cisco IOS XR XML API Guide OL-24657-01 Chapter 15 Network Configuration Protocol Limitations of NETCONF in Cisco IOS XR Event Notifications (RFC5277) Event notifications are not supported in Cisco IOS XR.15-146 Cisco IOS XR XML API Guide OL-24657-01 Chapter 15 Network Configuration Protocol Limitations of NETCONF in Cisco IOS XRC H A P T E R 16-147 Cisco IOS XR XML API Guide OL-24657-01 16 Cisco IOS XR Perl Scripting Toolkit This chapter describes the Cisco IOS XR Perl Scripting Toolkit as an alternative method to existing router management methods. This method enables the router to be managed by a Perl script running on a separate machine. Management commands and data are sent to, and from, the router in the form of XML over either a Telnet or an SSH connection. The well-defined and consistent structure of XML, which is used for both commands and data, makes it easy to write scripts that can interactively manage the router, display information returned from the router in the format required, or manage multiple routers at once. These sections describe how to use the Cisco IOS XR Perl Scripting Toolkit: • Cisco IOS XR Perl Scripting Toolkit Concepts, page 16-148 • Security Implications for the Cisco IOS XR Perl Scripting Toolkit, page 16-148 • Prerequisites for Installing the Cisco IOS XR Perl Scripting Toolkit, page 16-148 • Installing the Cisco IOS XR Perl Scripting Toolkit, page 16-149 • Using the Cisco IOS XR Perl XML API in a Perl Script, page 16-150 • Handling Types of Errors for the Cisco IOS XR Perl XML API, page 16-150 • Starting a Management Session on a Router, page 16-150 • Closing a Management Session on a Router, page 16-152 • Sending an XML Request to the Router, page 16-152 • Using Response Objects, page 16-153 • Using the Error Objects, page 16-154 • Using the Configuration Services Methods, page 16-154 • Using the Cisco IOS XR Perl Data Object Interface, page 16-157 • Cisco IOS XR Perl Notification and Alarm API, page 16-166 • Examples of Using the Cisco IOS XR Perl XML API, page 16-17016-148 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Cisco IOS XR Perl Scripting Toolkit Concepts Cisco IOS XR Perl Scripting Toolkit Concepts Table 16-1 describes the toolkit concepts. Some sample scripts are modified and show how to use the API in your own scripts. Security Implications for the Cisco IOS XR Perl Scripting Toolkit Similar to using the CLI over a Telnet or Secured Shell (SSH) connection, all authentication and authorization are handled by authentication, authorization, and accounting (AAA) on the router. A script prompts you to enter a password at run time, which ensures that passwords never get stored on the client machine. Therefore, the security implications for using the toolkit are identical to the CLI over the same transport. Prerequisites for Installing the Cisco IOS XR Perl Scripting Toolkit To use the toolkit, you must have installed Perl version 5.6 on the client machine that runs UNIX and Linux. To use the SSH transport option, you must have the SSH client executable installed on the machine and in your path. You need to install these specific standard Perl modules to use various functions: • XML::LibXML—This module is essential for using the Perl XML API and requires that the libxml2 library be installed on the system first. This must be the version that is compatible with the version of XML::LibXML. The toolkit is tested to work with XML::LibXML version 1.58 and libxml2 version 2.6.6. If you are installing libxml2 from a source, you must apply the included patch file before compiling. • Term::ReadKey (optional but recommended)—This module reads passwords without displaying them on the screen. • Net::Telnet—This module is needed if you are using the Telnet or SSH transport modules. If one of the modules is not available in the current version, you are warned during the installation process. Before installing the toolkit, you should install the current versions of the modules. You can obtain all modules from this location: http://www.cpan.org/ Table 16-1 List of Concepts for the IOS XR Perl Scripting Toolkit Concept Definition Cisco IOS XR Perl XML API Consists of the core of the toolkit and provides the ability to create management sessions, send management requests, and receive responses by using Perl objects and methods. Cisco IOS XR Perl Data Object API Allows management requests to be sent and responses received entirely using Perl objects and data structures without any knowledge of the underlying XML. Cisco IOS XR Perl Notification/Alarm API Allows a script to register for notifications (for example, alarms), on a management session and receive the notifications asynchronously as Perl objects.16-149 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Installing the Cisco IOS XR Perl Scripting Toolkit These modules are not necessary for using the API, but are required to run some sample scripts: • XML::LibXSLT—This module is needed for the sample scripts that use XSLT to produce HTML pages. The module also requires that the libxslt library be installed on the system first. The toolkit is tested to work with XML::LibXSLT version 1.57 and libxslt version 1.1.3. • Mail::Send—This module is needed only for the notifications sample script. Installing the Cisco IOS XR Perl Scripting Toolkit The Cisco IOS XR Perl Scripting Toolkit is distributed in a file named: Cisco-IOS_XR-Perl-Scripting-Toolkit-.tar.gz. To install the Cisco IOS XR Perl Scripting Toolkit, perform these steps: Step 1 Extract the contents from the directory in which the file resides by entering this command: tar -f Cisco-IOS_XR-Perl-Scripting-Toolkit-.tar.gz -xzC Table 16-2 defines the parameters. Step 2 Use the cd command to change to the toolkit installation directory and enter this command: perl Makefile.PL If the command gives a warning that one of the prerequisite modules is not found, download and install the applicable module from the Comprehensive Perl Archive Network (CPAN) before using the API. Step 3 Use the make command to maintain a set of programs, as shown in this example: make Step 4 Use the make install command, as shown in this example: make install Ensure that you have the applicable permission requirements for the installation. You may need to have root privileges. If you do not encounter any errors, the toolkit is installed successfully. The Perl modules are copied into the appropriate directory, and you can use your own Perl scripts. Table 16-2 Toolkit Installation Directory Parameters Parameter Description Defines the version of the toolkit to install, for example, version 1.0. Specifies the existing directory in which to create the toolkit installation directory. A directory called Cisco-IOS_XR-Perl-Scripting-Toolkit- is created within the directory along with the extracted contents.16-150 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using the Cisco IOS XR Perl XML API in a Perl Script Using the Cisco IOS XR Perl XML API in a Perl Script To use the Cisco IOS XR Perl XML API in a Perl application, import the module by including this statement at the top of the script: use Cisco::IOS_XR; If you are using the Data Object interface, you can specify extra import options in the statement. For more information about the objects, see the “Creating Data Objects” section on page 16-159. Handling Types of Errors for the Cisco IOS XR Perl XML API These types of errors can occur when using the Cisco IOS XR Perl XML API: • Errors returned from the router—Specify that the errors are produced during the processing of an XML request and are returned to you in an XML response document. For more information about how these errors are handled, see the “Using the Error Objects” section on page 16-154. • Errors produced within the Perl XML API modules—Specify that the script cannot continue. The module causes the script to be terminated with the appropriate error message. If the script writer wants the script to handle these error types, the writer must write the die handlers (for example, enclose the call to the API function within an eval{} block). Starting a Management Session on a Router Before any requests are sent, a management session must be started on the router, which is done by creating a new object of type named Cisco::IOS_XR. The new object is used for all further requests during the session, and the session is ended when the object is destroyed. A Cisco::IOS_XR object is created by calling Cisco::IOS_XR::new. Table 16-3 lists the optional parameters specified as arguments. Table 16-3 Argument Definitions Name Description use_command_line Controls whether or not the new() method parses the command-line options given when the script was invoked. If the value of the argument is true, which is the default, the command-line options specify or override any of the subsequent arguments and control debug and logging options. The value of 0 defines the value as false. interactive If the value of the argument is true, the script prompts you for the username and password if they have not been specified either in the script or on the command line. The Term::ReadKey module must be installed. The most secure way of using the toolkit is not to have the input echoed to the screen, which avoids hard coding or any record of passwords being used. The default value is false, which means that the script does not ask for user input. As a command-line option, the interactive argument does not take any arguments. You can specify -interactive to turn on the interactive mode.16-151 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Starting a Management Session on a Router This example shows the arguments given using the standard Perl hash notation: use Cisco::IOS_XR; my $session = new Cisco::IOS_XR(transport => 'telnet', host => 'router1', port => 7000, username => 'john', password => 'smith', connection_timeout => 3); Alternatively, the arguments can be specified in a file. For example: The contents of ‘/usrs/trice/perlxml.cfg’: [myrouter] transport = telnet host = router1 username = john password = smith connection_timeout = 3 In the script, the file and profile name are specified: use Cisco : : IOS_XR; my $session = new Cisco: :IOS_XR(config_file => ‘/usrs/trice/perlxml.cfg’, profile => ‘myrouter’); transport Means by which the Perl application should connect to the router, which defaults to Telnet. If a different value is specified, the new() method searches for a package called Cisco::IOS_XR::Transport::. If found, the Perl application uses that package to connect to the router. ssh_version If the chosen transport option is SSH and the SSH executable on your system supports SSH v2, specifies which version of SSH you want to use for the connection. The valid values are 1 and 2. If the SSH executable supports only version 1, an error is caused by specifying the ssh_version argument. host Specifies the name or IP address of the router to connect. The router console or auxiliary ports should not be used because they are likely to cause problems for the script when logging in and offer significantly lower performance than a management port. port Specifies the TCP port for the connection. The default value depends on the transport being used. username Specifies the username to log in to the router. password Specifies the corresponding password. connection_timeout Specifies the timeout value that is used to connect and log in to the session. If not specified, the default value is 5 seconds. response_timeout Specifies the timeout value that is used when waiting for a response to an XML request. If not specified, the default value is 10 seconds. prompt Specifies the prompt that is displayed on the router after a successful log in. The default is #. Table 16-3 Argument Definitions (continued) Name Description16-152 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Closing a Management Session on a Router Table 16-4 describes the additional command-line options that can be specified. To use the command-line options when invoking a script, use the -option value (assuming the option has a value). The option name does not need to be given in full, but must be long enough to be distinguished from other options. This is displayed: perl my_script.pl -host my_router -user john -interactive -debug xml Closing a Management Session on a Router When an object of type Cisco::IOS_XR is created, the transport connection to the router and any associated resources on the router are maintained until the object is destroyed and automatically cleaned. For most scripts, the process should occur automatically when the script ends. To close a particular session during the course of the script, use the close() method. You can perform an operation on a large set of routers sequentially, and not keep all sessions open for the duration of the script, as displayed in this example: my $session1 = new Cisco::IOS_XR(host => ‘router1’, ...); #do some stuff $session1->close; my $session2 = new Cisco::IOS_XR(host => ‘router2’, ...); # do some stuff ... Sending an XML Request to the Router Requests and responses pass between the client and router in the form of XML. Depending on whether the XML is stored in a string or file, you can construct an XML request that is sent to the router using either the send_req or send_req_file method. Some requests are sent without specifying any XML by using the configuration services methods; for example, commit and lock or the Data Object interface. This example shows how to send an XML request in the form of a string: my $xml_req_string = ‘...’; my $response = $session->send_req($xml_req_string); This example shows how to send a request stored in a file: my $response = $session->send_req_file('request.xml'); Table 16-4 Command-Line Options Name Description debug Turns on the specified debug type and can be repeated to turn on more than one type. logging Turns on the specified logging type and can be repeated to turn on more than one type. log_file Specifies the name of the log file to use. telnet_input_log Specifies the file used for the Telnet input log, if you are using Telnet. telnet_dump_log Specifies the file used for the Telnet dump log, if you are using Telnet.16-153 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using Response Objects Using Response Objects Both of the send_req and send_req_file methods return a Cisco::IOS_XR::Response object, which contains the XML response returned by the router. Note Both send methods handle iterators in the background; so if a response consists of many parts, the response object returned is the result of merging them back together. Retrieving the Response XML as a String This example shows how to use the to_string method: $xml_response_string = $response->to_string; Writing the Response XML Directly to a File This example shows how to use the write_file method by specifying the name of the file to be written: $response->write_file('response.xml'); Retrieving the Data Object Model Tree Representation of the Response This example shows how to retrieve a Data Object Model (DOM) tree representation for the response: my $document = $response->get_dom_tree; You should be familiar with the DOM, which an XML document is represented in an object tree structure. For more information, see this URL: http://www.w3.org/DOM/ Note The returned DOM tree type will be of type XML::LibXML::Document, because this is the form in which the response is held internally. The method is quick, because it does not perform extra parsing and should be used in preference to retrieving the string form of the XML and parsing it again (unless a different DOM library is used). Determining if an Error Occurred While Processing a Request This example shows how to determine whether an error has occurred while processing a request: my $error = $response->get_error; if (defined($error)) { die $error; } Use the get_error method to return one error from the response. This returns an error object that represents the first error found or is undefined if none are found. Retrieving a List of All Errors Found in the Response XML This example shows how to list all errors that occur, rather than just one, by using the get_errors method: my @errors = $response->get_errors; The get_errors method returns an array of error objects that represents all errors that were found in the response XML. For more information, see the “Using the Error Objects” section on page 16-154.16-154 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using the Error Objects Using the Error Objects Error objects are returned when calling the get_error and get_errors methods on a response object, and are used to represent an error encountered in an XML response. Table 16-5 lists the methods for the object. Using the Configuration Services Methods Methods are provided to enable the standard configuration services operations to be performed without knowledge of the underlying XML. These are the operations that are usually performed at the start or end of a configuration session, such as locking the running configuration or saving the configuration to a file. Committing the Target Configuration The config_commit() function takes these optional arguments: • mode • label • comment • Replace • KeepFailedConfig • IgnoreOtherSessions • Confirmed This example shows how to use the config_commit function: $response = $session->config_commit(Label => 'Example1', Comment => 'Just an example'); A response object is returned from which any errors can be extracted, if desired. To retrieve the commit ID that was assigned to the commit upon success, you can call the get_commit_id() method on the response object, as shown in this example: $commit_id = $response->get_commit_id(); Table 16-5 List of Methods for the Object Method Description get_message Returns the error message string that was found in the XML. get_code Returns the corresponding error code. get_element Returns the tag name of the XML element in which the error was found. get_dom_node Returns a reference to the element node in the response DOM1 tree. 1. DOM = Data Object Model. to_string Returns a string that contains the error message, code, and element name. If the error object is used in a scalar context, the method is used automatically to convert it to a string. This example displays all information in an error: Error encountered in object ConfederationPeerASTable: 'XMLMDA' detected the 'warning' condition 'The XML request does not conform to the schema. A child element of the element on which this error appears includes a non-existent naming, filter, or value element. Please check the request against the schema.' Error code: 0x4368a00016-155 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using the Configuration Services Methods Locking and Unlocking the Running Configuration This example shows how to use the config_lock and config_unlock functions, which takes no arguments: $error = $session->config_lock; $error = $session->config_unlock; Loading a Configuration from a File This example shows how to contain a filename as an argument: $error = $session->config_load(Filename => 'test_config.cfg'); Loading a Failed Configuration This example shows how to use the config_load_failed function, which takes no arguments: $error = $session->config_load_failed; Saving a Configuration to a File This example shows how to use two arguments for the config_save() function: $error = $session->config_save(Filename => 'disk0:/my_config.cfg’, Overwrite => 'true'); The first argument shows how to use the filename to which to write and the Boolean overwrite setting. The filename must be given with a full path. The second argument is optional. Clearing the Target Configuration This example shows how to use the config_clear function, which takes no arguments: $error = $session->config_clear; Getting a List of Recent Configuration Events This example shows how to use the config_get_history function that uses the optional arguments Maximum, EventType, Reverse, and Detail: $response = $session->config_get_history(EventType => ‘All’, Maximum =>10, Detail => ‘true’); It returns a Response object, on which the method get entries can be called. Getting a List of Recent Configuration Commits That Can Be Rolled Back This example shows how to use the config_get_commitlist function that uses the optional arguments Maximum and Detail: $response = $session->config_get_commitlist (Maximum => 10, Detail => ‘true’); It returns a Response object, on which the method get entries can be called. This returns an array of Entry objects, on which the method get key can be called to retrieve the CommitID, and get data to retrieve the rest of the fields.16-156 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using the Configuration Services Methods Loading Changes Associated with a Set of Commits This example shows how to use the config_load_commit_changes function to load into the target configuration the changes that were made during one or more commits, and it uses one of three possible arguments: ForCommitID, SinceCommitID, or Previous: $error = $session ->config_load_commit_changes (ForCommitID => 1000000072); #Loads the changes that were made in commit 1000000072 $error = $session ->config_load_commit_changes (SinceCommitID => 1000000072); #Loads the changes made in commits 1000000072, 1000000073...up to latest $error = $session ->config_load_commit_changes (Previous => 4); #Loads the changes made in the last 4 commits Rolling Back to a Previous Configuration This example shows how to use the config_rollback() function that uses the optional arguments Label and Comment, and exactly one of the two arguments CommitID or Previous or takes only TrialConfiguration: $error = $session->config_rollback(Label => ‘Rollback test’, CommitID => 1000000072); Loading Changes Associated with Rolling Back Configuration This example shows how to use the config_load_rollback_changes function to load into the target configuration the changes that would be made if you were to roll back one or more commits. The function uses one of three arguments: ForCommitID, ToCommitID and Previous. For example: $error = $session->config_load_rollback_changes (ForCommitID => 1000000072) # Loads the changes that would be made to rollback commit 1000000072 $error = $session->config_load_rollback_changes (ToCommitID => 1000000072); # Loads the changes that would be made to rollback all commits up to and including commit 1000000072 Getting a List of Current Configuration Sessions This example shows how to use the config_get_sessions function that uses the optional argument Detail to return detailed information about configuration sessions. For example: $response = $session->config_get_sessions (Detail => ‘true’); It returns a response object in which the method get_entries can be called. This returns an array of entry objects in which the method get_key can be called to retrieve the session ID, and get_data method to retrieve the rest of the fields. Clearing Configuration Session This example shows how to use config_clear_session function that accepts a configuration session ID SessionID as argument and clears that configuration session: $error=$session->config_clear_sessions (SessionID => ‘00000000-000a00c9-00000000’);Sending a Command-Line Interface Configuration Command This example shows how to use the config_cli() function, which takes a string argument containing the CLI format configuration that you want to apply to the router: $response = $session->config_cli($cli_command); To retrieve the textual CLI response from the response object returned, use the get_cli_response() method, as shown in this example: $response_text = $response->get_cli_response();16-157 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using the Cisco IOS XR Perl Data Object Interface Note Apart from the config_commit, config_get_history, config_get_commitlist, config_get_sessions and config_cli methods, each of the other methods return a reference to an error object if an error occurs or is undefined. For more information, see the “Using the Error Objects” section on page 16-154. Using the Cisco IOS XR Perl Data Object Interface Instead of having to specify the XML requests explicitly, the interface allows access to management data using a Perl notation. The Data Object interface is a Perl representation of the management data hierarchy stored on the router. It consists of objects of type Cisco::IOS_XR::Data, which corresponds to items in the IOS_XR management data hierarchy, and a set of methods for performing data operations on them. To use the Data Object interface, knowledge of the underlying management data hierarchy is required. The management data on an Cisco IOS XR router are under one of six root objects, namely Configuration, Operational, Action, AdminConfiguration, AdminOperational, and AdminAction. The objects that lie below these objects in the hierarchy, along with definitions of any datatypes or filters that are used by them, are documented in the Perl Data Object Documentation. A hash structure is defined to be a scalar (that is, basic) type; for example, string or number, a reference to a hash whose values are hash structures, or a reference to an array whose values are hash structures. This standard Perl data structure corresponds naturally to the structure of management data on an Cisco IOS XR router. This example shows how to use a hash structure: # basic type my $struct1 = ‘john’; # reference to a hash of basic types my $struct2 = {Forename => $struct1, Surname => ‘smith’}; # reference to an array of basic types my $struct3 = (‘dog’, ‘budgie’, ‘cat’); # reference to a hash of references and basic types my $struct4 = {Name => $struct2, Age => ‘30’, Pets => $struct3}; These sections describe how to use the Perl Data Object Documentation: • Understanding the Perl Data Object Documentation, page 16-158 • Generating the Perl Data Object Documentation, page 16-158 • Creating Data Objects, page 16-159 • Specifying the Schema Version to Use When Creating a Data Object, page 16-161 • Using Data Operation Methods on a Data Object, page 16-161 • Using the Batching API, page 16-164 • Displaying Data and Keys Returned by the Data Operation Methods, page 16-165 • Specifying the Session to Use for the Data Operation Methods, page 16-16616-158 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using the Cisco IOS XR Perl Data Object Interface Understanding the Perl Data Object Documentation The Perl Data Object Documentation consists of many files, each containing a subtree of the total management data hierarchy. The main part of each filename tells you the area of management data to which that file refers, and the suffix usually tells you below which root object that file’s data lies. For example, a file containing configuration data usually ends in _cfg.html. Some files may not contain any object definitions, but just some datatypes or filter definitions and usually end in _common.html. For leaf objects, the object definition describes the data that the object contains. For nonleaf objects, the definition provides a list of the object’s children within the tree. More precisely, the object definition consists of these items: • Name of the object. • Brief description of what data is contained in the object or in the subtree below. • List of the required task IDs that are required to access the data in the object and subtree. • List of parent objects and the files in which they are defined, if the object is the top-level object in that file. • If the object is a leaf object (for example, data is contained without child objects), and its name is not unique within that file, parent objects are listed. • If the object is a table entry, a list of the keys that are needed to identify a particular item in that table. For each key, a name, description, and datatype are given. • If the object is a table, a list of the filters that can be applied to that table. • If the object is a leaf object, a list of the value items that are contained. For each value item, a name, description, and datatype are given. • If the object is a leaf object, its default value (for example, the values for each of its value items that would be assumed if the object did not exist), if there is one. • List of the data operation methods, get_data, set_data, and so forth that are applicable to the object. For more information, see the “Specifying the Schema Version to Use When Creating a Data Object” section on page 16-161 Generating the Perl Data Object Documentation The Perl Data Object Documentation must be generated from the schema distribution tar file “All-schemas-CRS-1-”release”.tar.gz”, where “release” is the release of the Cisco IOS XR software that you have installed on the router. To generate the Perl Data Object Documentation: Step 1 From the perl subdirectory under the extracted contents of the previously mentioned Schema tarball, copy all *.dat files into the toolkit installation directory Cisco-IOS_XR-Perl-Scripting-Toolkit-”version”/dat (default) or a selected directory for the .dat files. These .dat files are the XML files that are used to generate the HTML documentation. Step 2 From the perl subdirectory under the extracted contents of the previously mentioned Schema tarball, copy all the *.html files into the toolkit installation directory Cisco-IOS_XR-Perl-Scripting-Toolkit-”version”/html(default) or a selected directory for the .html. (The default .html subdirectory already contains two files that were extracted with the toolkit distribution: root_objects.html and common_datatypes.html. These files are automatically copied to the selected .html directory, if a non-default directory is selected, upon performing this step).16-159 Cisco IOS XR XML API Guide OL-24657-01 Chapter 16 Cisco IOS XR Perl Scripting Toolkit Using the Cisco IOS XR Perl Data Object Interface Step 3 Run the script generate_html_documentation.pl, which is available in the distribution Cisco-IOS_XR-Perl-Scripting-Toolkit-”version”/scripts directory, giving the appropriate directories for the .dat and .html files, when prompted. Step 4 If the script fails, indicating any error .dat files, evaluate the .dat file to confirm that it is not of “0” size and that it has a header as in this example: