Juniper networks JUNOS OS 10.3 LN1000 User Manual

Download

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

CHAPTER 2

Using Junos XML Management Protocol and Junos XML Tag Elements

This chapter describes the syntactic and notational conventions used by the Junos XML protocolserver and client applications, including the mappings betweenstatements and commands in the Junos OS command-line interface (CLI) and the tag elements in the Junos Extensible Markup Language (XML) application programming interface (API).

For more information about the syntax of CLI commands and configuration statements, see the Junos CLI User Guide. For information about specific configuration statements, see the Junos OS configuration guides. For information about specific operational mode commands, see the Junos OS command references.

This chapter discusses the following topics:

•

XML and Junos XML Management Protocol Conventions Overview on page 9

•

Mapping Commands to Junos XML Tag Elements on page 14

•

Mapping Configuration Statements to Junos XML Tag Elements on page 15

•

Using the Same Configuration Tag Elements in Requests and Responses on page 21

XML and Junos XML Management Protocol Conventions Overview

A client application must comply with XML and Junos XML management protocol conventions. Each request from the client application must be a well-formed XML document; that is, it must obey the structural rules defined in the Junos XML protocol and Junos XML document type definitions (DTDs) for the kind of information encoded in the request. The client application must emit tag elements in the required order and only in legal contexts. Compliant applications are easier to maintain in the event of changes to the Junos OS or Junos XML management protocol.

Similarly, each response from the Junos XML protocol server constitutes a well-formed XML document (the Junos XML protocol server obeys XML and Junos XML management protocol conventions).

The following sections describe Junos XML management protocol conventions:

•

Request and Response Tag Elements on page 10

•

Child Tag Elements of a Request Tag Element on page 10

Junos XML Protocol Server

Client Application

Junos 10.3 Junos XML Management Protocol Guide

•

Child Tag Elements of a Response Tag Element on page 11

•

Spaces, Newline Characters, and Other White Space on page 11

•

XML Comments on page 12

•

XML Processing Instructions on page 12

•

Predefined Entity References on page 12

Request and Response Tag Elements

A request tag element is one generated by a client application to request information about a device’s current status or configuration, or to change the configuration.A request tag element corresponds to a CLI operational or configuration command. It can occur only within an <rpc> tag element. For information about the <rpc> tag element, see “Sending a Request to the Junos XML Protocol Server” on page 46.

A response tag element represents the Junos XML protocol server’s reply to a request tag element and occurs only within an <rpc-reply> tag element. For information about the <rpc-reply> tag element, see “Parsing the Junos XML Protocol Server Response” on page 48.

The following example represents an exchange in which a client application emits the

<get-interface-information> request tag element with the <extensive/> flag and the

Junos XML protocol server returns the <interface-information> response tag element.

NOTE: This example, like all others in this guide, shows each tag element on a separate

line, in the tag streams emitted by both the client application and Junos XML protocol server. In practice, a client application does not need to include newline characters between tag elements, because the server automatically discards such white space. For further discussion, see “Spaces, Newline Characters, and Other White Space” on page 11.

For information about the attributes in the opening rpc-reply tag, see “Parsing the Junos XML Protocol Server Response” on page 48. For information about the xmlns attribute in the opening <interface-information> tag, see “Requesting Operational Information” on page 62.

Child Tag Elements of a Request Tag Element

Some request tag elements contain child tag elements. For configuration requests, each child tag element represents a configuration element (hierarchy level or configuration

Chapter 2: Using Junos XML Management Protocol and Junos XML Tag Elements

object). For operational requests, each child tag element represents one of the options you provide on the command line when issuing the equivalent CLI command.

Some requests have mandatory child tag elements. To make a request successfully, a client application mustemit the mandatory tag elements withinthe requesttag element’s opening and closing tags. If any of the children are themselves container tag elements, the opening tag for each must occur before any of the tag elements it contains, and the closing tag must occur before the opening tag for another tag element at its hierarchy level.

In most cases, the client application canemit children that occur at the same level within a container tag element in any order. The important exception is a configuration element that has an identifier tag element, which distinguishes the configuration element from other elements of its type. The identifier tag element must be the first child tag element in the container tag element. Most frequently, the identifier tag element specifies the name of the configuration element and is called <name>.

Child Tag Elements of a Response Tag Element

The child tag elements of a response tag element represent the individual data items returned by the Junos XML protocol server for a particular request. The children can be either individual tag elements (empty tags or tag element triples) or container tag elements that enclose their own child tag elements. For some container tag elements, the Junos XML protocol server returns the children in alphabetical order. For other elements, the children appear in the order in which they were created in the configuration.

The set of child tag elements that can occur in a response or within a container tag element is subject to change in later releases of the Junos XML API. Client applications must not rely on the presence or absence of a particular tag element in the Junos XML protocol server’s output, nor on the ordering of child tag elements within a response tag element. For the mostrobust operation, include logicin the client applicationthat handles the absence of expected tag elements or the presence of unexpected ones as gracefully as possible.

Spaces, Newline Characters, and Other White Space

As dictated by the XML specification, the Junos XML protocol server ignores white space (spaces, tabs, newline characters, and other characters that represent white space) that occurs between tag elements in the tag stream generated by a client application. Client applications can, but do not need to, includewhite space between tag elements. However, they must not insert white space within an opening or closing tag. If they include white space in the contents of a tag element that they are submitting as a change to the candidate configuration, the Junos XML protocol server preserves the white space in the configuration database.

In itsresponses, the Junos XMLprotocolserver includes whitespace between tag elements to enhance the readability ofresponses that are saved to a file: it uses newline characters to put each tag element on its own line, and spaces to indent child tag elements to the right compared to their parents. A client application can ignoreor discardthe white space, particularly if it does not store responses for later review by human users. However, it

Junos 10.3 Junos XML Management Protocol Guide

must not depend on the presence or absence of white space in any particular location when parsing the tag stream.

For more information about white space in XML documents, see the XML specification from the World Wide Web Consortium (W3C), Extensible Markup Language (XML) 1.0, at http://www.w3.org/TR/REC-xml/ .

XML Comments

Client applications and the Junos XML protocol server can insert XML comments at any point between tag elements in the tag stream theygenerate, but not within tag elements. Client applications musthandle comments in output from the Junos XMLprotocol server gracefully but must not depend on their content. Client applications also cannot use comments to convey information to the Junos XML protocol server, because the server automatically discards any comments it receives.

XML comments areenclosed within the strings ,and cannot contain thestring

- - (two hyphens). For more details about comments, see the XML specification at

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

The following is an example of an XML comment:

<!- -This is a comment. Please ignore it. -->

XML Processing Instructions

An XML processing instruction (PI) contains information relevant to a particular protocol and has the following form:

<?PI-name attributes?>

Some PIs emitted during a Junos XML protocol session include information that a client application needs forcorrect operation. Aprominent example isthe <?xml?> tag element, which the client application and Junos XML protocol server each emit at the beginning of every Junos XML protocolsession tospecify which version of XML and whichcharacter encoding scheme they are using. For more information, see “Emitting the <?xml?> PI” on page 39 and “Parsing the Junos XML Protocol Server’s <?xml?> PI” on page 41.

The Junos XML protocol server canalso emit PIs thatthe client application doesnot need to interpret (for example, PIs intended for the CLI). If the client application does not understand a PI, it must treat the PI like a comment instead of exiting or generating an error message.

Predefined Entity References

By XML convention, there are two contexts in which certain characters cannot appear in their regular form:

•

In the string that appears between opening and closing tags (the contents of the tag element)

•

In the string value assigned to an attribute of an opening tag

When including a disallowed character in either context, client applications must substitute the equivalent predefined entity reference, which is a string of characters that

Chapter 2: Using Junos XML Management Protocol and Junos XML Tag Elements

represents the disallowed character. Because the Junos XML protocol server uses the same predefined entity references in its response tag elements, the client application must be able to convert them to actual characters when processing response tag elements.

Table 3 on page 13 summarizes the mapping between disallowed characters and predefined entity references for strings that appear between the opening and closing tags of a tag element.

Table 3: Predefined Entity ReferenceSubstitutions for Tag Content Values

Predefined Entity ReferenceDisallowed Character

&& (ampersand)

>> (greater-than sign)

<< (less-than sign)

Table 4 on page 13 summarizes the mapping between disallowed characters and predefined entity references for attribute values.

Table 4: Predefined Entity Reference Substitutions for Attribute Values

Predefined Entity ReferenceDisallowed Character

&& (ampersand)

'' (apostrophe)

>>> (greater-than sign)

<< (less-than sign)

"" (quotation mark)

As anexample,suppose thatthe following stringis the value contained bythe <condition> tag element:

if (a<b && b>c) return "Peer’s not responding"

The <condition> tag element looks like this (it appears on two lines for legibility only):

<condition>if (a<b && b>c) return "Peer’s not \

responding"</condition>

Similarly, if the value for the <example> tag element’s heading attribute is

Peer’s "age" <> 40, the opening tag looks like this:

Junos 10.3 Junos XML Management Protocol Guide

Mapping Commands to Junos XML Tag Elements

The Junos XML API defines tag-element equivalents for many commands in CLI operationalmode. For example, the <get-interface-information> tag elementcorresponds to the show interfaces command.

Information about the available command equivalents in the current releaseof the Junos OS can be found in the Junos XML API Operational Reference. For the mapping between commands and Junos XML tag elements, see the Junos XML API Operational Reference “Mapping Between Operational Tag Elements, PerlMethods, andCLI Commands” chapter. For detailed information about a specific operation, see the Junos XML API Operational Reference “Summary of Operational Request Tags” chapter.

The following sections describe the tag elements that map to command options:

•

Mapping for Command Options with Variable Values on page 14

•

Mapping for Fixed-Form Command Options on page 14

Mapping for Command Options with Variable Values

Many CLI commands have options that identify the object that the command affects or reports about, distinguishing the object from other objects of the same type. In some cases, the CLI does not precede the identifier with a fixed-form keyword, but XML convention requires that the Junos XML API define a tag element for every option. To learn the names for each identifier (and any other child tag elements) for an operational request tag element, consult the tag element’s entry in the appropriate DTD or in the Junos XML API Operational Reference.

The following example shows the Junos XML tag elements for two CLI operational commands that havevariable-formoptions. In the showinterfacescommand, t3-5/1/0:0 is the name of the interface. In the show bgp neighbor command, 10.168.1.222 is the IP address for the BGP peer of interest.

Mapping for Fixed-Form Command Options

Some CLI commands include options that have a fixed form, such as the brief and detail strings, which specify the amount of detail to include in the output. The Junos XML API usually maps such an option to an empty tag whose name matches the option name.

The following example shows the Junos XML tag elements for the show isis adjacency command, which has a fixed-form option called detail.

Chapter 2: Using Junos XML Management Protocol and Junos XML Tag Elements

Mapping Configuration Statements to Junos XML Tag Elements

The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy. At the top levels of the configuration hierarchy, there is almost always a one-to-one mapping between tag elements and statements, and most tag names match the configuration statement name. At deeper levels of the hierarchy, the mapping is sometimes less direct, because some CLI notational conventions do not map directly to XML-compliant tagging syntax.

NOTE: For some configuration statements, the notation used when you type the

statement at the CLI configuration-mode prompt differs from the notation used in a configuration file. The same Junos XML tag element maps to both notational styles.

The following sections describe the mapping between configuration statements and Junos XML tag elements:

•

Mapping for Hierarchy Levels and Container Statements on page 15

•

Mapping for Objects That Have an Identifier on page 16

•

Mapping for Single-Value and Fixed-Form Leaf Statements on page 17

•

Mapping for Leaf Statements with Multiple Values on page 18

•

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

•

Mapping for Comments About Configuration Statements on page 20

Mapping for Hierarchy Levels and Container Statements

The <configuration> tag element is the top-level Junos XML container tag element for configuration statements. It corresponds to the [edit] hierarchy level in CLI configuration mode. Most statementsat the next few levels of the configuration hierarchy are container statements. The Junos XML container tag element that corresponds to a container statement almost always has the same name as the statement.

The following example shows the Junos XML tag elements for two statements at the top level of the configuration hierarchy. Note that a closing brace in a CLI configuration statement corresponds to a closing Junos XML tag.

Junos 10.3 Junos XML Management Protocol Guide

Mapping for Objects That Have an Identifier

At some hierarchy levels, the same kind of configuration object can occur multiple times. Each instance ofthe objecthas aunique identifier to distinguishit fromthe other instances. In the CLI notation, the parent statement for such an object consists of a keyword and identifier of the following form:

keyword identifier { … configuration statements for individual characteristics … }

keyword is a fixed string that indicates the type of object being defined, and identifier is

the unique name for this instance of the type. In the Junos XML API, the tag element corresponding to the keyword is a container tag element for child tag elements that represent the object’s characteristics. The container tag element’s name generally matches the keyword string.

The Junos XML API differs from the CLI in its treatment of the identifier. Because the Junos XMLAPI doesnot allow containertag elements to contain bothother tagelements and untagged character data such as an identifier name, the identifier must be enclosed in a tag element of its own. Most frequently, identifier tag elements for configuration objects are called <name>. Some objects have multiple identifiers, which usually have names other than <name>. To verify the name of each identifier tag element for a configuration object, consult the entry for the object in the Junos XML API Configuration Reference.

NOTE: The Junos OS reservesthe prefixjunos- forthe identifiers of configurationgroups

defined within the junos-defaults configuration group. User-defined identifiers cannot start with the string junos-.

Identifier tag elements also constitute an exception to the general XML convention that tag elements at the same level of hierarchy can appear in any order; the identifier tag element always occurs first within the container tag element.

The configuration for most objects that have identifiers includes additional leaf statements, which represent other characteristics of the object. For example, each BGP group configured at the[edit protocols bgp group] hierarchy level has an associated name (the identifier) and can have leaf statements for other characteristics such as type, peer autonomous system (AS) number, and neighbor address. For information about the

Chapter 2: Using Junos XML Management Protocol and Junos XML Tag Elements

Junos XML mapping for leaf statements, see “Mapping for Single-Value and Fixed-Form Leaf Statements” on page 17, “Mapping for Leaf Statements with Multiple Values” on page 18, and “Mapping for Multiple Options on One or More Lines” on page 19.

The following example shows the Junos XML tag elements for configuration statements that define two BGP groups called G1 and G2. Notice that the Junos XML <name> tag element that encloses the identifier of each group (and the identifier of the neighbor within a group) does not have a counterpart in the CLI statements. For complete information about changing routing platform configuration, see “Changing Configuration Information” on page 103.

Mapping for Single-Value and Fixed-Form Leaf Statements

A leaf statement is a CLI configuration statement that does not contain any other statements. Most leaf statements define a value for one characteristic of a configuration object and have the following form:

keyword value;

