Juniper networks JUNOS OS 10.3 LN1000 User Manual

JUNOS

Junos XML Management Protocol Guide

Release

10.3

Published: 2010-06-30

Juniper Networks, Inc. 1194 North Mathilda Avenue Sunnyvale, California 94089 USA 408-745-2000 www.juniper.net

This productincludes the Envoy SNMPEngine, developed by Epilogue Technology, an IntegratedSystemsCompany.Copyright ©1986-1997, Epilogue Technology Corporation. All rights reserved. This program and its documentation were developed at private expense, and no part of them is in the public domain.

This product includes FreeBSD software developed by the University of California, Berkeley, and its contributors. All of the documentation and software included in the 4.4BSD and 4.4BSD-Lite Releases is copyrighted by the Regents of the University of California. Copyright © 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994. The Regents of the University of California. All rights reserved.

GateD software copyright © 1995, the Regents of the University. All rights reserved. Gate Daemon was originated and developed through release 3.0 by Cornell University and its collaborators. Gated is based on Kirton’s EGP, UC Berkeley’s routing daemon (routed), and DCN’s HELLO routing protocol. Development of Gated has been supported in part by the National Science Foundation. Portions of the GateD software copyright © 1988, Regents of the University of California. All rights reserved. Portions of the GateD software copyright © 1991, D. L. S. Associates.

Juniper Networks, Junos, Steel-Belted Radius, NetScreen, and ScreenOS are registered trademarks of Juniper Networks, Inc. in the United States and other countries. The Juniper Networks Logo, the Junos logo, and JunosE are trademarks of Juniper Networks, Inc. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.

Juniper Networks assumes no responsibility for any inaccuracies in this document. Juniper Networks reserves the right to change, modify, transfer, or otherwise revise this publication without notice.

Products made or sold by Juniper Networks or components thereof might be covered by one or more of the following patents that are owned by or licensed to Juniper Networks: U.S. Patent Nos. 5,473,599, 5,905,725, 5,909,440, 6,192,051, 6,333,650, 6,359,479, 6,406,312, 6,429,706, 6,459,579, 6,493,347, 6,538,518, 6,538,899, 6,552,918, 6,567,902, 6,578,186, and 6,590,785.

JUNOS®OS Junos XML Management Protocol Guide

Writing: Tony Mauro, Michael Scruggs, Brenda Wilden Editing: Stella Hackell, Nancy Kurahashi, Sonia Saruba, Laura Singer Illustration: Faith Bradford Cover Design: Edmonds Design

Revision History July 2010—R1 Junos 10.3

The information in this document is current as of the date listed in the revision history.

YEAR 2000 NOTICE

Juniper Networks hardware and software products are Year 2000 compliant. The Junos OS has no known time-related limitations through the year 2038. However, the NTP application is known to have some difficulty in the year 2036.

END USER LICENSE AGREEMENT

READ THIS END USER LICENSE AGREEMENT (“AGREEMENT”) BEFORE DOWNLOADING, INSTALLING, OR USING THE SOFTWARE.

BY DOWNLOADING, INSTALLING, OR USING THE SOFTWARE OR OTHERWISE EXPRESSING YOUR AGREEMENT TO THE TERMS CONTAINED HEREIN, YOU (AS CUSTOMER OR IF YOU ARE NOT THE CUSTOMER, AS A REPRESENTATIVE/AGENT AUTHORIZED TO BIND THE CUSTOMER) CONSENT TOBE BOUND BYTHIS AGREEMENT. IF YOU DO NOT OR CANNOT AGREE TOTHE TERMS CONTAINED HEREIN, THEN (A) DO NOT DOWNLOAD, INSTALL, OR USE THE SOFTWARE, AND (B) YOU MAY CONTACT JUNIPER NETWORKS REGARDING LICENSE TERMS.

1. The Parties. The parties to this Agreement are (i) Juniper Networks, Inc. (if the Customer’s principal office is located in the Americas) or Juniper Networks (Cayman) Limited (ifthe Customer’sprincipal officeis locatedoutside the Americas) (suchapplicable entitybeing referred to herein as“Juniper”), and(ii) the personor organization thatoriginally purchased fromJuniper or an authorized Juniper reseller theapplicable license(s) for use of the Software (“Customer”) (collectively, the “Parties”).

2. The Software. In this Agreement, “Software” means the program modules and features of the Juniper or Juniper-supplied software, for which Customer has paid the applicable license or support fees to Juniper or an authorized Juniper reseller, or which was embedded by Juniper in equipment which Customer purchased from Juniper or an authorized Juniper reseller. “Software” also includes updates, upgrades and new releases of such software. “Embedded Software” means Software which Juniper has embedded in or loaded onto the Juniper equipment and any updates, upgrades, additions or replacements which are subsequently embedded in or loaded onto the equipment.

3. License Grant. Subject to payment of the applicable fees and the limitations and restrictions set forth herein, Juniper grants to Customer a non-exclusive and non-transferable license, without right to sublicense, to use the Software, in executable form only, subject to the following use restrictions:

a. Customer shall use Embedded Software solely as embedded in, and for execution on, Juniper equipment originally purchased by Customer from Juniper or an authorized Juniper reseller.

b. Customer shall use the Software on a single hardware chassis having a single processing unit, or as many chassis or processing units for which Customer has paid the applicable license fees; provided, however, with respect to the Steel-Belted Radius or Odyssey Access Client software only, Customer shall use such Software on a single computer containing a single physical random access memory space and containing any number of processors. Use of the Steel-Belted Radius or IMS AAA software on multiple computers or virtual machines (e.g., Solaris zones) requires multiple licenses, regardless of whether such computers or virtualizations are physically contained on a single chassis.

c. Product purchase documents, paper or electronic user documentation, and/or the particular licenses purchased by Customer may specify limitsto Customer’s useof theSoftware.Such limitsmay restrict useto a maximumnumber ofseats, registeredendpoints, concurrent users, sessions, calls, connections, subscribers, clusters, nodes, realms, devices, links, ports or transactions, or require the purchase of separate licenses to use particular features, functionalities, services, applications, operations, or capabilities, or provide throughput, performance, configuration, bandwidth, interface, processing, temporal, or geographical limits. In addition, such limits may restrict the use of the Software to managing certain kinds of networks or require the Software to be used only in conjunction with other specific Software. Customer’s use of the Software shall be subject to all such limitations and purchase of all applicable licenses.