In general, the name of the Junos XML tag element corresponding to a leaf statement is the same as the keyword string. The string between the opening and closing Junos XML tags is the same as the value string.

The following example shows the Junos XML tag elements for two leaf statements that have a keyword and a value: the message statement at the [edit system login] hierarchy level and the preference statement at the [edit protocols ospf] hierarchy level.

Junos 10.3 Junos XML Management Protocol Guide

Some leaf statements consist of a fixed-form keyword only, without an associated variable-form value. The Junos XML API represents such statements with an empty tag. The following example shows the Junos XML tag elements for the disable statement at the [edit forwarding-options sampling] hierarchy level.

Mapping for Leaf Statements with Multiple Values

Some Junos leaf statements accept multiple values, which can be either user-defined or drawn from a set of predefined values. CLI notation uses square brackets to enclose all values in a single statement, as in the following:

statement [ value1 value2 value3 ...];

The Junos XML API instead encloses each value in its own tag element. The following example shows the Junos XML tag elements for a CLI statement with multiple user-defined values. Theimport statementimports two routingpolicies definedelsewhere in the configuration. For complete information about changing routing platform configuration, see “Changing Configuration Information” on page 103.

T1508

Chapter 2: Using Junos XML Management Protocol and Junos XML Tag Elements

The following example shows the Junos XML tag elements for a CLI statement with multiple predefined values. The permissions statement grants three predefined permissions to members of the user-accounts login class.

Mapping for Multiple Options on One or More Lines

For some Junos configuration objects, the standard CLI syntax places multiple options on a single line, usually for greater legibility and conciseness. In most such cases, the first option identifies the object and does not have a keyword, but later options are paired keywords and values. The Junos XML API encloses each option in its own tag element. Because the first option has no keyword in the CLI statement, the Junos XML API assigns a name to its tag element.

The following example shows the Junos XML tag elements for a CLI configuration statementwith multiple optionson a single line. The Junos XML API defines a tag element for both options and assigns a name to the tag element for the first option (10.0.0.1), which has no CLI keyword.

The syntax forsome configuration objects includesmore thanone multioptionline. Again, the Junos XML API definesa separate tag element for each option.The following example shows Junos XML tag elements for a traceoptions statement at the [edit protocols isis] hierarchy level. The statement has three child statements, each with multiple options.

Junos 10.3 Junos XML Management Protocol Guide

Mapping for Comments About Configuration Statements

A Junosconfigurationcan include commentsthat describe statements inthe configuration. In CLI configuration mode, the annotate command specifies the comment to associate with a statement at the current hierarchy level. You can also use a text editor to insert comments directly into a configuration file. For more information, see the Junos CLI User Guide.

The Junos XML API encloses comments about configuration statements in the

<junos:comment> tag element. (These comments are different from the comments that

are enclosed in the strings  and are automatically discarded by the protocol server.)

In the Junos XML API, the <junos:comment> tag element immediately precedes the tag element for the associated configuration statement. (If the tag element forthe associated statement is omitted, the comment is not recorded in the configuration database.) The comment text string can include one of the two delimiters that indicate a comment in the configuration database: either the # character before the comment or the paired strings /* before the comment and */ after it. If the client application does not include the delimiter, the protocol server adds the appropriate one when it adds the comment to the configuration. The protocol server also preserves any white space included in the comment.

The following example shows the Junos XML tag elements that associate comments with two statements in a sample configuration statement. The first comment illustrates how including newline characters in the contents of the <junos:comment> tag element (/* New backbone area */) results in the comment appearing on its own line in the configuration file. There are no newline characters in the contents of the second

<junos:comment> tag element, so in the configuration file the comment directly follows

the associated statement on the same line.

Chapter 2: Using Junos XML Management Protocol and Junos XML Tag Elements

Using the Same Configuration Tag Elements in Requests and Responses

The Junos XML protocol server encloses its response to each configuration request in

<rpc-reply> and <configuration> tag elements. Enclosing each configuration response

within a<configuration> tag element contrasts withhow theserver encloses each different operational response in a tag element named for that type of response—for example, the <chassis-inventory> tag elementfor chassis information orthe <interface-information> tag element for interface information.

The Junos XML tag elements within the <configuration> tag element represent configuration hierarchy levels, configuration objects, and object characteristics, always ordered from higher to deeper levels of the hierarchy. When a client application loads a configuration, it can emit the same tag elements in the same order as the Junos XML protocol server uses when returning configuration information. This consistent representation makes handling configuration information more straightforward. For instance, the client application can request the current configuration, store the Junos XML protocol server’s response to a local memory buffer, make changes or apply transformations to the buffered data, and submit the altered configuration as a change to the candidate configuration. Because the altered configuration is based on the Junos XML protocol server’s response, it is certain to be syntactically correct. For more information about changing routing platform configuration, see “Changing Configuration Information” on page 103.

Similarly, when a client application requests information about a configuration element (hierarchy level or configuration object), it uses the same tag elements that the Junos XML protocol server willreturn inresponse. To represent theelement, theclient application sends a complete stream of tag elements from the top of the configuration hierarchy (represented by the <configuration> tag element) down to the requested element. The innermost tag element, which represents the level or object, is either empty or includes the identifier tag element only. The Junos XML protocol server’s response includes the same stream ofparent tag elements, but the tag element forthe requested configuration element contains all the tag elements that represent the element’s characteristics or child levels. Formore information, see “Requesting Configuration Information” onpage 64.

Junos 10.3 Junos XML Management Protocol Guide

The tag streams emitted by the Junos XML protocol server and by a client application can differ in the use of white space, as described in “Spaces, Newline Characters, and Other White Space” on page 11.

PART 2

Using the Junos XML Management Protocol

•

Controlling the Junos XML Management Protocol Session on page 25

•

Requesting Information on page 61

•

Changing Configuration Information on page 103

•

Committing a Configuration on page 133

•

Summary of Junos XML Protocol Tag Elements on page 149

•

Summary of Attributes in Junos XML Tags on page 183

Junos 10.3 Junos XML Management Protocol Guide

CHAPTER 3

Controlling the Junos XML Management Protocol Session

This chapter explains how to start and terminate a session with the Junos XML protocol server, and describes the Extensible Markup Language (XML) tag elements from the Junos XML management protocol that client applications and the Junos XML protocol server use to coordinate information exchange during the session. It discusses the following topics:

•

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

•

Establishing a Junos XML Management Protocol Session on page 26

•

Exchanging Information with the Junos XML Protocol Server on page 45

•

Locking and Unlocking the Candidate Configuration or Creating a Private Copy on page 52

•

Ending a Junos XML Protocol Session and Closing the Connection on page 55

•

Displaying CLI Output as XML Tag Elements on page 56

•

Example of a Junos XML Protocol Session on page 56

Client Application’s Role in a Junos XML Protocol Session

To create a session and communicate with the Junos XML protocol server, a client application performs the following procedures, which are described in the indicated sections:

1. Establishes a connection to the Junos XML protocol server on the routing platform,

as described in “Connecting to the Junos XML Protocol Server” on page 37.

2. Opens aJunos XML protocol session, asdescribed in“Starting theJunos XMLProtocol

Session” on page 38.

3. (Optional) Locks the candidate configuration or creates a private copy, as described

in “Exchanging Information with the Junos XML Protocol Server” on page 45. Locking the configuration prevents other users or applications from changing it at the same time. Creating a private copy of the configuration enables the application to make changes without affecting the candidate or active configuration until the copy is committed.

Junos 10.3 Junos XML Management Protocol Guide

4. Requests operational or configuration information, or changes configuration

information, as described in “Requesting Information” on page 61 and “Changing Configuration Information” on page 103.

5. (Optional) Verifies the syntactic correctness of a configuration before attempting

to commit it, as described in “Verifying a Configuration Before Committing It” on page 133.

6. Commits changes made to the configuration, as described in “Committing a

Configuration” on page 133.

7. Unlocks the candidate configuration if it is locked, as described in “Unlocking the

Candidate Configuration” on page 54.

8. Ends the Junos XML protocol session and closes the connection to the device, as

described in “Ending a Junos XML Protocol Session and Closing the Connection” on page 55.

Establishing a Junos XML Management Protocol Session

The JunosXML protocol servercommunicates with client applications within the context of a Junos XML protocol session. The server and client explicitly establish a connection and session before exchanging data and close the session and connection when they are finished.

The streams of Junos XML protocol tag elements and Junos XML tag elements emitted by the Junos XML protocol server and the client application must each constitute well-formed XML by obeying the structural rulesdefined in the document type definition (DTD) for the kind of information they are exchanging. The client application must emit tag elements in the required order and only in the allowed contexts.

Client applications access theJunos XMLprotocol server usingone of the protocols listed in “Supported Access Protocols” on page27. To authenticate withthe Junos XMLprotocol server, they use either aJunos XML protocol-specific mechanismor the access protocol’s standard authentication mechanism, depending on the protocol. After authentication, the Junos XML protocol server uses the Junos login usernames and classes already configured on the device to determine whether a client application is authorized to make each request.

For information about establishing a connection and a Junos XML protocol session, see the following sections:

•

Supported Access Protocols on page 27

•

Prerequisites for Establishing a Connection on page 27

•

Connecting to the Junos XML Protocol Server on page 37

•

Starting the Junos XML Protocol Session on page 38

•

Authenticating with the Junos XML Protocol Server on page 43

For an example of a complete Junos XML protocol session, see “Example of a Junos XML Protocol Session” on page 56.

Supported Access Protocols

To connect to the Junos XML protocol server, client applications can use the access protocols and associated authentication mechanisms listed in Table 5 on page 27.

Table 5: Supported Access Protocols and Authentication Mechanisms

Chapter 3: Controlling the Junos XML Management Protocol Session

Authentication MechanismAccess Protocol

clear-text, a Junos XML protocol-specific access protocol for sending unencrypted text over a Transmission Control Protocol (TCP) connection

Secure Sockets Layer (SSL)

The SSH and SSL protocols are preferred because they encrypt security information (such as passwords) before transmitting it across the network. Outbound SSH allows you to create an encrypted connection to the device in situations where you cannot connect to the device using standard SSH. The clear-text and Telnet protocols do not encrypt information.

For information about the prerequisites for each access protocol, see “Prerequisites for Establishing aConnection” on page27. For authentication instructions,see “Authenticating with the Junos XML Protocol Server” on page 43.

Prerequisites for Establishing a Connection

Junos XML protocol-specific

Standard SSHSSH

Outbound SSHOutbound SSH

Junos XML protocol-specific

Standard TelnetTelnet

To enable a client application to establish a connection to the Junos XML protocol server, you must satisfy the requirements discussed in the following sections:

•

Prerequisites for All Access Protocols on page 27

•

Prerequisites for Clear-Text Connections on page 29

•

Prerequisites for SSH Connections on page 30

•

Prerequisites for Outbound SSH Connections on page 31

•

Prerequisites for SSL Connections on page 35

•

Prerequisites for Telnet Connections on page 37

Prerequisites for All Access Protocols

A client application must be able to log in to each device on which it establishes a connection with the Junos XML protocol server. The following instructions explain how to create a Junos login account for the application; for detailed information, see the chapter about configuring user access in the Junos System Basics Configuration Guide.

Junos 10.3 Junos XML Management Protocol Guide

Alternatively, you can skip this section and enable authentication through RADIUS or TACACS+; for instructions, see the chapter about system authentication in the Junos System Basics Configuration Guide.

To determine whether a login account exists on a device running Junos OS, enter the CLI configuration mode on the device and issue the following commands:

[edit] user@host# edit system login [edit system login] user@host# show user account-name

If the appropriate account does not exist, perform the following steps:

1. Include the user statement at the [edit system login] hierarchy level and specify a

username. Also include the class statement at the [edit system login user username] hierarchy level, and specify a login class that has the permissions required for all actions to be performed by the application. You can also include the optional

full-name and uid statements. Optionally, include the full-name and uid statements.

[edit system login] user@host# set user account-name class class-name

NOTE: For detailed information about creating user accounts, see the chapter about configuring user access in the Junos System Basics Configuration Guide.

2. Create a text-based password for the account by including either the

plain-text-password or encrypted-password statement at the [edit system login user account-name authentication] hierarchy level.

[edit system login] user@host# edit user account-name authentication

NOTE: A text-based password is not strictly necessary if the account is used to access the Junos XML protocol server through SSH with public/private key pairs for authentication, but we recommend that you create one anyway. The key pair alone is sufficient if the account is used only for SSH access, but a password is required if the account is also used for any other type of access (for login on the console,for example). The password is also used—the SSH server prompts for it—if key-based authentication is configured but fails. For information about creating a public/private key pair, see “Prerequisites for SSH Connections” on page 30.

To enter a password as text, issue the following command. You are prompted for the password, which is encrypted before being stored.

[edit system login user account-name authentication] user@host# set plain-text-password New password: password Retype new password: password

Chapter 3: Controlling the Junos XML Management Protocol Session

To store a password that you have previously created and hashed using Message Digest 5 (MD5) or Secure Hash Algorithm 1 (SHA-1), issue the following command:

[edit system login user account-name authentication] user@host# set encrypted-password "password"

Issue the commit command.

[edit system login user account-name authentication] user@host# top [edit] user@host# commit

4. Repeat the preceding steps on each device where the client application establishes

Junos XML protocol sessions.

5. Enable the client application to access the password and provide it when the Junos

XML protocol server prompts for it. There are several possible methods, including the following:

•

Code the application to prompt the user for a password at startup and to store the password temporarily in a secure manner.

•

Store the password in encrypted form in a secure local-disk location or secured database and code the application to access it.

Prerequisites for Clear-Text Connections

A client application that uses the Junos XML protocol-specific clear-text access protocol sends unencrypted text directly over a TCP connection without using any additional protocol (such as SSH, SSL, or Telnet).

NOTE: Devices running the Junos-FIPS software do not accept Junos XML protocol

clear-text connections. We recommend that you do not use the clear-text protocol in a Common Criteria environment. For more information, see the Secure Configuration Guide for Common Criteria and Junos-FIPS.

To enable client applications to use the clear-text protocol to connect to the Junos XML protocol server, perform the following steps:

1. Verifythat theapplication can access the TCP software. On most operating systems,

TCP is accessible in the standard distribution. Do this on each computer where the application runs.

2. Satisfy the prerequisites discussed in “Prerequisites for All Access Protocols” on

page 27.

3. Configure the device running Junos OS to accept clear-text connections from client

applications on port 3221 by including the xnm-clear-text statement at the [edit

system services] hierarchy level:

[edit] user@host# set system services xnm-clear-text

Junos 10.3 Junos XML Management Protocol Guide

By default, the Junos XML protocol server supports up to 75 simultaneous clear-text sessions and 150 connection attempts per minute. Optionally, you caninclude either or both the connection-limit statement to limit the number of concurrent sessions and the rate-limit statement to limit the number of connection attempts. Both statements accept a value from 1 through 250.

[edit] user@host# set system services xnm-clear-text connection-limit limit user@host# set system services xnm-clear-text rate-limit limit

For more information about the xnm-clear-text statement, see the Junos System Basics Configuration Guide.

4. Commit the configuration:

[edit] user@host# commit

5. Repeat Step 2 through Step 4on eachdevice wherethe clientapplication establishes

Junos XML protocol sessions.

Prerequisites for SSH Connections

To enable a client application to use the SSH protocol to connect to the Junos XML protocol server, perform the following steps:

1. Enable the application to access the SSH software.

If the application uses the Junos XML protocol Perl module provided by Juniper Networks, no action is necessary. As part of the installation procedure for the Perl module, you installa prerequisites package that includes the necessary SSHsoftware. For instructions, see “Downloading the Junos XML Protocol Perl Client and Prerequisites Package” on page 206.

If the application does not use the Junos XML protocol Perl module, obtain the SSH software and install it on the computer where the application runs. For information about obtaining and installing SSH software, see http://www.ssh.com/ and

http://www.openssh.com/ .

2. Satisfy the prerequisites discussed in “Prerequisites for All Access Protocols” on

page 27.

3. (Optional) If you want to use key-based SSH authentication for the application,

create a public/private key pair and associate it with the Junos OS login account you created in “Prerequisites for All Access Protocols” on page 27. Perform the following steps:

a. Working onthe computer where theclient application runs,issue thessh-keygen

command in a standard command shell (not the Junos OS CLI). By providing the appropriate arguments, youencode thepublic key witheither RSA (supported by SSH versions 1 and 2) or the Digital Signature Algorithm (DSA), supported by SSH version 2. Formore information, see the man page provided by your SSH vendor for the ssh-keygen command. TheJunos OSuses SSHversion 2by default but also supports version 1.

% ssh-keygen options

Chapter 3: Controlling the Junos XML Management Protocol Session

b. Enable the application to access the public and private keys. One method is to

run the ssh-agent program on the computer where the application runs.

c. On the device running Junos OS that needs to accept SSH connections from

Junos XML protocol client applications, associate the public key with the Junos login account by including the load-key-file statement at the [edit system login

user account-name authentication] hierarchy level. First, move to that hierarchy

level:

[edit] user@host# edit system login user account-name authentication

Issue the following command to copy the contents of the specified file onto the device running Junos OS:

[edit system login user account-name authentication] user@host# set load-key-file URL

URL is the path to the file that contains one or more public keys. The ssh-keygen

command by default stores each public key in a file in the .ssh subdirectory of the user home directory; the filename depends on the encoding (DSA or RSA) and SSH version. For information about specifying URLs, see the Junos CLI User Guide.

Alternatively, you can include one or both of the ssh-dsa and ssh-rsa statements at the [edit system login user account-name authentication] hierarchy level. We recommend using the load-key-file statement, however, because it eliminates the need to type or cut and paste the public key on the command line. For more information about the ssh-dsa and ssh-rsa statements, see the Junos System Basics Configuration Guide.

4. Configure the device running Junos OS to accept SSH connections by including the

ssh statement at the [edit system services] hierarchy level. This statement

enables SSH access for all users and applications, not just Junos XML protocol client applications.

[edit system login user account-name authentication] user@host# top [edit] user@host# set system services ssh

5. Commit the configuration:

[edit] user@host# commit

6. Repeat Step 1 on each computer where the application runs, and Step 2 through

Step 5 on each device to which the application connects.

Prerequisites for Outbound SSH Connections

The outbound SSH feature allows the initiation of an SSH session between devices running Junos OS and Network and System Management servers where client-initiated TCP/IP connections are blocked (for example, when the device is behind a firewall). To configureoutbound SSH, you addan outbound-ssh configuration statement to thedevice. Once configured and committed, the device running Junos OS will begin to initiate

Junos 10.3 Junos XML Management Protocol Guide

outbound SSH sessions with the configured management clients. Once the outbound SSH session is initialized and the connection is established, the management server initiates the SSH sequence as the client and the device running Junos OS, acting as the server, authenticates the client.

Setting up outbound SSH involves:

•

Configuring the device running Junos OS for outbound SSH

•

Configuring the management server for outbound SSH.

To configure the device for outbound SSH:

1. Satisfy the prerequisites discussed in “Prerequisites for All Access Protocols” on

page 27.

2. In the [edit system services ssh] hierarchy level, set the SSH protocol to v2:

[edit system services ssh] set protocol-version v2

3. Generate/obtain a public/private key pair for the device running Junos OS. This key

pair willbe used to encryptthe data transferred across theSSH connection. Formore informationon generating key pairs, seethe JunosSystem Basics Configuration Guide.

4. If the public key will be installed on the application management system manually,

transfer the public key to the NSM server.

5. Add the following outbound-ssh statement at the [edit system services] hierarchy

level:

[edit system services] outbound-ssh client {

application-id {

device-id device-id; secret secret; keep-alive {

retry number;

timeout number; } reconnect-strategy (sticky | in-order) ; services netconf; address {

port destination-port;

retry number;

timeout number; }

}

Chapter 3: Controlling the Junos XML Management Protocol Session

The attributes are as follows:

•

application-id—(Required) Identifies the outbound-ssh configuration stanza on

the device. Each outbound-ssh stanza represents a single outbound SSH connection. This attribute is not sent to the client.

•

device-id—(Required) Identifies the device to the client during the initiation

sequence.

•

secret secret—(Optional) Public SSH host key of the device running the Junos OS.

If this statement is added to the outbound-ssh configuration hierarchy, the device running Junos OS will pass its public key to the configuration management server during the initialization of the outbound SSH service. This is the recommended method ofmaintaining acurrent copy ofthe router'spublic keyon theconfiguration management server.

•

keep-alive—(Optional) Specify that keepalive messages be sent from the device

running Junos OS to the configuration management server. To configure the keepalive message, you must set both the timeout and retry attributes.

•

retry number—Number of keepalive messages the device running Junos OS sends

without receivinga response from the configuration management server before the current SSH connection is terminated. The default is three tries.

•

timeout seconds—Amount of time, in seconds, that the server waits for data

before sending a keepalive signal. The default is 15 seconds.

•

reconnect-strategy (sticky | in-order)—(Optional) Method that the device running

Junos OS uses to reestablish a disconnected outbound SSH connection. Two methods are available:

•

sticky—The device attempts to reconnect to the configuration management

server to which it was last connected. If the connection is unavailable, the device attempts to establish a connection with the next configuration management server on the list and so forth until a connection is established.

•

in-order—The device attempts to establish an outbound SSH session based on

the configuration management server address list. The device attempts to establish a session with the first server on the list. If this connection is not available, the device attempts to establish a session with the next server, and so on down the list until a connection is established.

When reconnecting to a client, the device running Junos OS attempts toreconnect to the client based on the retry and timeout values for each of the clients listed in the configuration management server list..

•

services—(Required) Specifies the services available for the session. Currently,

NETCONF is the only service available.

•

address—(Required) The host name or the IPv4 address of the configuration

management server. You can list multiple clientsby addingeach client'sIP address or host name along with the connection parameters listed below.

•

port destination-port—Outbound SSH port for the client. The default is port 22.

Junos 10.3 Junos XML Management Protocol Guide

•

retrynumber– Number of times the device running Junos OS attempts toestablish

an outbound SSH connection before gving up. The default is three tries.

•

timeout seconds—Amount of time, in seconds, that the device running Junos OS

attemptsto establish an outbound SSH connection before givingup. Thedefault is 15 seconds.

6. Commit the configuration:

[edit] user@host# commit

To set up the configuration management server:

1. Satisfy the prerequisites discussed in “Prerequisites for All Access Protocols” on

page 27.

2. Enable the application to access the SSH software.

•

If the application uses the Junos XML protocol Perl module provided by Juniper Networks, no action is necessary. As part of the installation procedure for the Perl module, you install a prerequisites package that includes the necessary SSH software. For instructions, see “Downloading the Junos XML Protocol Perl Client and Prerequisites Package” on page 206.

•

If the application does not use the Junos XML protocol Perl module, obtain the SSH software and install it on the computer where the application runs. For informationabout obtaining and installing SSH software,see http://www.ssh.com/ and http://www.openssh.com/ .

3. (Optional) Manually install the device's public key for use with the SSH connection.

4. Configure the client system to receive and process initialization broadcast requests.

The intialization requests use the following syntax:

•

If the secret attribute isconfigured, the device running Junos OSwill send its public SSH key along withthe intializationsequence (recommended method).When the key has been received, the client needs to determine what to do with the device’s public key. We recommend that you replace any current public SSH key for the device with the new key. This ensures that the client always has the current key available for authentication.

MSG-ID: DEVICE-CONN-INFO\r\n MSG-VER: V1\r\n DEVICE-ID: <device-id>\r\n HOST-KEY: <pub-host-key>\r\n HMAC: <HMAC(pub-SSH-host-key, <secret>)>\r\n

•

If the secret attribute is not configured, the device does not send its public SSH key along with the initialization sequence. You need to manually install the current public SSH key for the device.

MSG-ID: DEVICE-CONN-INFO\r\n MSG-VER: V1\r\n DEVICE-ID: <device-id>\r\n

Chapter 3: Controlling the Junos XML Management Protocol Session

Prerequisites for SSL Connections

To enable a client application to use the SSL protocol to connect to the Junos XML protocol server, perform the following steps:

1. Enable the application to access the SSL software.

If the application uses the Junos XML protocol Perl module provided by Juniper Networks, no action is necessary. As part of the installation procedure for the Perl module, you installa prerequisites package that includesthe necessary SSLsoftware. For instructions, see “Downloading the Junos XML Protocol Perl Client and Prerequisites Package” on page 206.

If the application does not use the Junos XML protocol Perl module, obtain the SSL software and install it on the computer where the application runs. For information about obtaining and installing the SSL software, see http://www.openssl.org/ .

2. Satisfy the prerequisites discussed in “Prerequisites for All Access Protocols” on

page 27.

3. Use one of the following two methods to obtain an authentication certificate in

privacy-enhanced mail (PEM) format:

•

Request a certificate from a certificate authority; these agencies usually charge a fee.

•

Working on the computer where the client application runs, issue the following

openssl command in a standard command shell (not the Junos OS CLI). The

command generates a self-signed certificate and an unencrypted 1024-bit RSA private key, and writes them to the file called certificate-file.pem in the working directory. The command appears here on two lines only for legibility:

% openssl req -x509 -nodes -newkey rsa:1024 \

-keyout certificate-file.pem -out certificate-file.pem

4. Import the certificate onto the device running Junos OS by including the local

statement at the [edit security certificates] hierarchy level and the load-key-file statement at the [edit security certificates local certificate-name] hierarchy level.

[edit] user@host# edit security certificates local certificate-name

[edit security certificates local certificate-name] user@host# set load-key-file URL-or-path

certificate-nameis a name you choose to identify the certificateuniquely (forexample, junos-xml-protocol-ssl-client-hostname, where hostname is the computer where the

client application runs).

URL-or-path specifies the file that contains the paired certificate and private key (if

you issued the openssl command in Step 3, the certificate-name.pem file). Specify either the URL to its location on the client computer or a pathname on the local disk (if you have already used another method to copy the certificate file to the device’s local disk). For more information about specifying URLs and pathnames, see the Junos CLI User Guide.

Junos 10.3 Junos XML Management Protocol Guide

NOTE: The CLI expects the private key in the URL-or-path file to be unencrypted. If the

key is encrypted, the CLI prompts you for the passphrase associated with it, decrypts it, and stores the unencrypted version.

The set-load-key-file URL-or-path command copies the contents of the certificate file into the configuration. When you view the configuration, the CLI displays the string of charactersthat constitute the private key and certificate, marking them as SECRET-DATA. The load-key-file keyword is not recorded in the configuration.

5. Configure the device running Junos OS to accept SSL connections from Junos XML

protocol client applications on port 3220 by including the xnm-ssl statement at the

[edit system services] hierarchy level.

[edit security certificates local certificate-name] user@host# top [edit] user@host# set system services xnm-ssl local-certificate certificate-name

certificate-name is the unique name you assigned to the certificate in Step 4.

By default, the Junos XML protocol server supports up to 75 simultaneous SSL sessions and 150 connection attempts per minute. Optionally, you caninclude either or both the connection-limit statement to limit the number of concurrent sessions and the rate-limit statement to limit connection attempts. Both statements accept a value from 1 through 250.

[edit] user@host# set system services xnm-ssl connection-limit limit user@host# set system services xnm-ssl rate-limit limit

For more information about the xnm-ssl statement, see the Junos System Basics Configuration Guide.

6. Commit the configuration:

[edit] user@host# commit

7. Repeat Step 1on eachcomputer where theclient applicationruns, and Step 2through

Step 6 on each device to which the client application connects.

Chapter 3: Controlling the Junos XML Management Protocol Session

Prerequisites for Telnet Connections

To enablea client application to usethe Telnet protocol to access the Junos XML protocol server, perform the steps described in this section.

Devices running the Junos-FIPS software do not accept Telnet connections. We recommend that you do not use the Telnet protocol in a Common Criteria environment. For more information, see the Secure Configuration Guide for Common Criteria and Junos-FIPS.

1. Verify that the application can access the Telnet software. On most operating

systems, Telnet is accessible in the standard distribution.

2. Satisfy the prerequisites discussed in “Prerequisites for All Access Protocols” on

page 27.

3. Configure the device running Junos OS to accept Telnet connections by including

the telnet statement at the [edit system services] hierarchy level. This statement enables Telnet access for all users and applications, not just Junos XML protocol client applications.

[edit] user@host# set system services telnet

4. Repeat Step 1 on each computer where the application runs, and Step 2 and Step 3

on each device to which the application connects.

Connecting to the Junos XML Protocol Server

•

Connecting to the Junos XML Protocol Server from the Client Application on page 37

•

Connecting to the Junos XML Protocol Server from the CLI on page 38

Connecting to the Junos XML Protocol Server from the Client Application

For a client application to connect to the Junos XML protocol server and open a session, you must first satisfy the prerequisites described in “Prerequisites for Establishing a Connection” on page 27.

When the prerequisites are satisfied, an application written in Perl can most efficiently establish a connection and open a session by using the Junos XML protocol Perl module provided by Juniper Networks. For more information, see “Writing Junos XML Protocol Perl Client Applications” on page 205.

A client application that does not use the Junos XML protocol Perl module connects to the Junos XML protocol server by opening a socket or other communications channel to the Junos XML protocol server device, invoking one of the remote-connection routines appropriate for the programming language and access protocol that the application uses.

What the client application does next depends on which access protocol it is using:

•

If using the clear-text or SSL protocol, the client application performs the following steps:

Junos 10.3 Junos XML Management Protocol Guide

1. Emits the initialization PI and tag, as described in “Emitting the Initialization PI and

Tag” on page 39.

2. Authenticates with the Junos XML protocol server, as described in “Authenticating

with the Junos XML Protocol Server” on page 43.

•

If using the SSH or Telnet protocol, the client application performs the following steps:

1. Uses the protocol’s built-in authentication mechanism to authenticate.

2. Issues the junoscript command to request that the Junos XML protocol server

convert the connection into a Junos XML protocol session. For a C programming language example, see “Writing Junos XML Protocol C Client Applications” on page 233.

3. Emits the initialization PI and tag, as described in “Emitting the Initialization PI and

Tag” on page 39.

Connecting to the Junos XML Protocol Server from the CLI

The Junos XML management protocol and Junos XML API are primarily intended for use by client applications; however, for testing purposes you can establish an interactive Junos XML protocol session and type commands in a shell window. To connect to the Junos XML protocol server from the CLI operational mode,issue the junoscriptinteractive command (the interactive option causes the Junos XML protocol server to echo what you type):

user@host> junoscript interactive

To begin a Junos XML protocol session over the connection, emit the initialization PI and tag that are described in “Emitting the Initialization PI and Tag” on page 39. You can then type sequences oftag elements thatrepresent operational andconfiguration operations, which are described in “Requesting Information” on page 61, “Changing Configuration Information” on page 103, and “Committing a Configuration” on page 133. To eliminate typing errors, save complete tag element sequences in a file and use a cut-and-paste utility to copy the sequences to the shell window.

NOTE: When you close the connection to the Junos XML protocol server (for example,

by emitting the <request-end-session/> and </junoscript> tags), the routing platform completely closesyour connectioninstead of returning you to the CLI operational mode prompt. For more information about ending a Junos XML protocol session, see “Ending a Junos XML Protocol Session and Closing the Connection” on page 55.

Starting the Junos XML Protocol Session

Each Junos XML protocol session begins with a handshake in which the Junos XML protocol server and the client application specify the version of XML and the version of the Junos XML management protocol they are using. Each party parses the version

Chapter 3: Controlling the Junos XML Management Protocol Session

information emitted by the other, using it to determine whether they can communicate successfully. The following sections describe how to start a Junos XML protocol session:

•

Emitting the Initialization PI and Tag on page 39

•

Parsing the Initialization PI and Tag from the Junos XML Protocol Server on page 41

•

Verifying Software Compatibility on page 43

•

Supported Software Versions on page 43

Emitting the Initialization PI and Tag

When the Junos XML protocol session begins, the client application emits an <?xml?> PI and an opening <junoscript> tag, as described in the following sections:

•

Emitting the <?xml?> PI on page 39

•

Emitting the Opening <junoscript> Tag on page 40

Emitting the <?xml?> PI

The client application begins by emitting an <?xml?> PI.

NOTE: In the following example (and in all examples in this document of tag elements

emitted by a client application), boldfont is used to highlight the part of the tag sequence that is discussed in the text.

<?xml version="version" encoding="encoding"?>

The attributes are as follows. For a list of the attribute values that are acceptable in the current version of the Junos XML management protocol, see “Supported Software Versions” on page 43.

•

version—The version of XML with which tag elements emitted by the client application

comply

•

encoding—The standardized character set that the client application uses and can

understand

In the following example of a client application’s <?xml?> PI, the version="1.0" attribute indicates that the application is emitting tag elements that comply with the XML 1.0 specification. The encoding="us-ascii" attribute indicates that the client application is using the 7-bit ASCII character set standardized by the American National Standards Institute (ANSI). For more information about ANSI standards, see http://www.ansi.org/ .

<?xml version="1.0" encoding="us-ascii"?>

NOTE: If the application fails to emit the <?xml?> PI before emitting the opening

<junoscript> tag, the Junos XML protocol server emits an error messageand immediately

closes the session and connection. For more information, see “Emitting the Opening <junoscript> Tag” on page 40.

Junos 10.3 Junos XML Management Protocol Guide

Emitting the Opening <junoscript> Tag

The client application then emits its opening <junoscript> tag, which has the following syntax (and appears here on two lines only for legibility):

<junoscript version="version" hostname="hostname" junos:key="key"

release="release-code">

The attributes are as follows. For a list of the attribute values that are acceptable in the current version of the Junos XML management protocol, see “Supported Software Versions” on page 43.

•

version—(Required) Specifies the version ofthe Junos XML management protocol that

the client application is using.

•

hostname—(Optional) Names the machine on which the client application is running.

The information is used only when diagnosing problems. The Junos XML protocol does not include support for establishing trusted-host relationships or otherwise altering Junos XML protocol server behavior depending on the client hostname.

•

junos:key—(Optional) Requests that the Junos XML protocol server indicate whether

a child configurationelement isan identifierfor its parentelement. The only acceptable value is key. For more information, see “Requesting an Indicator for Identifiers” on page 73.

•

release—(Optional) Identifies the Junos OS Release (and by implication, the Junos

XML API) for which the client application is designed. The value of this attribute indicates that the client application can interoperate successfully with a Junos XML protocol server that also supports that version of the Junos XML API. In other words, it indicates that the client application emits request tag elements from that API and knows how to parse response tag elements from it. If the application does not include this attribute, the Junos XML protocol server emits tag elements from the Junos XML API that it supports. For more information, see “Verifying Software Compatibility” on page 43.

For the value of the release attribute, use the standard notation for Junos OS version numbers. For example, the value 10.3R1 represents the initial version of Junos OS Release 10.3.

In the following example of a client application’s opening <junoscript> tag, the

version="1.0" attribute indicates that it is using Junos XML protocol version 1.0. The hostname="client1" attribute indicates that theclient applicationis runningon the machine

called client1. The release="10.3R1" attribute indicates that the switch, router, or security device is running the initial version of Junos OS Release 10.3.

Chapter 3: Controlling the Junos XML Management Protocol Session

NOTE: If the application fails to emit the <?xml?> PI before emitting the opening

<junoscript> tag, the Junos XML protocol server emits an error message similar to the

following and immediately closes the session and connection:

<rpc-reply>

<xnm:error xmlns="http://xml.juniper.net/xnm/1.1/xnm" \

xmlns:xnm="http://xml.juniper.net/xnm/1.1/xnm"> <message>

communication error while exchanging credentials

</message>

</xnm:error> </rpc-reply>  </junoscript>

For more information about the <xnm:error> tag, see “Handling an Error or Warning” on page 51.

Parsing the Initialization PI and Tag from the Junos XML Protocol Server

When the Junos XML protocol session begins, the Junos XML protocol server emits an

<?xml?> PI and an opening <junoscript> tag, as described in the following sections:

•

Parsing the Junos XML Protocol Server’s <?xml?> PI on page 41

•

Parsing the Junos XML Protocol Server’s Opening <junoscript> Tag on page 41

Parsing the Junos XML Protocol Server’s <?xml?> PI

The syntax for the <?xml?> PI is as follows:

<?xml version="version" encoding="encoding"?>

The attributes are as follows. For a list of the attribute values that are acceptable in the current version of the Junos XML management protocol, see “Supported Software Versions” on page 43.

•

version—The version of XML with which tag elements emitted bythe JunosXML protocol

server comply

•

encoding—The standardized character set that the Junos XML protocol server uses

and can understand

In the following example of a Junos XML protocol server’s <?xml?> PI, the version="1.0" attribute indicates that the server is emitting tag elements that comply with the XML 1.0 specification.The encoding="us-ascii" attributeindicates that theserver isusing the 7-bit ASCII character set standardized by ANSI. For more information about ANSI standards, see http://www.ansi.org/ .

<?xml version="1.0" encoding="us-ascii"?>

Parsing the Junos XML Protocol Server’s Opening <junoscript> Tag

After emitting the <?xml?>PI, the server then emits its opening <junoscript> tag, which has the following form (the tag appears on multiple lines only for legibility):

<junoscript xmlns="namespace-URL" xmlns:junos="namespace-URL" \

Junos 10.3 Junos XML Management Protocol Guide

schemaLocation="namespace-URL" os="JUNOS" \ release="release-code" hostname="hostname" version="version">

The attributes are as follows:

•

hostname—The name of the device on which the Junos XML protocol server is running.

•

os—The operating system of the device on which the Junos XML protocol server is

running. The value is always JUNOS.

•

release—The identifier for the version of the Junos OS from which the Junos XML

protocol server is derived and that it is designed to understand. It is presumably in use on the device where the Junos XML protocol server is running. The value of the release attribute uses the standard notation for Juniper Networks software version numbers. For example, the value 10.3R1 represents the initial version of Junos OS Release 10.3.

•

schemaLocation—The XML namespace for the XML Schema-language representation

of the Junos configuration hierarchy.

•

version—The version of the Junos XML management protocol that the Junos XML

protocol server is using.

•

xmlns—The XML namespace for the tag elements enclosed by the <junoscript> tag

element that do not have a prefix on their names (that is, the default namespace for Junos XML tag elements). The value is a URL of the form

http://xml.juniper.net/xnm/version/xnm, where version is a string such as 1.1.

•

xmlns:junos—The XML namespace for the tag elements enclosed by the <junoscript>

tag element that have the junos: prefix on their names. The value is a URL of the form

http://xml.juniper.net/junos/release-code/junos, where release-code is the standard

string that represents areleaseof the Junos OS. For example,the value 10.3R1represents the initial version of Junos OS Release 10.3.

In the following example of a Junos XML protocol server’s opening <junoscript> tag, the

version attribute indicates that the server is using Junos XML protocol version 1.0, and

the hostname attribute indicates that the router’s name is big-device. The os and release attributes indicate that the device is running the initial version of Junos OS Release 10.3. The xmlns attribute indicate that the default namespace for Junos XML tag elements is

http://xml.juniper.net/xnm/1.1/xnm . The xmlns:junos attribute indicates that the

namespace for tag elements that have the junos: prefix is

http://xml.juniper.net/junos/10.3R1/junos . The tag appears on multiple lines only for

legibility.

<junoscript xmlns="http://xml.juniper.net/xnm/1.1/xnm"\

xmlns:junos="http://xml.juniper.net/junos/10.3R1/junos" \ schemaLocation="http://xml.juniper.net/junos/10.3R1/junos" os="JUNOS" \ release="10.3R1.8" hostname="big-device" version="1.0">

Chapter 3: Controlling the Junos XML Management Protocol Session

Verifying Software Compatibility

Exchanging <?xml?> and <junoscript> tag elements enablesa client application andthe Junos XML protocol server to determine if they are running different versions of the software used during a Junos XML protocol session. Different versions are sometimes incompatible, and by Junos XML protocol convention the party running the later version of software determines how to handle any incompatibility. For fully automated performance, include code in the client application that determines if its version of softwareis later thanthat of the Junos XMLprotocol server. Decide which of the following options is appropriate when the application’s version is more recent, and implement the corresponding response:

•

Ignore differences in Junos version, and do not alter the client application’s behavior to accommodate the Junos XML protocol server. A difference in Junos versions does not necessarily make the server and client incompatible, sothis is often avalid approach.

•

Alter standard behavior to be compatible with the Junos XML protocol server. If the client application is running a later version of the Junos OS, for example, it can choose to emit only tag elements that represent the software features available in the Junos XML protocol server’s version of the Junos OS.

•

End the Junos XML protocol session and terminate the connection. This is appropriate if you decide that it is not practical to accommodate the Junos XML protocol server’s version of software. For instructions, see “Ending a Junos XML Protocol Session and Closing the Connection” on page 55.

Supported Software Versions

Table 6 on page 43 specifies the PI or opening tag and attribute used to convey version information during Junos XML protocol session initialization in version 1.0 of the Junos XML management protocol.

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

AttributePI or TagSoftware and Versions

version="1.0"<?xml?>XML 1.0

encoding="us-ascii"<?xml?>ANSI-standardized 7-bit ASCII

character set

version="1.0"<junoscript>Junos XML protocol 1.0

<junoscript>Junos OS Release

release="m.nZb"

For example:

release="10.3R1"

Authenticating with the Junos XML Protocol Server

A client application that uses the clear-text or SSL protocol must now authenticate with the Junos XML protocol server. (Applications that use the SSH or Telnet protocol use the protocol’s built-in authentication mechanism before emitting initialization tag elements, as described in “Connecting to the Junos XML Protocol Server” on page 37.)

Junos 10.3 Junos XML Management Protocol Guide

See the following sections:

•

Submitting an Authentication Request on page 44

•

Interpreting the Authentication Response on page 45

Submitting an Authentication Request

The client application begins the authentication process byemitting an<rpc> tag element enclosing the <request-login>tag element. In the <request-login>tag element, itencloses the <username> tag element to specify the Junos OS account (username) under which to establish the connection. The account must already be configured on the Junos XML protocolserver device, as describedin “Prerequisites for AllAccess Protocols” on page 27. You can choose whether or not the application provides the account password as part of the initial tag sequence.

Providing the Password with the Username

To provide the password along with the username, the application emits the following tag sequence:

<rpc>

<request-login>

<username>username</username>

<challenge-response>password</challenge-response>

</request-login>

</rpc>

This tag sequenceis appropriate if the applicationautomatesaccess to routing, switching, or security platform information anddoes not interact withusers, orobtains the password from a user before beginning the authentication process.

Providing Only the Username

To omit the password andspecify only the username, theapplication emits the following tag sequence:

<rpc>

<request-login>

<username>username</username>

</request-login>

</rpc>

This tag sequence is appropriate if the application does not obtain the password until the authentication process has alreadybegun. Inthis case,the Junos XML protocolserver returns the <challenge> tag element within an <rpc-reply> tag element to request the passwordassociated with the username. The tag element enclosesthe Password: string, which the client application can forward to the screen as a prompt for a user. The

echo="no" attribute in the opening <challenge> tag specifies that the password string

typed by the user does not echo on the screen. The tag sequence is as follows:

<rpc-reply xmlns:junos="URL">

<challenge echo="no">Password:</challenge>

</rpc-reply>

The client application obtains the password and emits the following tag sequence to forward it to the Junos XML protocol server:

<rpc>

Chapter 3: Controlling the Junos XML Management Protocol Session

<request-login>

<username>username</username>

<challenge-response>password</challenge-response>

</request-login>

</rpc>

Interpreting the Authentication Response

After it receives the username and password, the Junos XML protocol server emits the

<authentication-response> tag element to indicate whether the authentication attempt

is successful.

Server Response When Authentication Succeeds

If the password is correct, the authentication attempt succeeds and the Junos XML protocol server emits the following tag sequence:

<rpc-reply xmlns:junos="URL">

<authentication-response>

<status>success</status>

<message>username</message>

<login-name>remote-username</login-name>

</authentication-response>

</rpc-reply>

The <message> tag element contains the Junos username under which the connection is established.

The <login-name> tag element contains theusername thatthe clientapplication provided to an authentication utility such as RADIUS or TACACS+. This tag element appears only if the username differs from the username contained in the <message> tag element.

The JunosXML protocolsession begins, as described in“Starting the Junos XML Protocol Session” on page 38.

Server Response When Authentication Fails

If thepassword is not correct or the <request-login>tag element is otherwise malformed, the authentication attempt fails and the Junos XML protocol server emits the following tag sequence:

<rpc-reply xmlns:junos="URL">

<authentication-response>

<message>error-message</message>

</authentication-response>

</rpc-reply>

The error-message string in the <message> tag element explains why the authentication attempt failed. The Junos XML protocol server emits the <challenge> tag element up to two more times before rejecting the authentication attempt and closing the connection.

Exchanging Information with the Junos XML Protocol Server

The session continues when the client application sends a request to the Junos XML protocol server. The Junos XML protocol server does not emit any tag elements after

Junos 10.3 Junos XML Management Protocol Guide

session initialization except in response to the client application’s requests. The following sections describe the exchange of tagged data:

•

Sending a Request to the Junos XML Protocol Server on page 46

•

Parsing the Junos XML Protocol Server Response on page 48

•

Handling an Error or Warning on page 51

•

Halting a Request on page 52

Sending a Request to the Junos XML Protocol Server

To initiate a request to the Junos XML protocol server, a client application emits the opening <rpc> tag, followed by one or more tag elements that represent the particular request, and the closing </rpc> tag, in that order:

<rpc>

</rpc>

The application encloses each request in a separate pair of opening <rpc> and closing

</rpc> tags. The <rpc> tag element can occur only within the <junoscript> tag element.

For an example of emitting an <rpc> tag element in the context of a completeJunos XML protocol session, see “Example of a Junos XML Protocol Session” on page 56.

The Junos XML protocol server ignores any newline characters, spaces, or other white space characters that occur between tag elements in the tag stream, but does preserve white space withintag elements. For more information, see “Spaces,Newline Characters, and Other White Space” on page 11.

See the following sections for further information:

•

Request Classes on page 46

•

Including Attributes in the Opening <rpc> Tag on page 48

Request Classes

A client application can make three classes of requests:

•

Operational Requests on page 46

•

Configuration Information Requests on page 47

•

Configuration Change Requests on page 47

NOTE: Although operational and configuration requests conceptually belongto separate

classes, a Junos XML protocol session does not have distinct modes that correspond to CLI operational and configuration modes. Each request tag element is enclosed within its own <rpc> tag element, so a client application can freely alternate operational and configuration requests.

Operational Requests

Operational requests are requests for information about the status of a device running Junos OS. Operational requests correspond to the CLI operational mode commands listed in the Junos OS command references. The Junos XML API defines a request tag

Chapter 3: Controlling the Junos XML Management Protocol Session

element for many CLI commands. For example, the <get-interface-information> tag element corresponds to the show interfaces command, and the <get-chassis-inventory> tag element requests the same information as the show chassis hardware command.

The following sample request is for detailed information about the interface ge-2/3/0:

<rpc>

<get-interface-information>

<interface-name>ge-2/3/0</interface-name>

</get-interface-information>

</rpc>

For more information, see “Requesting Operational Information” on page 62. For information about the Junos XML request tag elements available in thecurrent Junos OS Release, see the Junos XML API Operational Reference.

Configuration Information Requests

Configuration information requests are requests for information about the device’s candidate configuration, a private configuration, or the committed configuration (the one currently in active use on the switching, routing, or security platform). The candidate and committed configurations diverge when there are uncommitted changes to the candidate configuration.

The Junos XML protocol defines the <get-configuration> operation for retrieving configuration information. The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy.

The following example shows how to request information about the [edit system login] hierarchy level in the candidate configuration:

<rpc>

<get-configuration>

</system>

</configuration>

</get-configuration>

</rpc>

For more information, see “Requesting Configuration Information” on page 64. For a summary of Junos XML configuration tag elements, see the Junos XML API Configuration Reference.

Configuration Change Requests

Configuration change requests are requests to change the candidate configuration, or to commit those changes to put them into active use on the device running Junos OS. The Junos XMLprotocol defines the <load-configuration>operation for changing configuration information. The Junos XML API defines a tag element for every CLI configuration statement described in the Junos OS configuration guides.

Junos 10.3 Junos XML Management Protocol Guide

The following example shows how to create a new Junos OS user account called admin at the [edit system login] hierarchy level in the candidate configuration:

<rpc>

<load-configuration>

<login>

<user>

<name>admin</name> <full-name>Administrator</full-name> <class>superuser</class>

</user>

</login>

</system>

</configuration>

</load-configuration>

</rpc>

For more information, see “Changing Configuration Information” on page 103 and “Committing a Configuration” on page 133. For a summary of Junos XML configuration tag elements, see the Junos XML API Configuration Reference.

Including Attributes in the Opening <rpc> Tag

Optionally, a client application can include one or more attributes of the form

attribute-name="value"in theopening <rpc> tag foreach request. TheJunos XMLprotocol

server echoes each attribute, unchanged, in the opening <rpc-reply> tag in which it encloses its response. A client application can use this feature to associate requests and responses by including an attribute in each opening <rpc> request tag that assigns a unique identifier. The Junos XML protocol server echoes the attribute in its opening

<rpc-reply> tag, making it easy to map the response to the initiating request. The client

application can freely define attribute names, except as described in the following note.

NOTE: The xmlns:junos attribute name is reserved. The Junos XML protocol server sets

the attribute to an appropriate value on the opening <rpc-reply> tag, so client applications must not emit it on the opening <rpc> tag. For more information, see “xmlns:junos Attribute” on page 49.

Parsing the Junos XML Protocol Server Response

The Junos XML protocol server encloses its response to each client request in a separate pair of opening <rpc-reply> and closing </rpc-reply> tags. Each response constitutes a well-formed XML document.

<rpc-reply xmlns:junos="URL">

</rpc-reply>

The xmlns:junos attribute in the opening <rpc-reply> tag defines the default namespace for the enclosed tag elements that have the junos: prefix in their names, as discussed further in “xmlns:junos Attribute” on page 49. The <rpc-reply> tag element occurs only within the <junoscript> tag element. Client applications must include code for parsing

Chapter 3: Controlling the Junos XML Management Protocol Session

the stream of response tag elements coming from the Junos XML protocol server, either processing them as they arrive or storing them until the response is complete. See the following sections for further information:

•

xmlns:junos Attribute on page 49

•

Junos XML Protocol Server Response Classes on page 49

•

Using a Standard API to Parse Response Tag Elements on page 50

For anexample of parsing the <rpc-reply> tag elementin the context of a complete Junos XML protocol session, see “Example of a Junos XML Protocol Session” on page 56.

xmlns:junos Attribute

The Junos XML protocol server includes the xmlns:junos attribute in the opening

<rpc-reply> tag to define the XML namespace for the enclosed Junos XML tag elements

that have the junos: prefix on their names. The namespace is a URL of the form

http://xml.juniper.net/junos/release-code/junos,where release-code is the standard string

that represents the release of the Junos OS running on the Junos XML protocol server machine.

In the following example, the namespace corresponds to the initial version of Junos OS Release 10.3:

<rpc-reply xmlns:junos="http://xml.juniper.net/junos/10.3R1/junos">

Junos XML Protocol Server Response Classes

The Junos XML protocol server returns three classes of responses:

•

Operational Responses on page 49

•

Configuration Information Responses on page 50

•

Configuration Change Responses on page 50

Operational Responses

Operational responses are responses to requests for information about the status of a switching, routing, or security platform. They correspond tothe output from CLI operational commands as described in the Junos command references.

The Junos XML API defines response tag elements for all defined operational request tag elements. For example, the Junos XML protocol server returns the information requestedby the<get-interface-information> tag elementin a response tagelement called

<interface-information>, and returns the information requested by the <get-chassis-inventory> tagelement ina responsetag element called <chassis-inventory>.

The following sample response includes information about the interface ge-2/3/0. The namespace indicated by the xmlns attribute contains interface information for the initial version of Junos OS Release 10.3.

<rpc-reply xmlns:junos="http://xml.juniper.net/junos/10.3R1/junos">

<interface-information xmlns="http://xml.juniper.net/junos/10.3R1/junos-interface">

<physical-interface>

</physical-interface>

Junos 10.3 Junos XML Management Protocol Guide

</interface-information>

</rpc-reply>

For more information about the xmlns attribute and contents of operational response tag elements, see “Requesting Operational Information” on page 62. For a summary of operational response tag elements, see the Junos XML API Operational Reference.

Configuration Information Responses

Configuration information responses are responses to requests for information about the device’scurrent configuration.The JunosXML API defines a tag elementfor every container and leaf statement in the configuration hierarchy.

The following sample response includes the information at the [edit system login] hierarchy level in the configuration hierarchy. For brevity, the sample shows only one user defined at this level.

<rpc-reply xmlns:junos="URL">

<login>

<user>

<name>admin</name> <full-name>Administrator</full-name>

</user>

</login>

</system>

</configuration>

</rpc-reply>

Configuration Change Responses

Configuration change responses are responses to requests that change the state or contents of the device configuration. For commit operations, the Junos XML protocol server encloses an explicit indicator of success or failure within the <commit-results> tag element:

<rpc-reply xmlns:junos="URL">

<commit-results>

</commit-results>

</rpc-reply>

For other operations, the Junos XML protocol server indicates success by returning an opening <rpc-reply> and closing </rpc-reply> tag with nothing between them, instead of emitting an explicit success indicator:

<rpc-reply xmlns:junos="URL"> </rpc-reply>

For more information, see “Changing Configuration Information” on page 103 and “Committing a Configuration” on page 133. For a summary of the available configuration tag elements, see the Junos XML API Configuration Reference.

Using a Standard API to Parse Response Tag Elements

Client applications can handle incoming XML tag elements by feeding them to a parser that implements a standard API such as the Document Object Model (DOM) or Simple

API for XML (SAX). Describing how to implement and use a parser is beyond the scope of this document.

Routines in the DOM accept incoming XML and build a tag hierarchy in the client application’s memory. There are alsoDOM routinesfor manipulating anexisting hierarchy. DOM implementations are available for several programming languages, including C, C++, Perl, and Java. For detailed information, see the Document Object Model (DOM) Level 1 Specification from the World Wide Web Consortium (W3C) at

http://www.w3.org/TR/REC-DOM-Level-1/ . Additional information is available from the

Comprehensive Perl Archive Network (CPAN) at

http://search.cpan.org/~tjmather/XML-DOM/lib/XML/DOM.pm .

One potential drawback with DOM is that it always builds a hierarchy of tag elements, which canbecome very large. If a clientapplication needs tohandle only onesubhierarchy at a time, it can use a parser that implements SAX instead. SAX accepts XML and feeds the tagelements directly to the client application, which must buildits own tag hierarchy. For more information, see the official SAX website at http://sax.sourceforge.net/ .

Handling an Error or Warning

Chapter 3: Controlling the Junos XML Management Protocol Session

If the Junos XML protocol server encounters an error condition, it emits an <xnm:error> tag element, which encloses child tag elements that describe the nature of the error. Client applications must be prepared to receive and handle an <xnm:error> tag element at any time. The information in any response tag elements already received and related to the current request might be incomplete. The client application can include logic for deciding whether to discard or retain the information.

The syntax of the <xnm:error> tag element is as follows. The opening tag appears on multiple lines only for legibility:

<xnm:error xmlns="http://xml.juniper.net/xnm/1.1/xnm" \

xmlns:xnm="http://xml.juniper.net/xnm/1.1/xnm">

</xnm:error>

The attributes are as follows:

•

xmlns—The XML namespace for the tag elements enclosed by the <xnm:error> tag

element that do not have a prefix in their names (that is, the default namespace for Junos XML tag elements). The value is a URL of the form

http://xml.juniper.net/xnm/version/xnm, where version is a string such as 1.1.

•

xmlns:xnm—The XMLnamespace for the<xnm:error> tagelement andfor theenclosed

tag elements that have the xnm: prefix in their names. The value is a URL of the form

http://xml.juniper.net/xnm/version/xnm, where version is a string such as 1.1.

The set of child tag elements enclosed in the <xnm:error> tag element depends on the operation that server was performing when the error occurred. An error can occur while the server is performing anyof the followingoperations, andthe servercan senda different combination of child tag elements in each case:

•

Processing an operational request submitted by a client application (discussed in “Requesting Information” on page 61)

Junos 10.3 Junos XML Management Protocol Guide

•

Opening, locking, committing, or closing a configuration as requested by a client application (discussed in“Exchanging Information withthe JunosXML Protocol Server” on page 45,“Committing aConfiguration” onpage 133,and “Endinga Junos XML Protocol Session and Closing the Connection” on page 55)

•

Parsing configuration data submitted by a client application in a <load-configuration> tag element (discussed in “Changing Configuration Information” on page 103)

If the Junos XML protocol server encounters a less serious problem, it can emit an

<xnm:warning> tag element instead. The usual response for the client application in this

case is to log the warning or pass it to the user, but to continue parsing the server’s response.

For a description of the child tag elements that can appear within an <xnm:error> or

<xnm:warning> tag element to specify the nature of the problem, see “<xnm:error>” on

page 179 and “<xnm:warning>” on page 181.

Halting a Request

To request that the Junos XML protocol server stop processing the current request, a client application emits the <abort/> tag directly after the closing </rpc> tag for the operation to be halted:

<rpc>

</rpc>

The Junos XML protocol server responds with the <abort-acknowledgement/> tag:

<rpc-reply xmlns:junos="URL">

<abort-acknowledgement/>

</rpc-reply>

Depending on the operation being performed, response tag elements already sent by the Junos XML protocol server for the halted request are possibly invalid.The application can include logic for deciding whether to discard or retain them as appropriate.

For more information, see“<abort/>” on page 149and “<abort-acknowledgement/>” on page 150.

Locking and Unlocking the Candidate Configuration or Creating a Private Copy

When a client application is requesting or changing configuration information, it can use one of three methods to access the configuration:

•

Lock the candidate configuration, which prevents other users or applications from changing the configuration until the application releases the lock (equivalent to the CLI configure exclusive command).

•

Create a private copy of the candidate configuration, which enables the application to view or change configuration data without affecting the candidate or active configurationuntil the private copy is committed (equivalent to the CLI configureprivate command).

Chapter 3: Controlling the Junos XML Management Protocol Session

•

Change the candidate configuration without locking it. We do not recommend this method, because of the potential for conflictswith changes madeby otherapplications or users that are editing the configuration at the same time.

If anapplication issimply requesting configuration information andnot changing it, locking the configuration or creating a private copy is not required. However, it is appropriate to lock the configuration if it is important that the information being returned not change during the session. The information from a private copy is guaranteed not to change, but can diverge from the candidate configuration if other users or applications are changing the candidate.

The restrictions on,and interactions between, operations on the locked regular candidate configuration and a private copy are the same as for the CLI configure exclusive and

configure private commands. For more information, see “Committing a Private Copy of

the Configuration” on page 135 and the Junos CLI User Guide.

For moreinformation about locking and unlocking the candidate configuration or creating a private copy, see the following sections:

•

Locking the Candidate Configuration on page 53

•

Unlocking the Candidate Configuration on page 54

•

Creating a Private Copy of the Configuration on page 54

Locking the Candidate Configuration

To lock the candidate configuration, a client application emits the <lock-configuration/> tag within an <rpc> tag element:

<rpc>

<lock-configuration/>

</rpc>

Emitting this tag prevents other users or applications from changing the candidate configuration until the lock is released (equivalent to the CLI configure exclusive command). Locking the configuration is recommended, particularly on devices where multiple users are authorized to change the configuration. A commit operation applies to all changes in the candidate configuration, not just those made by the user or application that requests the commit. Allowing multiple users or applications to make changes simultaneously can lead to unexpected results.

When the Junos XML protocol server locks the configuration, it returns an opening

<rpc-reply> and closing </rpc-reply> tag with nothing between them:

<rpc-reply xmlns:junos="URL"> </rpc-reply>

If theJunos XML protocol server cannotlock theconfiguration,the <rpc-reply> tag element insteadencloses an<xnm:error> tagelement explaining thereason for the failure. Reasons for the failure can include the following:

•

Another user or application has already locked the candidate configuration. The error message reports the login identity of the user or application.

Junos 10.3 Junos XML Management Protocol Guide

•

The candidate configuration already includes changes that have not yet been committed. To commit the changes, see “Committing a Configuration” on page 133. To roll back toa previousversion of the configuration (and losethe uncommitted changes), see “Rolling Back to a Previous or Rescue Configuration” on page 109.

Only one application can hold the lock on the candidate configuration at a time. Other users and applications can read the candidate configuration while it is locked, or can change their private copies. The lock persists until either the Junos XML protocol session ends or the client application unlocks the configuration by emitting the

<unlock-configuration/> tag, as described in “Unlocking the Candidate Configuration”

on page 54.

If the candidate configuration is not committed before the client application unlocks it, or if the Junos XML protocol session ends for any reason before the changes are committed, the changes are automatically discarded. The candidate and committed configurations remain unchanged.

Unlocking the Candidate Configuration

As long as a client application holds a lock on the candidate configuration, other applications and users cannot change the candidate. To unlock the candidate configuration,the client application includes the <unlock-configuration/> tag in an <rpc> tag element:

<rpc>

<unlock-configuration/>

</rpc>

To confirm that it has successfully unlocked the configuration, the Junos XML protocol server returns an opening <rpc-reply> and closing </rpc-reply> tag with nothing between them:

<rpc-reply xmlns:junos="URL"> </rpc-reply>

If the Junos XML protocol server cannot unlock the configuration, the <rpc-reply> tag element instead encloses an<xnm:error> tag element explainingthe reason for thefailure.

Creating a Private Copy of the Configuration

To create a private copy of the candidate configuration, a client application emits the

<private/> tag enclosed in <rpc> and <open-configuration> tag elements:

<rpc>

<open-configuration>

</open-configuration>

</rpc>

The client application can then perform the same operations on the private copy as on the regular candidate configuration, as described in “Changing ConfigurationInformation” on page 103.

After making changes to the private copy, the client application can commit the changes to the active configuration on the device running Junos OS by emitting the

<commit-configuration> tag element, asfor theregular candidate configuration.However,

Client Application Junos XML Protocol Server

<rpc>

<open-configuration>

</open-configuration>

</rpc>

<rpc-reply xmlns:junos="URL">

<xnm:warning xmlns="http://xml.juniper.net/xnm/1.1/xnm" \

xmlns:xnm="http://xml.juniper.net/xnm/1.1/xnm">

<message>uncommitted changes will be discarded on exit</message>

</xnm:warning>

</rpc-reply>

T1172

Chapter 3: Controlling the Junos XML Management Protocol Session

there are some restrictions on the commit operation for a private copy. For more information, see “Committing a Private Copy of the Configuration” on page 135.

To discard the private copy without committing it, a client application emits the

<close-configuration/> tag enclosed in an <rpc> tag element:

<rpc>

<close-configuration/>

</rpc>

Any changes to the private copy are lost. Changes to the private copy are also lost if the Junos XML protocol session ends for any reason before the changes are committed. It is not possible to save changes to a private copy other than by emitting the

<commit-configuration> tag element.

The following example shows how to create a private copy of the configuration. The Junos XML protocol server includes a reminder in its confirmation response that changes are discarded from a private copy if they are not committed before the session ends.

Ending a Junos XML Protocol Session and Closing the Connection

When a client application is finished making requests, it ends the Junos XML protocol session by emitting the <request-end-session/> tag within an <rpc> tag element:

In response, the Junos XML protocol server emits the <end-session/> tag enclosed in an

<rpc-reply> tag element and a closing </junoscript> tag:

The client application waits to receive this reply before emitting its closing </junoscript> tag:

For an example of the exchange of closing tags, see “Closing the Junos XML Protocol Session” on page 59.

<rpc>

<request-end-session/>

</rpc>

<rpc-reply xmlns:junos="URL">

<end-session/> </rpc-reply> </junoscript>

</junoscript>

Junos 10.3 Junos XML Management Protocol Guide

The clientapplication can then close the SSH, SSL, or other connection to the Junos XML protocol server machine. Client applications written in Perl can close the Junos XML protocol session and connection by using the Junos XML protocol Perl module described in “Writing Junos XMLProtocolPerl ClientApplications” onpage 205. For more information, see that chapter.

Client applications that do not use the Junos XML protocol Perl module use the routine provided for closing a connection in the standard library for their programming language.

Displaying CLI Output as XML Tag Elements

To display the output from a CLI command as Junos XML protocol tag elements and Junos XML tag elements instead of as the default formatted ASCII text, pipe the output from the command to the display xml command. The tag elements that describe Junos OS configuration or operational data belong to the Junos XML API, which defines the Junos content that can be retrieved and manipulated by the Junos XML management protocol operations.

The following example shows the output from the show chassis hardware command issued on an M20 router that is running the initial version of Junos OS Release 10.3 (the opening <chassis-inventory> tag appears on two lines only for legibility):

user@host> show chassis hardware | display xml

<rpc-reply xmlns:junos="http://xml.juniper.net/junos/10.3R1/junos">

<chassis-inventory \

xmlns="http://xml.juniper.net/junos/10.3R1/junos-chassis">

<name>Chassis</name> <serial-number>00118</serial-number> <description>M20</description> <chassis-module>

<name>Backplane</name> <version>REV 06</version> <part-number>710-001517</part-number>

<serial-number>AB5911</serial-number> </chassis-module> <chassis-module>

<name>Power Supply A</name>

</chassis-module>

</chassis>

</chassis-inventory>

</rpc-reply>

Example of a Junos XML Protocol Session

This section describes the sequence of tag elements in a sample Junos XML protocol session. The clientapplication beginsby establishing aconnection to aJunos XML protocol server. See the following sections:

•

Exchanging Initialization PIs and Tag Elements on page 57

•

Sending an Operational Request on page 57

•

Client Application Junos XML Protocol Server

<?xml version="1.0" encoding="us-ascii"?> <?xml version="1.0" encoding="us-ascii"?> <junoscript version="1.0" release=" JUNOS-release"> <junoscript version="1.0" hostname="router1" \

os="JUNOS" release="JUNOS-release" \ xmlns="URL"xmlns:junos=" URL" \ xmlns:xnm="URL">

T1173

Client Application Junos XML Protocol Server

<rpc>

<get-chassis-inventory>

</get-chassis-inventory>

</rpc>

<rpc-reply xmlns:junos="URL">

<chassis-inventory xmlns="URL">

<name>Chassis</name> <serial-number>1122</serial-number> <description>M320</description> <chassis-module>

<name>Midplane</name>

<!- - other child tags for the Midplane - -> </chassis-module> <!- - tags for other chassis modules- ->

</chassis>

</chassis-inventory>

</rpc-reply>

T1102

Locking the Configuration on page 57

•

Changing the Configuration on page 58

•

Committing the Configuration on page 58

•

Unlocking the Configuration on page 59

•

Closing the Junos XML Protocol Session on page 59

Exchanging Initialization PIs and Tag Elements

After the client application establishes a connection to a Junos XML protocol server, the two exchange initialization PIs and tag elements, as shown in the following example. Note that the Junos XML protocol server’s opening <junoscript> tag appears on multiple lines for legibility only.Neither theJunos XML protocol server norclient applications insert a newline character into the list of attributes. Also, in an actual exchange, the

JUNOS-releasevariable isreplaced by a value such as 10.3R1 for the initialversion of Junos

OS Release 10.3. For a detailed discussion of the <?xml?> PI and opening <junoscript> tag, see “Starting the Junos XML Protocol Session” on page 38.

Chapter 3: Controlling the Junos XML Management Protocol Session

Sending an Operational Request

The client application now emits the <get-chassis-inventory> tag element to request information about the device’s chassis hardware. The Junos XML protocol server returns the requested information in the <chassis-inventory> tag element.

Locking the Configuration

The client application then prepares to create a new privilege class called network-mgmt at the [editsystemlogin class] hierarchylevel.It begins by usingthe <lock-configuration/>

Client Application Junos XML Protocol Server

<rpc>

<lock-configuration/>

</rpc>

<rpc-reply xmlns:junos="URL"> </rpc-reply>

T1103

Client Application Junos XML Protocol Server

<rpc>

<load-configuration>

<login>

<class>

<name>network-mgmt</name> <permissions>configure</permissions> <permissions>snmp</permissions> <permissions>system</permissions>

</class>

</login>

</system>

</configuration>

</load-configuration>

</rpc>

<rpc-reply xmlns:junos="URL">

<load-configuration-results>

<load-success/>

</load-configuration-results>

</rpc-reply>

T1104

Junos 10.3 Junos XML Management Protocol Guide

tag to prevent any other users or applications from altering the candidate configuration at the same time. To confirm that the candidate configuration is locked, the Junos XML protocol server returns an <rpc-reply> and an </rpc-reply> tag with nothing between them.

Changing the Configuration

The client application emits the tag elements that add the new network-mgmt privilege class to the candidate configuration. The Junos XML protocol server returns the

<load-configuration-results> tag element to enclose a tag element that reports the

outcome of the load operation. (Understanding the meaning of these tag elements is not necessary for the purposes of this example, but for information about them, see “Changing Configuration Information” on page 103.)

Committing the Configuration

The client application commits the candidate configuration. The Junos XML protocol server returns the <commit-results> tag element to enclose tag elements that report the outcome of the commit operation (for information about these tag elements, see “Committing a Configuration” on page 133).

Client Application

<rpc>

<commit-configuration/>

</rpc>

<rpc-reply xmlns:junos="URL">

<commit-results>

<routing-engine>

<commit-success/> </routing-engine>

</commit-results>

</rpc-reply>

T1105

Junos XML Protocol Server

Unlocking the Configuration

Client Application Junos XML Protocol Server

<rpc>

<unlock-configuration/>

</rpc>

<rpc-reply xmlns:junos="URL"> </rpc-reply>

T1106

Client Application Junos XML Protocol Server

<rpc>

<request-end-session/>

</rpc>

<rpc-reply xmlns:junos="URL">

<end-session/> </rpc-reply> </junoscript>

</junoscript>

T1165

The client application unlocks (and by implication closes) the candidate configuration. As when it opens the configuration, the Junos XML protocol server confirms successful closure of the configuration only by returning an opening <rpc-reply> and closing

</rpc-reply> tag with nothing between them.

Chapter 3: Controlling the Junos XML Management Protocol Session

Closing the Junos XML Protocol Session

The client application closes the Junos XML protocol session.

Junos 10.3 Junos XML Management Protocol Guide

CHAPTER 4

Requesting Information

This chapter explains how to use the Junos XML management protocol and Junos XML API andto request information aboutthe statusand the current configuration ofa routing, switching, or security platform running Junos OS.

The tag elements for operational requests are defined in the Junos XML API and correspond to Junos OS command-line interface (CLI) operational commands, which are described in the Junos OS command references. There is a request tag element for many commands in the CLI show family of commands.

The tag element for configurationrequests is the Junos XML protocol <get-configuration> tag element. It corresponds to the CLI configuration mode show command, which is described in the Junos CLI User Guide. The Junos XML tag elements that make up the content of both the client application’s requests and the Junos XML protocol server’s responses correspond to CLI configuration statements, which are described in the Junos OS configuration guides.

In additionto information aboutthe currentconfiguration,client applications can request other configuration-related information, including an XML schema representation of the configurationhierarchy, information about previouslycommitted(rollback) configurations, or information about the rescue configuration.

This chapter discusses the following topics:

•

Overview of the Request Procedure on page 62

•

Requesting Operational Information on page 62

•

Requesting Configuration Information on page 64

•

Specifying the Source and Output Format of Configuration Information on page 65

•

Specifying the Scope of Configuration Information to Return on page 81

•

Requesting an XML Schema for the Configuration Hierarchy on page 94

•

Requesting a Previous (Rollback) Configuration on page 97

•

Comparing Two Previous (Rollback) Configurations on page 99

•

Requesting the Rescue Configuration on page 100

Junos 10.3 Junos XML Management Protocol Guide

Overview of the Request Procedure

To request information fromthe Junos XML protocol server, a client application performs the procedures described in the indicated sections:

1. Establishes a connection to the Junos XML protocol server on the routing, switching,

or security platform, as described in “Connecting to the Junos XML Protocol Server” on page 37.

2. Opens aJunos XML protocol session, asdescribed in“Starting theJunos XMLProtocol

Session” on page 38.

3. If making configuration requests, optionally locks the candidate configuration or

creates a private copy, as described in “Locking the Candidate Configuration” on page 53 and “Creating a Private Copy of the Configuration” on page 54.

4. Makes any number of requests one at a time, freely intermingling operational and

configuration requests. See “Requesting Operational Information” on page 62 and “Requesting Configuration Information” on page 64.

The application can also intermix requests with configuration changes, which are described in “Changing Configuration Information” on page 103.

5. Accepts the tag stream emitted by the Junos XML protocol server in response to

each request and extracts its content,as describedin “Parsing theJunos XML Protocol Server Response” on page 48.

6. Unlocks the candidate configuration if it is locked, as described in “Unlocking the

Candidate Configuration” on page 54. Other users and applications cannot change the configuration while it remains locked.

7. Ends the Junos XML protocol session and closes the connection to the device, as

described in “Ending a Junos XML Protocol Session and Closing the Connection” on page 55.

Requesting Operational Information

To request information about the current status of a device, a client application emits the specific tag element from the Junos XML API that returns the desired information. For example, the <get-interface-information> tag element corresponds to the

show interfaces command, the <get-chassis-inventory> tag element requests the same

information as the show chassis hardware command, and the <get-system-inventory> tag element requests the sameinformation as the show software information command.

For complete information about the operational request tag elements available in the current Junos OS Release, see the chapters in the Junos XML API Operational Reference that are titled “Mapping Between Operational Tag Elements, Perl Methods, and CLI Commands” and “Summary of Operational Request Tag Elements.”

The application encloses the request tag element in an <rpc> tag element. The syntax depends on whether the corresponding CLI command has any options:

<rpc>

Chapter 4: Requesting Information

<operational-request/>

<!- - If the command has options -->

<operational-request>

</operational-request>

</rpc>

The Junos XML protocol server encloses itsresponse inthe specificresponse tag element that corresponds to the request tag element, enclosed in an <rpc-reply> tag element:

<rpc-reply xmlns:junos="URL">

<operational-response xmlns="URL-for-DTD">

</operational-response>

</rpc-reply>

The opening tag for eachoperational response includes the xmlns attribute to define the XML namespacefor the enclosed tag elements that do not have a prefix (such as junos:) in their names. The namespace indicates which Junos XML document type definition (DTD)defines theset oftag elements inthe response.The Junos XML API defines separate DTDs for operational responses from different software modules. For instance, the DTD for interface information iscalled junos-interface.dtd and the DTD for chassis information is called junos-chassis.dtd. The division into separate DTDs and XML namespaces means that a tag element with the same name can have distinct functions depending on which DTD it is defined in.

The namespace is a URL of the following form:

http://xml.juniper.net/junos/release-code/junos-category

release-code is the standard string that represents the release of the Junos OS running

on the Junos XML protocol server device.

category specifies the DTD.

The Junos XML API Operational Reference includes the text of the Junos XML DTDs for operational responses.

Parsing the <output> Tag Element

If the Junos XML API does not define a response tag element for the type of output requested by a client application, the Junos XML protocol server encloses its response in an <output> tag element. The tag element’s contents are usually one or more lines of formatted ASCII output like that displayed by the CLI on the computer screen

For a reference page for the <output> tag element, see the Junos XML API Operational Reference.

Junos 10.3 Junos XML Management Protocol Guide

NOTE: The content and formatting of data within an <output> tag element are subject

to change, so client applications must not depend on them. Future versions of the Junos XML API will define specific response tag elements (instead of <output> tag elements) for more commands. Client applications that rely on the content of <output> tag elements will not be able to interpret the output from future versions of the Junos XML API.

Requesting Configuration Information

To request information abouta configuration ona routing,switching, orsecurity platform, a clientapplication encloses the<get-configuration> tag element in an <rpc> tag element. By setting optional attributes, theclient application canspecify the source and formatting of the configuration information returned by the Junos XML protocol server. By including the appropriate optional child tag elements, the application can request the entire configuration or specific portions of the configuration. The basic syntax is as follows:

<rpc>

<get-configuration [optional attributes]/>

<get-configuration [optional attributes]>

</configuration>

</get-configuration>

</rpc>

NOTE: If the client application locksthe candidateconfiguration beforemaking requests, it needs to unlock it after making its read requests. Other users and applications cannot change the configurationwhile it remains locked.For more information, see “Exchanging Information with the Junos XML Protocol Server” on page 45.

The Junos XML protocol server encloses its replyin an<rpc-reply> tag element.It includes attributes with the junos: prefix in the opening <configuration> tag to indicate when the configuration was last changed or committed and who committed it (the attributes appear on multiple lines in the syntax statement only for legibility). For more information about them,see “Requesting Information from the Committed orCandidateConfiguration” on page 65:

<rpc-reply xmlns:junos="URL">

<configuration junos:(changed | commit)-seconds="seconds" \

junos:(changed | commit)-localtime="YYYY-MM-DD hh:mm:ss TZ" \ [junos:commit-user="username"]>

</configuration>

<configuration-text>

Chapter 4: Requesting Information

</configuration-text>

</rpc-reply>

If a Junos XML tag element is returned within an <undocumented> tag element, the corresponding configuration element is not documented in the Junos OS configuration guides or officially supported by Juniper Networks. Most often, the enclosed element is used fordebugging only by support personnel. In a smallernumber of cases, the element is no longer supported or has been moved to another area of the configuration hierarchy, but appears in the current location for backward compatibility.

For reference pages for the <configuration>, <configuration-text>, and <undocumented> tag elements, see the Junos XML API Operational Reference.

Applications can also request other configuration-related information, including an XML schema representation of the configuration hierarchy or information about previously committed configurations. For more information, see the following sections:

•

Requesting an XML Schema for the Configuration Hierarchy on page 94

•

Requesting a Previous (Rollback) Configuration on page 97

•

Comparing Two Previous (Rollback) Configurations on page 99

•

Requesting the Rescue Configuration on page 100

The following sections describe how a client application specifies the source, format, and amount of information returned by the Junos XML protocol server:

•

Specifying the Source and Output Format of Configuration Information on page 65

•

Specifying the Scope of Configuration Information to Return on page 81

Specifying the Source and Output Format of Configuration Information

By including optional attributes when requesting configuration information, a client application can specify the source and formatting of the output returned by the Junos XML protocol server, as described in the following sections:

•

Requesting Information from the Committed or Candidate Configuration on page 65

•

Requesting Output as Formatted ASCII Text or Junos XML Tag Elements on page 68

•

Requesting a Change Indicator for Configuration Elements on page 70

•

Requesting an Indicator for Identifiers on page 73

•

Specifying the Output Format for Configuration Groups on page 74

Requesting Information from the Committed or Candidate Configuration

To request information from the candidate configuration, the application either includes the database="candidate" attribute or omits the attribute completely (information from the candidate configuration is the default):

<rpc>

<get-configuration/>

Junos 10.3 Junos XML Management Protocol Guide

<get-configuration>

</get-configuration>

</rpc>

To request information from the active configuration—the one most recently committed on the device—a client application includes the database="committed" attribute in the

<get-configuration/> tag or opening <get-configuration> tag:

<rpc>

<get-configuration database="committed"/>

<get-configuration database="committed">

</get-configuration>

</rpc>

For information aboutthe tagelements to enclosein the <get-configuration> tag element, see “Specifying the Scope of Configuration Information to Return” on page 81.

The Junos XML protocol server encloses its response in the <rpc-reply> tag element and either the <configuration> tag element (for Junos XML-tagged output) or

<configuration-text> tag element (for formatted ASCII output).

When returning information from thecandidate configuration as Junos XML tag elements, the Junos XML protocolserver includes attributes in the opening <configuration> tag that indicate when the configuration last changed (they appear on multiple lines here only for legibility):

<rpc-reply xmlns:junos="URL">

<configuration junos:changed-seconds="seconds" \

junos:changed-localtime="YYYY-MM-DD hh:mm:ss TZ">

</configuration>

</rpc-reply>

junos:changed-localtime represents the time of the last change as the date and time in

the device’s local time zone.

junos:changed-seconds represents the time of the last change as the numberof seconds

since midnight on 1 January 1970.

When returning information from the active configuration as Junos XML tag elements, the Junos XML protocolserver includes attributes in the opening <configuration> tag that indicate when the configuration was committed (they appear on multiple lines here only for legibility):

<rpc-reply xmlns:junos="URL">

<configuration junos:commit-seconds="seconds" \

junos:commit-localtime="YYYY-MM-DD hh:mm:ss TZ" \ junos:commit-user="username">

</configuration>

Client Application Junos XML Protocol Server

<rpc>

<get-configuration database="committed"/>

</rpc>

<rpc-reply xmlns:junos="URL">

<configuration \

junos:commit-seconds="seconds" \ junos:commit-localtime="timestamp" \

junos:commit-user="username"> <version>JUNOS-version</version> <system>

<host-name>big-router</host-name>

<!- - other children of <system>- -> </system> <!- - other children of <configuration>- ->

</configuration>

</rpc-reply>

T1185

Chapter 4: Requesting Information

</rpc-reply>

junos:commit-localtime represents the commit time as the date and time in the device’s

local time zone.

junos:commit-seconds represents the commit time as the number of seconds since

midnight on 1 January 1970.

junos:commit-user specifies the Junos OS username of the user whorequestedthe commit

operation.

The database attribute in the application’s request can be combined with one or more of thefollowing attributes inthe <get-configuration/> tag or opening <get-configuration> tag:

•

changed, which is described in “Requesting a Change Indicator for Configuration

Elements” on page 70

•

format, which is described in “Requesting Output as Formatted ASCII Text or Junos

XML Tag Elements” on page 68

•

inherit and optionally groups, which are described in “Specifying the Output Format

for Configuration Groups” on page 74

The application can also include the database attribute after requesting an indicator for identifiers (as described in “Requesting an Indicator for Identifiers” on page 73).

The following example shows how to request the entire committed configuration. In actual output, the JUNOS-version variable is replaced by a value such as 10.3R1 for the initial version of Junos OS Release 10.3.

Junos 10.3 Junos XML Management Protocol Guide

Requesting Output as Formatted ASCII Text or Junos XML Tag Elements

To request that the Junos XML protocol server return configuration information in Junos XML-tagged output, the client application either includes the format="xml" attribute in the <get-configuration/> tag or opening <get-configuration> tag or omits the attribute completely. The Junos XML protocol server returns Junos XML-tagged output by default.

<rpc>

<get-configuration/>

<get-configuration>

</get-configuration>

</rpc>

To request that the Junos XML protocol server return configuration information as formatted ASCII text instead of tagging it with Junos XML tag elements, the client application includes the format="text" attribute in the <get-configuration/>tag oropening

<get-configuration> tag. It encloses the request in an <rpc> tag element:

<rpc>

<get-configuration format="text"/>

<get-configuration format="text">

</get-configuration>

</rpc>

For information aboutthe tagelements to enclosein the <get-configuration> tag element, see “Specifying the Scope of Configuration Information to Return” on page 81.

NOTE: Regardless of which output format they request, client applications use Junos

XML tag elements to represent the configurationelement todisplay.The format attribute controls the format of the Junos XML protocol server’s output only.

When the application requests Junos XML tag elements, the Junos XML protocol server encloses its output in <rpc-reply> and <configuration> tag elements. For information about the attributes in the opening <configuration> tag, see “Requesting Information from the Committed or Candidate Configuration” on page 65.

<rpc-reply xmlns:junos="URL">

</configuration>

</rpc-reply>

Chapter 4: Requesting Information

When the application requests formatted ASCII output, the Junos XML protocol server formats its response in the same way that the CLI show configuration command displays configuration data—it uses the newline character, tabs, braces, and square brackets to indicate the hierarchical relationships between configuration statements. The server encloses formatted ASCII configuration statements in <rpc-reply> and

<configuration-text> tag elements:

<rpc-reply xmlns:junos="URL">

<configuration-text>

</configuration-text>

</rpc-reply>

The format attribute can be combined with one or more of the following other attributes in the <get-configuration/> tag or opening <get-configuration> tag:

•

database, which is described in “Requesting Information from the Committed or

Candidate Configuration” on page 65

•

inherit and optionally groups, which are described in “Specifying the Output Format

for Configuration Groups” on page 74

It does notmake sense tocombine theformat="text" attributewith the changed attribute (described in “Requesting a Change Indicator for Configuration Elements” on page 70) or to include it after requesting an indicator for identifiers (described in “Requesting an Indicator for Identifiers” on page 73). The change and identifier indicators appear only in Junos XML-tagged output, which is the default output format.

An application can request Junos-XML tagged output or formatted ASCII text for the entire configuration or any portion ofit. For instructionson specifying the amount of data to return, see “Specifying the Scope of Configuration Information to Return” on page 81.

The following example shows how to request formatted ASCII output from the

[edit policy-options] hierarchy level in the candidate configuration.

Client Application Junos XML Protocol Server

<rpc>

<get-configuration format="text">

<policy-options/>

</configuration>

</get-configuration>

</rpc>

<rpc-reply xmlns:junos="URL">

<configuration-text>

policy-options {

policy-statement load-balancing-policy {

from {

route-filter 192.168.10/24 orlonger;

route-filter 10.114/16 orlonger; } then {

load-balance per-packet; }

}

</configuration-text>

</rpc-reply>

T1121

Junos 10.3 Junos XML Management Protocol Guide

Requesting a Change Indicator for Configuration Elements

To request that the Junos XML protocol server indicate which configuration elements have changed sincethe last commit,a clientapplication includes thechanged="changed" attribute in the <get-configuration/> tag or opening <get-configuration> tag. It encloses the request in an <rpc> tag element:

<rpc>

<get-configuration changed="changed"/>

<get-configuration changed="changed">

</get-configuration>

</rpc>

For information aboutthe tagelements to enclosein the <get-configuration> tag element, see “Specifying the Scope of Configuration Information to Return” on page 81.

The Junos XML protocol server indicates which elements have changed by including the

junos:changed="changed" attribute in the opening tag of every parent tag element in the

path to the changed configuration element. If the changed configuration element is represented by a single (empty) tag, the junos:changed="changed" attribute appears in the tag. If the changed element is represented by a container tag element, the

junos:changed="changed" attribute appears in the opening container tag and also in the

opening tag for each child tag element enclosed in the container tag element.

Chapter 4: Requesting Information

The Junos XML protocol server encloses its response in <rpc-reply> and <configuration> tag elements. For information aboutthe standard attributes inthe opening <configuration> tag, see “Requesting Information from the Committed or Candidate Configuration” on page 65.

<rpc-reply xmlns:junos="URL">

<first-child-of-element junos:changed="changed"> <second-child-of-element junos:changed="changed">

</element>

</configuration>

</rpc-reply>

NOTE: When a commit operation succeeds, the Junos XML protocol server removes the junos:changed="changed" attribute from all tag elements. However, if warnings are generated during the commit, the attribute is not removed. In this case, the

junos:changed="changed" attribute appears on tag elements that changed before the

commit as well as those that changed after the commit.

An example of a commit-time warning is the message explaining that a configuration element will not actually apply until the device is rebooted. The warning appears in the tag string that the Junos XML protocol server returns to confirm the success of the commit, enclosed in an <xnm:warning> tag element.

To remove the junos:changed="changed" attribute from elements that changed before the commit, the client application must take any action necessary to eliminate the cause of the warning, and commit the configuration again.

The changed attributecan be combinedwith oneor moreof the following otherattributes in the <get-configuration/> tag or opening <get-configuration> tag:

•

database, which is described in “Requesting Information from the Committed or

CandidateConfiguration”on page65. Request change indicators in either thecandidate or active configuration:

•

When the database="candidate" attribute is included or the database attribute is omitted, the output is from the candidate configuration. Elements added to the candidate configuration after the last commit operation are marked with the

junos:changed="changed" attribute.

Client Application Junos XML Protocol Server

<rpc>

<get-configuration changed="changed">

</system>

</configuration>

</get-configuration>

</rpc>

<rpc-reply xmlns:junos="URL">

<configuration junos:changed-seconds="seconds" \

junos:changed-localtime="timestamp" junos:changed="changed">

<file>

<name>messages</name> <contents>

</contents> </file> <file junos:changed="changed">

<name junos:changed="changed">interactive-commands</name>

<name junos:changed="changed">interactive-commands</name> <notice junos:changed="changed"/>

</contents> </file>

</syslog>

</system>

</configuration>

</rpc-reply>

T1186

Junos 10.3 Junos XML Management Protocol Guide

•

When the database="committed" attribute is included, the output is from the active configuration.Elements added to the activeconfigurationby themost recentcommit are marked with the junos:changed="changed" attribute.

•

inherit and optionally groups, which are described in “Specifying the Output Format

for Configuration Groups” on page 74.

It doesnot makesense tocombine thechanged attribute with the format="text" attribute. The junos:changed="changed" attributeappears only inJunos XML-tagged output, which is the default output format.

The application can also include the changed attribute after requesting an indicator for identifiers (as described in “Requesting an Indicator for Identifiers” on page 73).

The following example shows howto request change indicators for configuration elements at the [edit system syslog] hierarchy level in the candidate configuration. The output indicates that a log file called interactive-commands has been configured since the last commit.

Requesting an Indicator for Identifiers

To request that the Junos XML protocol server indicate whether a child configuration element is an identifier for its parent element, a client application includes the

junos:key="key" attribute in the opening <junoscript> tag for the Junos XML protocol

session, which appears here on two lines for legibility only:

<junoscript version="version" hostname="hostname" junos:key="key"

release="release-code">

For more information aboutthe <junoscript>tag, see “Emitting the Opening <junoscript> Tag” on page 40.

When the identifier indicator is requested, the Junos XML protocol server includes the

junos:key="key" attribute in the opening tag for each identifier. As always, the Junos XML

protocol server encloses its response in <rpc-reply> and <configuration> tag elements. For information about the attributes in the opening <configuration> tag, see “Requesting Informationfrom the Committed or CandidateConfiguration”on page65. Inthe following, the identifier tag element is called <name>:

<rpc-reply xmlns:junos="URL">

Chapter 4: Requesting Information

<name junos:key="key">identifier</name>  </object>

</configuration>

</rpc-reply>

The client application can include one or more of the following other attributes in the

<get-configuration/> tagor opening <get-configuration> tag whenthe junos:key attribute

is included in the opening <junoscript> tag:

•

changed, which is described in “Requesting a Change Indicator for Configuration

Elements” on page 70

•

database, which is described in “Requesting Information from the Committed or

Candidate Configuration” on page 65

•

inherit and optionally groups, which are described in “Specifying the Output Format

for Configuration Groups” on page 74

When requesting an indicator for identifiers, it does not make sense to include the

format="text" attribute in the <get-configuration> tag element (as described in

“Requesting Output as Formatted ASCII Text or Junos XML Tag Elements” on page 68). The junos:key="key" attribute appears only in Junos XML-tagged output, which is the default output format.

The following example shows how indicators for identifiers appear on configuration elements at the [edit interfaces] hierarchy level in the candidate configuration when the

Client Application Junos XML Protocol Server

<?xml version="1.0" encoding="us-ascii"?> <?xml version="1.0" encoding="us-ascii"?> <junoscript version="1.0" \ <junoscript version="1.0" hostname="router1" \

junos:key="key" \ os="JUNOS" release="JUNOS-release" \ release="JUNOS-release"> xmlns="URL"xmlns:junos=" URL" \

xmlns:xnm="URL">

<rpc>

<get-configuration>

</configuration>

</get-configuration>

</rpc>

<rpc-reply xmlns:junos="URL">

<configuration junos:changed-seconds="seconds" \

junos:changed-localtime="timestamp">

<!- - tag elements for other interfaces- -> <interface>

<inet>

</address>

</inet>

</family>

</unit> </interface> <!- - tag elements for other interfaces- ->

</interfaces>

</configuration>

</rpc-reply>

T1187

Junos 10.3 Junos XML Management Protocol Guide

junos:key="key"attribute is includedin the opening <junoscript> tag emittedby theclient

application for the session. The two opening <junoscript> tags appear on multiple lines for legibility only. Neither client applications nor the Junos XML protocol server insert newline characters within tags. Also, for brevity the output includes just one interface, the loopback interface lo0.

Specifying the Output Format for Configuration Groups

The <groups> tag element corresponds to the [edit groups] configuration hierarchy. It encloses tag elements representing configuration groups, each of which contains a set of configuration statements that are appropriate at multiple locations in the hierarchy. Use the apply-groups configuration statement or <apply-groups> tag element to insert a configuration group at the appropriate location, achieving the same effect as directly inserting the statements defined in the group. The section of configuration hierarchy to which a configuration group is applied is said to inherit the group’s statements.

In addition to the groups defined at the [edit groups] hierarchy level, the Junos OS predefines a group called junos-defaults. This group includes configuration statements judged appropriate for basic operations on any routing, switching, or security platform. By default, the statements in this group do not appear in the output of CLI commands that display the configuration, nor in theoutput returnedby theJunos XML protocol server for the <get-configuration> tag element. For more information about user-defined configuration groups and the junos-defaults group, see the Junos CLI User Guide.

Chapter 4: Requesting Information

The following sections explain howto specify the output formatfor configurationelements that are defined in configuration groups:

•

Specifying Whether Configuration Groups Are Displayed Separately on page 75

•

Displaying the Source Group for Inherited Configuration Elements on page 76

•

Examples: Specifying Output Format for Configuration Groups on page 78

Specifying Whether Configuration Groups Are Displayed Separately

By default, the Junos XML protocol server displays the tag element for each user-defined configuration group as a child of the <groups> tag element, instead of displaying them as children of the elements to which they are applied. This display mode parallels the default behavior of the CLI configuration mode show command, which displays the

[edit groups] hierarchy as a separate hierarchy in the configuration.

To request that the Junos XML protocol server not display the<groups> or <apply-groups> tag elements separately, but instead enclose tag elements inherited from user-defined groups withinthe inheriting tag elements,a clientapplication includes the inherit="inherit" attribute in the <get-configuration/> tag or opening <get-configuration> tag. It encloses the request in an <rpc> tag element:

<rpc>

<get-configuration inherit="inherit"/>

<get-configuration inherit="inherit">

</get-configuration>

</rpc>

To request that the Junos XML protocol server include tag elements that are inherited from the junos-defaults group as well as user-defined configuration groups, the client application includes the inherit="defaults" attribute in the <get-configuration/> tag or opening <get-configuration> tag:

<rpc>

<get-configuration inherit="defaults"/>

<get-configuration inherit="defaults">

</get-configuration>

</rpc>

For information aboutthe tagelements to enclosein the <get-configuration> tag element, see “Specifying the Scope of Configuration Information to Return” on page 81.

When the client includes the inherit="inherit" attribute, the output includes the same information as the output from the following CLI configuration mode command, and does not include configuration elements inherited from the junos-defaults group:

user@host# show | display inheritance | except ##

Junos 10.3 Junos XML Management Protocol Guide

When the client includes the inherit="defaults" attribute, the output includes the same information as the output from the following CLI configuration mode command:

user@host# show | display inheritance defaults | except ##

In both cases, the Junos XML protocol server encloses its output in the <rpc-reply> tag element and either the <configuration> tag element (for Junos XML-tagged output) or

<configuration-text> tag element (for formatted ASCII output). For information about

the attributes in the opening <configuration> tag, see “Requesting Information from the Committed or Candidate Configuration” on page 65.

<rpc-reply xmlns:junos="URL">

</configuration>

<configuration-text>

</configuration-text>

</rpc-reply>

The inherit attribute can be combined with one or more of the following attributes in the

<get-configuration/> tag or opening <get-configuration> tag:

•

changed, which is described in “Requesting a Change Indicator for Configuration

Elements” on page 70

•

database, which is described in “Requesting Information from the Committed or

Candidate Configuration” on page 65

•

format, which is described in “Requesting Output as Formatted ASCII Text or Junos

XML Tag Elements” on page 68

•

groups, which is described in “Displaying the Source Group for Inherited Configuration

Elements” on page 76

The application can also include the inherit attribute after requesting an indicator for identifiers (as described in “Requesting an Indicator for Identifiers” on page 73).

Displaying the Source Group for Inherited Configuration Elements

To request that the Junos XML protocol server indicate the configuration group from which configuration elements are inherited, a client application combines the

groups="groups" attribute with the inherit attribute in the <get-configuration/> tag or

opening <get-configuration> tag. It encloses the request in an <rpc> tag element:

<rpc>

<get-configuration inherit="(defaults | inherit)" groups="groups"/>

<get-configuration inherit="(defaults | inherit)" groups="groups">

</get-configuration>

Chapter 4: Requesting Information

</rpc>

For information aboutthe tagelements to enclosein the <get-configuration> tag element, see “Specifying the Scope of Configuration Information to Return” on page 81.

When the groups="groups" attribute is combined with the inherit="inherit" attribute, the output includes the same information as the output from the following CLI configuration mode command, and does not include configuration elements inherited from the

junos-defaults group:

user@host# show | display inheritance

When the groups="groups" attribute is combined with the inherit="defaults" attribute, the output includes the same information as the output from the following CLI configuration mode command:

user@host# show | display inheritance defaults

The inherit and groups attributes canbe combined withone ormore of the following other attributes in the <get-configuration/> tag or opening <get-configuration> tag:

•

changed, which is described in “Requesting a Change Indicator for Configuration

Elements” on page 70.

•

database, which is described in “Requesting Information from the Committed or

Candidate Configuration” on page 65.

•

format, which is described in “Requesting Output as Formatted ASCII Text or Junos

XML Tag Elements” on page 68. The application can request either Junos XML-tagged or formatted ASCII output:

If the output is tagged with Junos XML tag elements (the format="xml" attribute is

•

included or the format attribute is omitted), the Junos XML protocol server includes the junos:group="source-group" attribute inthe opening tags ofconfigurationelements that are inherited from configuration groups and encloses its response in

<configuration> and <rpc-reply> tag elements. For information about the attributes

in theopening <configuration> tag,see “Requesting Information fromthe Committed or Candidate Configuration” on page 65.

<rpc-reply xmlns:junos="URL">

<inherited-element junos:group="source-group">

<inherited-child-of-inherited-element junos:group="source-group">

</inherited-child-of-inherited-element>

</inherited-element>

</configuration>

</rpc-reply>

If the output is formatted ASCII text (the format="text" attribute is included), the

•

Junos XML protocol server encloses its response in <configuration-text> and

<rpc-reply> tag elements, and inserts three commented lines immediately above

each inherited element, as in the following:

<rpc-reply xmlns:junos="URL">

Junos 10.3 Junos XML Management Protocol Guide

<configuration-text>

*/ For each inherited element */

/* parent levels for the element */

## ## 'inherited-element' was inherited from group 'source-group' ## inherited-element {

}

/* closing braces for parent levels for the element */

</configuration-text>

</rpc-reply>

The application can also include the inherit and groups attributes after requesting an indicator for identifiers (as described in “Requesting an Indicator for Identifiers” on page 73).

## ## 'inherited-child' was inherited from group 'source-group' ## inherited-child {

... child statements of inherited-child ...

}