d. For any trial copy of the Software, Customer’s right to use the Software expires 30 days after download, installation or use of the Software. Customer may operate the Software after the 30-day trial period only if Customer pays for a license to do so. Customer may not extend or create an additional trial period by re-installing the Software after the 30-day trial period.

e. The Global Enterprise Edition of the Steel-Belted Radius software may be used by Customer only to manage access to Customer’s enterprise network. Specifically, service provider customers are expressly prohibited from using the Global Enterprise Edition of the Steel-Belted Radius software to support any commercial network access services.

The foregoing license is not transferable or assignable by Customer. No license is granted herein to any user who did not originally purchase the applicable license(s) for the Software from Juniper or an authorized Juniper reseller.

4. Use Prohibitions. Notwithstanding the foregoing, the license provided herein does not permit the Customer to, and Customer agrees not to and shall not: (a) modify, unbundle, reverse engineer, or create derivative works based on the Software; (b) make unauthorized copies of the Software (except as necessary for backup purposes); (c) rent, sell, transfer, or grant any rights in and to any copy of the Software,in any form, toany third party; (d) remove anyproprietary notices, labels, or marks on orin any copy of the Softwareor any product in which the Software is embedded; (e) distribute any copy of the Software to any third party, including as may be embedded in Juniper equipment sold inthe secondhand market;(f) use any‘locked’ orkey-restrictedfeature, function, service,application, operation,or capability without first purchasing the applicable license(s) and obtaining a valid key from Juniper, even if such feature, function, service, application, operation, or capability is enabled without a key; (g) distribute any key for the Software provided by Juniper to any third party; (h) use the

Software in any manner that extends or is broader than the uses purchased by Customer from Juniper or an authorized Juniper reseller; (i) use Embedded Software on non-Juniper equipment; (j) use Embedded Software (or make it available for use) on Juniper equipment that the Customer did not originally purchase from Juniper or an authorized Juniper reseller; (k) disclose the results of testing or benchmarking of the Software to any third party without the prior written consent of Juniper;or (l) use the Software in any mannerother than as expressly provided herein.

5. Audit. Customer shall maintain accurate records as necessary to verify compliance with this Agreement. Upon request by Juniper, Customer shall furnish such records to Juniper and certify its compliance with this Agreement.

6. Confidentiality. The Parties agree that aspects of the Software and associated documentation are the confidential property of Juniper. As such, Customer shall exercise allreasonable commercial efforts to maintain the Software and associated documentation inconfidence, which at a minimum includes restricting access to the Software to Customer employees and contractors having a need to use the Software for Customer’s internal business purposes.

7. Ownership. Juniper and Juniper’s licensors, respectively, retain ownership of all right, title, and interest (including copyright) in and to the Software, associated documentation, and all copies of the Software. Nothing in this Agreement constitutes a transfer or conveyance of any right, title, or interest in the Software or associated documentation, or a sale of the Software, associated documentation, or copies of the Software.

8. Warranty, Limitation of Liability, Disclaimer of Warranty. The warranty applicable to the Software shall be as set forth in the warranty statementthat accompanies theSoftware (the“Warranty Statement”). Nothingin thisAgreement shall giverise to anyobligation to support the Software. Support services may be purchased separately. Any such support shall be governed by a separate, written support services agreement. TO THE MAXIMUM EXTENT PERMITTED BY LAW, JUNIPER SHALL NOT BE LIABLE FOR ANY LOST PROFITS, LOSS OF DATA, OR COSTSOR PROCUREMENTOF SUBSTITUTEGOODS ORSERVICES,OR FOR ANYSPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUTOF THIS AGREEMENT,THE SOFTWARE,OR ANYJUNIPER OR JUNIPER-SUPPLIEDSOFTWARE. INNO EVENTSHALL JUNIPER BE LIABLE FOR DAMAGES ARISING FROM UNAUTHORIZED OR IMPROPER USE OF ANY JUNIPER OR JUNIPER-SUPPLIED SOFTWARE. EXCEPT AS EXPRESSLY PROVIDED IN THE WARRANTY STATEMENT TO THE EXTENT PERMITTED BY LAW, JUNIPER DISCLAIMS ANY AND ALL WARRANTIES IN AND TO THE SOFTWARE (WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE), INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT DOES JUNIPER WARRANT THAT THE SOFTWARE, OR ANY EQUIPMENT OR NETWORK RUNNING THE SOFTWARE, WILL OPERATE WITHOUT ERROR OR INTERRUPTION, OR WILL BE FREE OF VULNERABILITY TO INTRUSION OR ATTACK. In no event shall Juniper’s or its suppliers’ or licensors’ liability to Customer, whether in contract, tort (including negligence), breach of warranty, or otherwise, exceed the price paid by Customer for the Software that gave rise to the claim, or if the Software is embedded in another Juniper product, the price paid by Customer for such other product. Customer acknowledges and agrees that Juniper has set its prices and entered into this Agreement in reliance upon the disclaimers of warranty and the limitations of liability set forth herein, that the same reflect an allocation of risk between the Parties (including the risk that a contract remedy may fail of its essential purpose and cause consequential loss), and that the same form an essential basis of the bargain between the Parties.

9. Termination. Any breach of this Agreement or failure by Customer to pay any applicable fees due shall result in automatic termination of the license granted herein. Upon such termination, Customer shall destroy or return to Juniper all copies of the Software and related documentation in Customer’s possession or control.

10. Taxes. All license fees payable under this agreement are exclusive of tax. Customer shall be responsible for paying Taxes arising from the purchase of the license, or importation or use of the Software. If applicable, valid exemption documentation for each taxing jurisdiction shall be provided to Juniper prior to invoicing, and Customer shall promptly notify Juniper if their exemption is revoked or modified. All payments made by Customer shall be net of any applicable withholding tax. Customer will provide reasonable assistance to Juniper in connection with such withholding taxes by promptly: providing Juniper with valid tax receipts and other required documentation showing Customer’s payment of any withholding taxes; completing appropriate applications that would reduce the amount of withholding tax to be paid; and notifying and assisting Juniper in any audit or tax proceeding related to transactions hereunder. Customer shall comply with all applicable tax laws and regulations, and Customer will promptly pay or reimburse Juniper for all costs and damages related to any liability incurred by Juniper as a result of Customer’s non-compliance or delay with its responsibilities herein. Customer’s obligations under this Section shall survive termination or expiration of this Agreement.

11. Export. Customer agrees to comply with all applicable export laws and restrictions and regulations of any United States and any applicable foreign agency or authority, and not to export or re-export the Software or any direct product thereof in violation of any such restrictions, laws or regulations, or without all necessary approvals. Customer shall be liable for any such violations. The version of the Software supplied to Customer may contain encryption or other capabilities restricting Customer’s ability to export the Software without an export license.

12. Commercial Computer Software. The Software is “commercial computer software” and is provided with restricted rights. Use, duplication, or disclosure by the United States government is subject to restrictions set forth in this Agreement and as provided in DFARS

227.7201 through 227.7202-4, FAR 12.212, FAR 27.405(b)(2), FAR 52.227-19, or FAR 52.227-14(ALT III) as applicable.

13. Interface Information. To the extent required by applicable law, and at Customer's written request, Juniper shall provide Customer with the interface information needed to achieve interoperability between the Software and another independently created program, on payment of applicable fee, if any. Customer shallobserve strict obligations of confidentiality with respect to such information and shall use such information in compliance with any applicable terms and conditions upon which Juniper makes such information available.

14. Third Party Software. Any licensor of Juniper whose software is embedded in the Software and any supplierof Juniper whose products or technology are embedded in (or services are accessed by) the Software shall be a third party beneficiary with respect to this Agreement, and such licensor or vendor shall have the right to enforcethis Agreement in its own name as if it were Juniper. In addition, certain third party software may be provided with the Software and is subject to the accompanying license(s), if any, of its respective owner(s). To the extent portions of the Software are distributed under and subject to open source licenses obligating Juniper to make the source code for such portions publicly available (such as the GNU General Public License (“GPL”) or the GNU Library General Public License (“LGPL”)), Juniper will make such source code portions (including Juniper modifications, as appropriate) available upon request for a period of up to three years from the date of distribution. Such request can be made in writing to Juniper Networks, Inc., 1194 N. Mathilda Ave., Sunnyvale, CA 94089, ATTN: General Counsel. You may obtain a copy of the GPL at http://www.gnu.org/licenses/gpl.html, and a copy of the LGPL

at http://www.gnu.org/licenses/lgpl.html .