Examples: Specifying Output Format for Configuration Groups

The following sample configuration hierarchy defines a configuration group called

interface-group. The apply-groups statement applies the statements in the group at the [edit interfaces] hierarchy level:

[edit] groups {

interface-group {

interfaces {

so-1/1/1 {

encapsulation ppp;

}

} } apply-groups interface-group; interfaces {

fxp0 {

unit 0 {

family inet {

address 192.168.4.207/24;

}

} }

When the inherit attribute is not included in the <get-configuration/> tag, the output includes the <groups> and <apply-groups> tag elements asseparateitems. The <groups> tag element enclosesthe tagelements defined inthe interface-group configuration group. The placement of the <apply-groups> tag element directly above the <interfaces> tag element indicates that the [edit interfaces] hierarchy inherits the statements defined in the interface-group configuration group.

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

XML and Junos XML Management Protocol Conventions Overview

Request and Response Tag Elements

Child Tag Elements of a Request Tag Element

Child Tag Elements of a Response Tag Element

Spaces, Newline Characters, and Other White Space

XML Comments

XML Processing Instructions

Predefined Entity References

Mapping Commands to Junos XML Tag Elements

Mapping for Command Options with Variable Values

Mapping for Fixed-Form Command Options

Mapping Configuration Statements to Junos XML Tag Elements

Mapping for Hierarchy Levels and Container Statements

Mapping for Objects That Have an Identifier

Mapping for Single-Value and Fixed-Form Leaf Statements

Mapping for Leaf Statements with Multiple Values

Mapping for Multiple Options on One or More Lines

Mapping for Comments About Configuration Statements

Using the Same Configuration Tag Elements in Requests and Responses

Client Application’s Role in a Junos XML Protocol Session

Establishing a Junos XML Management Protocol Session

Supported Access Protocols

Prerequisites for Establishing a Connection

Prerequisites for All Access Protocols

Prerequisites for Clear-Text Connections

Prerequisites for SSH Connections

Prerequisites for Outbound SSH Connections

Prerequisites for SSL Connections

Prerequisites for Telnet Connections

Connecting to the Junos XML Protocol Server

Connecting to the Junos XML Protocol Server from the Client Application

Connecting to the Junos XML Protocol Server from the CLI

Starting the Junos XML Protocol Session

Emitting the Initialization PI and Tag

Emitting the <?xml?> PI

Emitting the Opening <junoscript> Tag

Parsing the Initialization PI and Tag from the Junos XML Protocol Server

Parsing the Junos XML Protocol Server’s <?xml?> PI

Parsing the Junos XML Protocol Server’s Opening <junoscript> Tag

Verifying Software Compatibility

Supported Software Versions

Authenticating with the Junos XML Protocol Server

Submitting an Authentication Request

Providing the Password with the Username

Providing Only the Username

Interpreting the Authentication Response

Server Response When Authentication Succeeds

Server Response When Authentication Fails

Exchanging Information with the Junos XML Protocol Server

Sending a Request to the Junos XML Protocol Server

Request Classes

Operational Requests

Configuration Information Requests

Configuration Change Requests

Including Attributes in the Opening <rpc> Tag

Parsing the Junos XML Protocol Server Response