15. Miscellaneous. This Agreement shall be governed by the laws of the State of California without reference to its conflicts of laws principles. The provisions of the U.N. Convention for the International Sale of Goods shall not apply to this Agreement. For any disputes arising under this Agreement, the Parties hereby consent to the personal and exclusive jurisdiction of, and venue in, the state and federal courts within Santa Clara County, California. This Agreement constitutes the entire and sole agreement between Juniper and the Customer with respect to the Software, and supersedes all prior and contemporaneous agreements relating to the Software, whether oral or written (including any inconsistent terms contained in a purchase order), except that the terms of a separate written agreement executed by an authorized Juniper representative and Customer shall govern to the extent such terms are inconsistent or conflict with terms contained herein. No modification to this Agreement nor any waiver of any rights hereunder shall be effective unless expressly assented to in writing by the party to be charged. If any portion of this Agreement is held invalid, the Parties agree that such invalidity shall not affect the validity of the remainder of this Agreement. This Agreement and associated documentation has been written in the English language, and the Parties agree that the English version will govern. (For Canada: Les parties aux présentés confirment leur volonté que cette convention de même que tous les documents y compris tout avis qui s'y rattaché, soient redigés en langue anglaise. (Translation: The parties confirm that this Agreement and all related documentation is and will be in the English language)).

Abbreviated Table of Contents

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Part 1 Overview

Chapter 1 Introduction to the Junos XML Management Protocol and Junos XML

API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2 Using Junos XML Management Protocol and Junos XML Tag Elements . . . 9

Part 2 Using the Junos XML Management Protocol

Chapter 3 Controlling the Junos XML Management Protocol Session . . . . . . . . . . . . . 25

Chapter 4 Requesting Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Chapter 5 Changing Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 6 Committing a Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Chapter 7 Summary of Junos XML Protocol Tag Elements . . . . . . . . . . . . . . . . . . . . . . 149

Chapter 8 Summary of Attributes in Junos XML Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Part 3 Writing Junos XML Protocol Client Applications

Chapter 9 Writing Junos XML Protocol Perl Client Applications . . . . . . . . . . . . . . . . . 205

Chapter 10 Writing Junos XML Protocol C Client Applications . . . . . . . . . . . . . . . . . . . . 233

Part 4 Index

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Index of Statements and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Junos 10.3 Junos XML Management Protocol Guide

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Junos Documentation and Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Using the Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Requesting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Self-Help Online Tools and Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Opening a Case with JTAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii

Part 1 Overview

Chapter 1 Introduction to the Junos XML Management Protocol and Junos XML

API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Junos XML Management Protocol and Junos XML API Overview . . . . . . . . . . . . . . 3

XML Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Junos XML and Junos XML Management Protocol Tag Elements . . . . . . . . . . 4

Document Type Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Advantages of Using the Junos XML Management Protocol and Junos XML

API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Overview of a Junos XML Protocol Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2 Using Junos XML Management Protocol and Junos XML Tag Elements . . . 9

XML and Junos XML Management Protocol Conventions Overview . . . . . . . . . . . . 9

Request and Response Tag Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Child Tag Elements of a Request Tag Element . . . . . . . . . . . . . . . . . . . . . . . . 10

Child Tag Elements of a Response Tag Element . . . . . . . . . . . . . . . . . . . . . . . . 11

Spaces, Newline Characters, and Other White Space . . . . . . . . . . . . . . . . . . . 11

XML Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

XML Processing Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Predefined Entity References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Mapping Commands to Junos XML Tag Elements . . . . . . . . . . . . . . . . . . . . . . . . . 14

Mapping for Command Options with Variable Values . . . . . . . . . . . . . . . . . . . 14

Mapping for Fixed-Form Command Options . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Mapping Configuration Statements to Junos XML Tag Elements . . . . . . . . . . . . . . 15

Mapping for Hierarchy Levels and Container Statements . . . . . . . . . . . . . . . . 15

Mapping for Objects That Have an Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Mapping for Single-Value and Fixed-Form Leaf Statements . . . . . . . . . . . . . . 17

Mapping for Leaf Statements with Multiple Values . . . . . . . . . . . . . . . . . . . . . 18

Junos 10.3 Junos XML Management Protocol Guide

Mapping for Multiple Options on One or More Lines . . . . . . . . . . . . . . . . . . . . 19

Mapping for Comments About Configuration Statements . . . . . . . . . . . . . . . 20

Using the Same Configuration Tag Elements in Requests and Responses . . . . . . 21

Part 2 Using the Junos XML Management Protocol

Chapter 3 Controlling the Junos XML Management Protocol Session . . . . . . . . . . . . . 25

Client Application’s Role in a Junos XML Protocol Session . . . . . . . . . . . . . . . . . . 25

Establishing a Junos XML Management Protocol Session . . . . . . . . . . . . . . . . . . . 26

Supported Access Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Prerequisites for Establishing a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Prerequisites for All Access Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Prerequisites for Clear-Text Connections . . . . . . . . . . . . . . . . . . . . . . . . . 29

Prerequisites for SSH Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Prerequisites for Outbound SSH Connections . . . . . . . . . . . . . . . . . . . . . 31

Prerequisites for SSL Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Prerequisites for Telnet Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Connecting to the Junos XML Protocol Server . . . . . . . . . . . . . . . . . . . . . . . . . 37

Connecting to the Junos XML Protocol Server from the Client

Connecting to the Junos XML Protocol Server from the CLI . . . . . . . . . . 38

Starting the Junos XML Protocol Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Emitting the Initialization PI and Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Parsing the Initialization PI and Tag from the Junos XML Protocol

Verifying Software Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Supported Software Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Authenticating with the Junos XML Protocol Server . . . . . . . . . . . . . . . . . . . . 43

Submitting an Authentication Request . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Interpreting the Authentication Response . . . . . . . . . . . . . . . . . . . . . . . . 45

Exchanging Information with the Junos XML Protocol Server . . . . . . . . . . . . . . . . 45

Sending a Request to the Junos XML Protocol Server . . . . . . . . . . . . . . . . . . 46

Request Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Including Attributes in the Opening <rpc> Tag . . . . . . . . . . . . . . . . . . . . 48

Parsing the Junos XML Protocol Server Response . . . . . . . . . . . . . . . . . . . . . 48

xmlns:junos Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Junos XML Protocol Server Response Classes . . . . . . . . . . . . . . . . . . . . . 49

Using a Standard API to Parse Response Tag Elements . . . . . . . . . . . . . 50

Handling an Error or Warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Halting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Locking and Unlocking the Candidate Configuration or Creating a Private

Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Locking the Candidate Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Unlocking the Candidate Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Creating a Private Copy of the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Ending a Junos XML Protocol Session and Closing the Connection . . . . . . . . . . . 55

Displaying CLI Output as XML Tag Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Table of Contents

Example of a Junos XML Protocol Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Exchanging Initialization PIs and Tag Elements . . . . . . . . . . . . . . . . . . . . . . . . 57

Sending an Operational Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Locking the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Changing the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Committing the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Unlocking the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Closing the Junos XML Protocol Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 4 Requesting Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Overview of the Request Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Requesting Operational Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Parsing the <output> Tag Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Requesting Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Specifying the Source and Output Format of Configuration Information . . . . . . . 65

Requesting Information from the Committed or Candidate

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Requesting Output as Formatted ASCII Text or Junos XML Tag

Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Requesting a Change Indicator for Configuration Elements . . . . . . . . . . . . . . 70

Requesting an Indicator for Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Specifying the Output Format for Configuration Groups . . . . . . . . . . . . . . . . 74

Specifying Whether Configuration Groups Are Displayed Separately . . . 75

Displaying the Source Group for Inherited Configuration Elements . . . . . 76

Examples: Specifying Output Format for Configuration Groups . . . . . . . 78

Specifying the Scope of Configuration Information to Return . . . . . . . . . . . . . . . . 81

Requesting the Complete Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Requesting a Hierarchy Level or Container Object Without an Identifier . . . . 82

Requesting All Configuration Objects of a Specified Type . . . . . . . . . . . . . . . 83

Requesting a Specified Number of Configuration Objects . . . . . . . . . . . . . . . 84

Requesting Identifiers Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Requesting One Configuration Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Requesting a Subset of Objects by Using Regular Expressions . . . . . . . . . . . 90

Requesting Multiple Configuration Elements Simultaneously . . . . . . . . . . . . 93

Requesting an XML Schema for the Configuration Hierarchy . . . . . . . . . . . . . . . . 94

Creating the junos.xsd File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Example: Requesting an XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Requesting a Previous (Rollback) Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Comparing Two Previous (Rollback) Configurations . . . . . . . . . . . . . . . . . . . . . . . 99

Requesting the Rescue Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 5 Changing Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Overview of Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Specifying the Source and Format of New Configuration Data . . . . . . . . . . . . . . 105

Providing Configuration Data in a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Providing Configuration Data as a Data Stream . . . . . . . . . . . . . . . . . . . . . . 106

Defining Configuration Data as Formatted ASCII Text or Junos XML Tag

Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Junos 10.3 Junos XML Management Protocol Guide

Replacing the Entire Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Replacing the Configuration with New Data . . . . . . . . . . . . . . . . . . . . . . . . . 108

Rolling Back to a Previous or Rescue Configuration . . . . . . . . . . . . . . . . . . . 109

Creating, Modifying, or Deleting Configuration Elements . . . . . . . . . . . . . . . . . . . 109

Merging Configuration Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Replacing Configuration Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Creating New Configuration Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Replacing Configuration Elements Only If They Have Changed . . . . . . . . . . . 115

Deleting Configuration Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Deleting a Hierarchy Level or Container Object . . . . . . . . . . . . . . . . . . . . 117

Deleting a Configuration Object That Has an Identifier . . . . . . . . . . . . . . 117

Deleting a Single-Value or Fixed-Form Option from a Configuration

Deleting Values from a Multivalue Option of a Configuration Object . . 120

Reordering Elements in Configuration Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Renaming a Configuration Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Changing a Configuration Element’s Activation State . . . . . . . . . . . . . . . . . . . . . . 125

Deactivating a Newly Created Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Deactivating or Reactivating an Existing Element . . . . . . . . . . . . . . . . . . . . . 126

Changing aConfigurationElement’sActivationStateSimultaneously with Other

Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Replacing an Element and Setting Its Activation State . . . . . . . . . . . . . . . . . 128

Using Junos XML Tag Elements for the Replacement Element . . . . . . . 128

Using Formatted ASCII Text for the Replacement Element . . . . . . . . . . 128

Reordering an Element and Setting Its Activation State . . . . . . . . . . . . . . . . 129

Renaming an Object and Setting Its Activation State . . . . . . . . . . . . . . . . . . 129

Example: Replacing an Object and Deactivating It . . . . . . . . . . . . . . . . . . . . 130

Chapter 6 Committing a Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Verifying a Configuration Before Committing It . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Committing the Candidate Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Committing a Private Copy of the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Committing a Configuration at a Specified Time . . . . . . . . . . . . . . . . . . . . . . . . . 136

Committing the Candidate Configuration Only After Confirmation . . . . . . . . . . . 137

Committing and Synchronizing a Configuration on Redundant Control

Planes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Synchronizing the Configuration on Both Routing Engines . . . . . . . . . . . . . . . 141

Example: Synchronizing the Configuration on Both Routing Engines . . 142

Forcing a Synchronized Commit Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Example: Forcing a Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Synchronizing Configurations Simultaneously with Other Operations . . . . . 143

Verifying the Configuration on Both Routing Engines . . . . . . . . . . . . . . . 143

Scheduling Synchronization for a Specified Time . . . . . . . . . . . . . . . . . 144

Synchronizing Configurations but Requiring Confirmation . . . . . . . . . . . 144

Logging a Message About Synchronized Configurations . . . . . . . . . . . . 145

Logging a Message About a Commit Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Chapter 7 Summary of Junos XML Protocol Tag Elements . . . . . . . . . . . . . . . . . . . . . . 149

<abort/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

<abort-acknowledgement/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Table of Contents

<authentication-response> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

<challenge> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

<checksum-information> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

<close-configuration/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

<commit-configuration> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

<commit-results> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

<database-status> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

<database-status-information> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

<end-session/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

<get-checksum-information> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

<get-configuration> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

<junoscript> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

<load-configuration> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

<load-configuration-results> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

<lock-configuration/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

<open-configuration> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

<reason> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

<request-end-session/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

<request-login> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

<routing-engine> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

<rpc> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

<rpc-reply> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

<unlock-configuration/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

<?xml?> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

<xnm:error> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

<xnm:warning> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Chapter 8 Summary of Attributes in Junos XML Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

inactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

junos:changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

junos:changed-localtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

junos:changed-seconds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

junos:commit-localtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

junos:commit-seconds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

junos:commit-user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

junos:group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

junos:key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

junos:position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

junos:total . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

recurse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

xmlns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Junos 10.3 Junos XML Management Protocol Guide

Part 3 Writing Junos XML Protocol Client Applications

Chapter 9 Writing Junos XML Protocol Perl Client Applications . . . . . . . . . . . . . . . . . 205

Overview of the Junos::Device Perl Module and Sample Scripts . . . . . . . . . . . . . 205

Downloading the Junos XML Protocol Perl Client and Prerequisites Package . . 206

Unpacking the Junos XML Protocol Perl Client and Sample Scripts . . . . . . . . . . 207

Installing the Prerequisites Package and the Junos XML Protocol Perl Client . . . 207

Unpacking and Installing the Junos XML Protocol Perl Client Prerequisites

Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Installing the Junos XML Protocol Perl Client . . . . . . . . . . . . . . . . . . . . . . . . 209

Tutorial: Writing Perl Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Import Perl Modules and Declare Constants . . . . . . . . . . . . . . . . . . . . . . . . . 210

Connect to the Junos XML Protocol Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Satisfying Protocol Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Group Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Obtain and Record Parameters Required by the JUNOS::Device

Obtaining Application-Specific Parameters . . . . . . . . . . . . . . . . . . . . . . 215

Converting Disallowed Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Establishing the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Submitting a Request to the Junos XML Protocol Server . . . . . . . . . . . . . . . . 217

Providing Method Options or Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 218

Submitting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Example: Getting an Inventory of Hardware Components . . . . . . . . . . . 221

Example: Loading Configuration Statements . . . . . . . . . . . . . . . . . . . . . 222

Parsing and Formatting the Response from the Junos XML Protocol

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Parsing and Formatting an Operational Response . . . . . . . . . . . . . . . . 226

Parsing and Outputting Configuration Data . . . . . . . . . . . . . . . . . . . . . . 228

Closing the Connection to the Junos XML Protocol Server . . . . . . . . . . . . . . 232

Mapping CLI Commands to Perl Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Chapter 10 Writing Junos XML Protocol C Client Applications . . . . . . . . . . . . . . . . . . . . 233

Establishing a Junos XML Protocol Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Accessing and Editing Device Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Part 4 Index

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Index of Statements and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

List of Tables

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Table 1: Notice Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Table 2: Text and Syntax Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

Part 1 Overview

Chapter 2 Using Junos XML Management Protocol and Junos XML Tag Elements . . . 9

Table 3: Predefined Entity Reference Substitutions for Tag Content Values . . . . . 13

Table 4: Predefined Entity Reference Substitutions for Attribute Values . . . . . . . . 13

Part 2 Using the Junos XML Management Protocol

Chapter 3 Controlling the Junos XML Management Protocol Session . . . . . . . . . . . . . 25

Table 5: Supported Access Protocols and Authentication Mechanisms . . . . . . . . 27

Table 6: Junos XML Protocol version 1.0 PI and Opening Tag . . . . . . . . . . . . . . . . . 43

Chapter 4 Requesting Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Table 7: Regular Expression Operators for the matching Attribute . . . . . . . . . . . . . 91

Junos 10.3 Junos XML Management Protocol Guide

About This Guide

This preface provides the following guidelines for using the JUNOS®OS Junos XML

Management Protocol Guide:

•

Junos Documentation and Release Notes on page xvii

•

Objectives on page xvii

•

Audience on page xviii

•

Supported Platforms on page xix

•

Using the Indexes on page xix

•

Documentation Conventions on page xix

•

Documentation Feedback on page xxi

•

Requesting Technical Support on page xxi

Junos Documentation and Release Notes

For a list of related Junos documentation, see

http://www.juniper.net/techpubs/software/junos/ .

If the information in the latest release notes differs from the information in the documentation, follow the Junos Release Notes.

Objectives

To obtain the most current version of all Juniper Networks®technical documentation,

see the product documentation page on the Juniper Networks website at

http://www.juniper.net/techpubs/.

Juniper Networks supports a technical bookprogram to publish books byJuniper Networks engineers and subject matter experts with book publishers around the world. These books go beyond the technical documentation to explore the nuances of network architecture, deployment, and administration using the Junos operating system (Junos OS) and Juniper Networks devices. In addition, the Juniper Networks Technical Library, published in conjunction with O'Reilly Media, explores improving network security, reliability, and availability using Junos OS configuration techniques. All the books are for sale at technical bookstores and book outlets around the world. The current list can be viewed at http://www.juniper.net/books .

This guide describes how to use the Junos Extensible Markup Language (XML) management protocol and the Junos XML application programming interface (API) to

Junos 10.3 Junos XML Management Protocol Guide

configure or request information from the Junos XML protocol server on a device running Junos OS.

NOTE: For additional informationabout Junos OS—either corrections to or information

that might have been omitted from this guide—see the software release notes at

http://www.juniper.net/.

Audience

This guide is designed for network administrators who are configuring and monitoring a Juniper Networks M Series, MX Series, T Series, EX Series, or J Series router or switch.

This guide is designed for Juniper Networks customers who want to write custom applications for configuring or monitoring a Juniper Networks device that runs the Junos OS. It assumes that you are familiar with basic terminology and concepts of XML, with XML-parsing utilities such as the Document Object Model (DOM) or Simple API for XML (SAX), and with the Junos OS command-line interface (CLI).

To use this guide, you need a broad understanding of networks in general, the Internet in particular, networking principles, and network configuration. You must also be familiar with one or more of the following Internet routing protocols:

•

Border Gateway Protocol (BGP)

•

Distance Vector Multicast Routing Protocol (DVMRP)

•

Intermediate System-to-Intermediate System (IS-IS)

•

Internet Control Message Protocol (ICMP) device discovery

•

Internet Group Management Protocol (IGMP)

•

Multiprotocol Label Switching (MPLS)

•

Open Shortest Path First (OSPF)

•

Protocol-Independent Multicast (PIM)

•

Resource Reservation Protocol (RSVP)

•

Routing Information Protocol (RIP)

•

Simple Network Management Protocol (SNMP)

Personnel operating the equipment must be trained and competent; must not conduct themselves in a careless, willfully negligent, or hostile manner; and must abide by the instructions provided by the documentation.

Supported Platforms

For the features described in this manual, Junos OS currently supports the following platforms:

•

Using the Indexes

This reference contains two indexes: a standard index with topic entries, and an index of tags and attributes.

About This Guide

EX Series

J Series

M Series

MX Series

SRX Series

T Series

Documentation Conventions

Table 1 on page xix defines notice icons used in this guide.

Table 1: Notice Icons

Table 2 on page xx defines the text and syntax conventions used in this guide.

DescriptionMeaningIcon

Indicates important features or instructions.Informational note

Indicates a situation that might result in loss of data or hardware damage.Caution

Alerts you to the risk of personal injury or death.Warning

Alerts you to the risk of personal injury from a laser.Laser warning

Junos 10.3 Junos XML Management Protocol Guide

Table 2: Text and Syntax Conventions

ExamplesDescriptionConvention

Fixed-width text like this

Italic text like this

Plain text like this

Represents text that you type.Bold text like this

Represents output that appears on the terminal screen.

•

Introduces important new terms.

•

Identifies book names.

•

Identifies RFC and Internet draft titles.

Represents variables (options for which you substitute a value) in commands or configuration statements.

Represents names of configuration statements, commands, files, and directories; IP addresses; configuration hierarchy levels; or labels on routing platform components.

To enter configuration mode, type the

configure command:

user@host> configure

user@host> show chassis alarms No alarms currently active

•

A policy term is a named structure that defines match conditions and actions.

•

Junos System Basics Configuration Guide

•

RFC 1997, BGP Communities Attribute

Configure the machine’s domain name:

[edit] root@# set system domain-name

domain-name

•

To configure a stub area, include the

stub statement at the [edit protocols ospf area area-id] hierarchy level.

•

The console portis labeled CONSOLE.

stub <default-metric metric>;Enclose optional keywords or variables.< > (angle brackets)

| (pipe symbol)

# (pound sign)

[ ] (square brackets)

Indention and braces ( { } )

; (semicolon)

J-Web GUI Conventions

Indicates a choice betweenthe mutually exclusivekeywords or variables on either side of the symbol. The set of choices is often enclosed in parentheses for clarity.

same lineas theconfiguration statement to which it applies.

Enclose a variable for which you can substitute one or more values.

Identify a level in the configuration hierarchy.

Identifies a leaf statement at a configuration hierarchy level.

broadcast | multicast

(string1 | string2 | string3)

rsvp { # Required for dynamic MPLS onlyIndicates a comment specified on the

community name members [ community-ids ]

[edit] routing-options {

static {

route default {

nexthop address; retain;

}

Table 2: Text and Syntax Conventions (continued)

Bold text like this

Represents J-Web graphical user interface (GUI) items you click or select.

About This Guide

ExamplesDescriptionConvention

•

In the Logical Interfaces box, select All Interfaces.

•

To cancel the configuration, click

Cancel.

> (bold right angle bracket)

Documentation Feedback

We encourage you to provide feedback, comments, and suggestions so that we can improve the documentation. You can send your comments to

techpubs-comments@juniper.net, or fill out the documentation feedback form at

https://www.juniper.net/cgi-bin/docbugreport/. If you are using e-mail, be sure to include

the following information with your comments:

•

Document or topic name

•

URL or page number

•

Software release version (if applicable)

Requesting Technical Support

Technical productsupport is available through the Juniper NetworksTechnical Assistance Center (JTAC). If you are a customer with an active J-Care or JNASC support contract, or are covered under warranty, and need post-sales technical support, you can access our tools and resources online or open a case with JTAC.

Separates levels in a hierarchy of J-Web selections.

In the configuration editor hierarchy, select Protocols>Ospf.

•

JTAC policies—For a complete understanding of our JTAC procedures and policies, review the JTAC User Guide located at

http://www.juniper.net/us/en/local/pdf/resource-guides/7100059-en.pdf .

•

Product warranties—For product warranty information, visit

http://www.juniper.net/support/warranty/ .

•

JTAC hours of operation—The JTAC centers have resources available 24 hours a day, 7 days a week, 365 days a year.

Self-Help Online Tools and Resources

For quick and easy problem resolution, Juniper Networks has designed an online self-service portal called the Customer Support Center (CSC) that provides you with the following features:

•

Find CSC offerings: http://www.juniper.net/customers/support/

•

Search for known bugs: http://www2.juniper.net/kb/

Junos 10.3 Junos XML Management Protocol Guide

•

Find product documentation: http://www.juniper.net/techpubs/

•

Find solutions and answer questions using our Knowledge Base: http://kb.juniper.net/

•

Download the latest versions of software and review release notes:

http://www.juniper.net/customers/csc/software/

•

Search technical bulletins for relevant hardware and software notifications:

https://www.juniper.net/alerts/

•

Join and participate in the Juniper Networks Community Forum:

http://www.juniper.net/company/communities/

•

Open a case online in the CSC Case Management tool: http://www.juniper.net/cm/

To verifyservice entitlement by product serialnumber,use ourSerial NumberEntitlement (SNE) Tool: https://tools.juniper.net/SerialNumberEntitlementSearch/

Opening a Case with JTAC

You can open a case with JTAC on the Web or by telephone.

•

Use the Case Management tool in the CSC at http://www.juniper.net/cm/ .

•

Call 1-888-314-JTAC (1-888-314-5822 toll-free in the USA, Canada, and Mexico).

For international or direct-dial options in countries without toll-free numbers, see

http://www.juniper.net/support/requesting-support.html .

PART 1

Overview

•

Introduction to the Junos XML Management Protocol and Junos XML API on page 3

•

Using Junos XML Management Protocol and Junos XML Tag Elements on page 9

Junos 10.3 Junos XML Management Protocol Guide

CHAPTER 1

Introduction to the Junos XML Management Protocol and Junos XML API

This chapter discusses the following

•

Junos XML Management Protocol and Junos XML API Overview on page 3

•

XML Overview on page 4

•

Advantages of Using the Junos XML Management Protocol and Junos XML API on page 5

•

Overview of a Junos XML Protocol Session on page 6

Junos XML Management Protocol and Junos XML API Overview

The Junos XML Management Protocol is an XML-based protocol that client applications use to request and change configuration information on routing, switching, and security platforms runningJunos OS.The JunosXML protocol uses anExtensible Markup Language (XML) based data encoding for the configuration data and remote procedure calls. The Junos XML protocol defines basic operations that are equivalent to configuration mode commands in the Junos OS command-line interface (CLI). Applications use the protocol operations to display, edit, and commit configuration statements (among other operations), just as administratorsuse CLI configuration mode commands suchas show,

set, and commit to perform those operations.

The Junos XML API is an XML representation of Junos configuration statements and operational mode commands. Junos XML configuration tag elements are the content to which the Junos XML protocol operations apply. Junos XML operational tag elements are equivalent in function to operational modecommands inthe CLI,which administrators use to retrieve status information for a device. The Junos XML API also includes tag elements that are the counterpart to Junos configuration statements.

Client applications request or change information on a device by encoding the request with tag elements from the Junos XML management protocol and Junos XML API and sending it to the Junos XML protocol server on the device. The Junos XML protocol server is integrated intothe JunosOS and does not appear as aseparateentry inprocess listings. The Junos XML protocol server directs the request to the appropriate software modules within the device, encodes the response in Junos XML and Junos XML protocol tag elements, and returns the result to the client application. For example, to request

Junos 10.3 Junos XML Management Protocol Guide

information about the status of a device’s interfaces, a client application sends the

<get-interface-information> tag elementfrom theJunos XMLAPI. TheJunos XML protocol

server gathers the information from the interface process and returns it in the

<interface-information> tag element.

You can usethe Junos XML managementprotocol and Junos XML API to configure devices running Junos OS or request information about the device configuration or operation. You can write client applications to interact with the Junos XML protocol server, but you can also utilize the Junos XML protocol to build custom end-user interfaces for configuration and information retrieval and display, such as a Web browser-based interface.

XML Overview

XML is a language for defining a set of markers, called tags, that are applied to a data set ordocument todescribe thefunction ofindividual elementsand codifythe hierarchical relationships between them. Tags look much like Hypertext Markup Language (HTML) tags, but XML is actually a metalanguage used to define tags that best suit the kind of data being marked.

For more details about XML, see A Technical Introduction to XML at

http://www.xml.com/pub/a/98/10/guide0.html and the additional reference material at

the http://www.xml.com site. The official XML specification from the World Wide Web Consortium (W3C), Extensible Markup Language (XML) 1.0, is available at

http://www.w3.org/TR/REC-xml.

The following sections discuss Junos XML and Junos XML management protocol tag elements.

•

Junos XML and Junos XML Management Protocol Tag Elements on page 4

•

Document Type Definition on page 5

Junos XML and Junos XML Management Protocol Tag Elements

Items in an XML-compliant document or data set are always enclosed in paired opening and closing tags. XML is stricter in this respect than HTML, which sometimes uses only opening tags. The following examples show paired opening and closing tags enclosing a value:

<interface-state>enabled</interface-state> <input-bytes>25378</input-bytes>

The term tag element refers to a three-part set: opening tag, contents, and closing tag. The content can be an alphanumeric character string as in the preceding examples, or can itself be a container tag element, which contains other tag elements. For simplicity, the term tag is often used interchangeably with tag element or element.

If atag element isempty—has nocontents—it can be represented either as paired opening and closing tags with nothing between them, or as a single tag with a forward slash after the tag name. For example, the notation <snmp-trap-flag/> is equivalent to

<snmp-trap-flag></snmp-trap-flag>.

As the preceding examples show, angle brackets enclose the name of a Junos XML or Junos XMLprotocol tag elementin itsopening and closing tags.This isan XML convention, and the brackets are a required part of the complete tag element name. They are not to be confused with the angle brackets used in JuniperNetworks documentation to indicate optional parts of CLI command strings.

Junos XML and Junos XML protocol tag elements obey the XML convention that the tag element name indicates the kind of information enclosed by the tags. For example, the name of the Junos XML <interface-state> tag element indicates that it contains a description of the current status of an interface on the device, whereas the name of the

<input-bytes> tag elementindicatesthat itscontents specify the number of bytes received.

When discussing tag elements in text, this documentation conventionally uses just the name of the opening tag to represent the complete tag element (opening tag, contents, and closing tag). For example, the documentation refers to the <input-bytes> tag to indicate the entire <input-bytes>number-of-bytes</input-bytes> tag element.

Document Type Definition

An XML-tagged document or data set is structured, because a set of rules specifies the ordering and interrelationships of the items in it. The rules define the contexts in which each tagged item can—and in some cases must—occur. A file called a document type definition, or DTD, lists every tag element that can appear in the document or data set, defines the parent-child relationships between the tags, and specifies other tag characteristics. The same DTD can apply to many XML documents or data sets.

Chapter 1: Introduction to the Junos XML Management Protocol and Junos XML API

Advantages of Using the Junos XML Management Protocol and Junos XML API

The Junos XML management protocol and Junos XML API fully document all options for every supported Junos operational request and all elements in every Junos configuration statement. The tag names clearly indicate the function of an element in an operational request or configuration statement.

The combination of meaningful tag names and the structural rules in a DTD makes it easy to understand the content and structure of an XML-tagged data set or document. Junos XML and Junos XML protocol tag elements make it straightforward for client applications that request information from a device to parse the output and find specific information.

The following example illustrates how the Junos XML API makes it easier to parse device output andextractthe neededinformation. It comparesformattedASCII and XML-tagged versions of output from a device running the Junos OS. The formatted ASCII follows:

Physical interface: fxp0, Enabled, Physical link is Up

Interface index: 4, SNMP ifIndex: 3

The corresponding XML-tagged version is:

<name>fxp0</name> <admin-status>enabled</admin-status> <operational-status>up</operational-status> <index>4</index>

Junos 10.3 Junos XML Management Protocol Guide

<snmp-index>3</snmp-index>

</interface>

When a client application needs to extract a specific value from formatted ASCII output, it must rely on the value’s location, expressed either absolutely or with respect to labels or values in adjacent fields. Suppose that the client application wants to extract the interface index. It can use a regular-expression matching utility to locate specific strings, but one difficulty is that the number of digits in the interface index is not necessarily predictable. The client application cannot simply read a certain number of characters after the Interface index: label, but must instead extract everything between the label and the subsequent label, which is

, SNMP ifIndex

A problem arises if the format or ordering of output changes in a later version of the Junos OS, for example, if a Logical index field is added following the interface index number:

Physical interface: fxp0, Enabled, Physical link is Up

Interface index: 4, Logical index: 12, SNMP ifIndex: 3

An application that extracts the interface index number delimited by the Interface index: and SNMPifIndex labels nowobtains an incorrect result. The application mustbe updated manually to search for the following label instead:

, Logical index

In contrast, the structured nature of XML-tagged output enables a client application to retrieve the interface index by extracting everything within the opening <index> tag and closing </index> tag. The application does not have to rely on an element’s position in the output string, so the Junos XML protocol server can emit the child tag elements in any order within the <interface> tag element. Adding a new <logical-index> tag element in a future release does not affect an application’s ability to locate the <index> tag element and extract its contents.

Tagged output is also easier to transform into different display formats. For instance, you might want to display different amounts of detail about a given device component at different times. When a device returns formatted ASCII output, you haveto design and write special routines and data structures in your display program to extract and store the information needed for a given detail level. In contrast, the inherent structure of XML output is an ideal basis for a display program’s own structures. It is also easy to use the same extraction routine for several levels of detail, simply ignoring the tag elements you do not need when creating a less detailed display.

Overview of a Junos XML Protocol Session

Communicationbetween the Junos XMLprotocolserver anda client application issession based. The two parties explicitly establish a connection before exchanging data and close the connection when they are finished. Each request from the client application and each response from the Junos XML protocol server constitutes a well-formed XML document, because the tag streams obey the structural rules defined in the Junos XML protocoland JunosXML DTDs for thekind ofinformation they encode.Client applications must produce a well-formed XML document for each request by emitting tag elements in the required order and only in the legal contexts.

Chapter 1: Introduction to the Junos XML Management Protocol and Junos XML API

The following list outlines the basic structure of a Junos XML protocol session. For more specific information, see the Junos XML Management Protocol Guide

1. The client application establishes a connection to the Junos XML protocol server

and opens the Junos XML protocol session.

2. The Junos XML protocol server and client application exchange initialization

information, which is used to determine if they are using compatible versions of the Junos OS and the Junos XML management protocol.

3. The client application sends one or more requests to the Junos XML protocol server

and parses its responses.

4. The client application closes the Junos XML protocol session and the connection to

the Junos XML protocol server.

Junos 10.3 Junos XML Management Protocol Guide

+ 252 hidden pages

Juniper networks JUNOS OS 10.3 LN1000 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Abbreviated Table of Contents

Table of Contents

List of Tables

About This Guide

Junos Documentation and Release Notes

Objectives

Audience

Supported Platforms

Using the Indexes

Documentation Conventions

Documentation Feedback

Requesting Technical Support

Self-Help Online Tools and Resources

Opening a Case with JTAC

Junos XML Management Protocol and Junos XML API Overview

XML Overview

Junos XML and Junos XML Management Protocol Tag Elements

Document Type Definition

Advantages of Using the Junos XML Management Protocol and Junos XML API

Overview of a Junos XML Protocol Session