NETCONF XML Management Protocol Developer Guide
Total Page:16
File Type:pdf, Size:1020Kb
Junos® OS NETCONF XML Management Protocol Developer Guide Published 2021-09-16 ii Juniper Networks, Inc. 1133 Innovation Way Sunnyvale, California 94089 USA 408-745-2000 www.juniper.net Juniper Networks, the Juniper Networks logo, Juniper, and Junos are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered marks, 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. Junos® OS NETCONF XML Management Protocol Developer Guide Copyright © 2021 Juniper Networks, Inc. All rights reserved. The information in this document is current as of the date on the title page. YEAR 2000 NOTICE Juniper Networks hardware and software products are Year 2000 compliant. 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 The Juniper Networks product that is the subject of this technical documentation consists of (or is intended for use with) Juniper Networks software. Use of such software is subject to the terms and conditions of the End User License Agreement ("EULA") posted at https://support.juniper.net/support/eula/. By downloading, installing or using such software, you agree to the terms and conditions of that EULA. iii Table of Contents About This Guide | xvii 1 Overview NETCONF XML Management Protocol Overview | 2 NETCONF XML Management Protocol and Junos XML API Overview | 2 Advantages of Using the NETCONF XML Management Protocol and Junos XML API | 3 NETCONF and Junos XML Tags Overview | 6 XML and Junos OS Overview | 6 XML Overview | 8 XML and NETCONF XML Management Protocol Conventions Overview | 11 Map Junos OS Commands and Command Output to Junos XML Tag Elements | 16 Mapping Command Output to Junos XML Elements | 17 Mapping Commands to Junos XML Request Tag Elements | 18 Mapping for Command Options with Variable Values | 19 Mapping for Fixed-Form Command Options | 20 Map Configuration Statements to Junos XML Tag Elements | 21 Using NETCONF Configuration Response Tag Elements in NETCONF Requests and Configuration Changes | 28 2 Manage NETCONF Sessions NETCONF Session Overview | 31 NETCONF Session Overview | 31 Understanding the Client Application’s Role in a NETCONF Session | 32 Generate Well-Formed XML Documents | 33 Understanding the Request Procedure in a NETCONF Session | 34 Manage NETCONF Sessions | 36 Establish an SSH Connection for a NETCONF Session | 36 Establish an SSH Connection for a NETCONF Session | 37 iv Prerequisites for Establishing an SSH Connection for NETCONF Sessions | 37 Installing SSH Software on the Configuration Management Server | 37 Configuring a User Account for the Client Application on Devices Running Junos OS | 37 Configuring a Public/Private Key Pair or Password for the Junos OS User Account | 38 Accessing the Keys or Password with the Client Application | 40 Enabling NETCONF Service over SSH | 41 Prerequisites for Establishing an Outbound SSH Connection for NETCONF Sessions | 43 Configuring the Device Running Junos OS for Outbound SSH | 43 Installing SSH Software on the Client | 45 Receiving and Managing the Outbound SSH Initiation Sequence on the Client | 46 Enabling NETCONF Service over SSH | 46 NETCONF Sessions over Transport Layer Security (TLS) | 48 Understanding NETCONF-over-TLS Connections | 49 How to Establish a NETCONF Session over TLS | 54 Install TLS Client Software on the Configuration Management Server | 54 Obtain X.509 Certificates for the Server and Client | 55 Install the Server’s Local Certificate in the Junos OS PKI | 56 Install the CA Certificates in the Junos OS PKI | 57 Enable the NETCONF Service over TLS | 59 Configure the TLS Client-to-NETCONF Username Mapping | 59 Configure the Default NETCONF Username Mapping | 61 Configure the User Account for the NETCONF User | 61 Start the NETCONF-over-TLS Session | 62 NETCONF and Shell Sessions over Outbound HTTPS | 64 Understanding NETCONF and Shell Sessions over Outbound HTTPS | 64 How to Establish NETCONF and Shell Sessions over Outbound HTTPS | 68 Obtain an X.509 Certificate for the gRPC Server | 69 Set Up the gRPC Server | 72 Configure the User Account for the NETCONF or Shell User | 74 Configure the Outbound HTTPS Client (Junos OS Release 20.2) | 75 Configure the Outbound HTTPS Clients (Junos OS Release 20.3R1 and later) | 76 Configure the Extension Service for Outbound HTTPS on Devices Running Junos OS | 78 Start the NETCONF or Shell Session | 81 Connect to the NETCONF Server Using SSH | 83 v Start a NETCONF Session | 85 Exchanging <hello> Tag Elements | 85 Verifying Compatibility | 87 Send Requests to the NETCONF Server | 89 Operational Requests | 90 Configuration Information Requests | 91 Configuration Change Requests | 92 Parse the NETCONF Server Response | 93 Operational Responses | 94 Configuration Information Responses | 95 Configuration Change Responses | 95 Parse Response Tag Elements Using a Standard API in NETCONF and Junos XML Protocol Sessions | 96 Understanding Character Encoding on Juniper Networks Devices | 97 Handle an Error or Warning in a NETCONF Session | 98 Lock and Unlock the Candidate Configuration Using NETCONF | 100 Locking the Candidate Configuration | 101 Unlocking the Candidate Configuration | 102 Terminate a NETCONF Session | 103 End a NETCONF Session and Close the Connection | 105 Sample NETCONF Session | 105 Exchanging Initialization Tag Elements | 106 Sending an Operational Request | 106 Locking the Configuration | 107 Changing the Configuration | 108 Committing the Configuration | 109 Unlocking the Configuration | 110 Closing the NETCONF Session | 110 Configure RFC-Compliant NETCONF Sessions | 111 NETCONF Event Notifications | 116 NETCONF Event Notifications Overview | 117 vi NETCONF Event Notification Format | 118 How to Enable and Subscribe to NETCONF Event Notifications | 119 Enable the NETCONF Event Notification Service | 120 Subscribe to Receive Event Notifications | 121 Terminate the Subscription | 122 NETCONF Tracing Operations | 123 NETCONF and Junos XML Protocol Tracing Operations Overview | 123 Example: Trace NETCONF and Junos XML Protocol Session Operations | 125 Requirements | 125 Overview | 125 Configuration | 126 Verification | 128 NETCONF Protocol Operations | 131 <close-session/> | 131 <commit> | 132 <copy-config> | 134 <delete-config> | 136 <discard-changes/> | 137 <edit-config> | 138 <get> | 141 <get-config> | 143 <kill-session> | 145 <lock> | 147 <unlock> | 148 <validate> | 149 NETCONF Request and Response Tags | 151 End-of-document Character Sequence | 151 <data> | 153 vii <error-info> | 154 <hello> | 155 <ok/> | 157 <rpc> | 157 <rpc-error> | 158 <rpc-reply> | 160 <target> | 161 Junos XML Protocol Elements Supported in NETCONF Sessions | 164 <abort/> | 165 <abort-acknowledgement/> | 166 <checksum-information> | 167 <close-configuration/> | 168 <commit-configuration> | 169 <commit-results> | 174 <commit-revision-information> | 176 <database-status> | 178 <database-status-information> | 180 <end-session/> | 181 <get-checksum-information> | 182 <get-configuration> | 184 <load-configuration> | 190 <load-configuration-results> | 197 <lock-configuration/> | 198 <open-configuration> | 199 <reason> | 201 <request-end-session/> | 202 viii <routing-engine> | 203 <unlock-configuration/> | 205 <xnm:error> | 206 <xnm:warning> | 209 Junos XML Protocol Element Attributes Supported in NETCONF Sessions | 212 junos:changed-localtime | 212 junos:changed-seconds | 213 junos:commit-localtime | 214 junos:commit-seconds | 215 junos:commit-user | 216 operation | 217 replace-pattern | 219 xmlns | 221 3 Manage Configurations Using NETCONF Change the Configuration Using NETCONF | 224 Edit the Configuration Using NETCONF | 224 Upload and Format Configuration Data in a NETCONF Session | 226 Referencing Configuration Data Files | 227 Streaming Configuration Data | 229 Formatting Data: Junos XML versus CLI Configuration Statements | 231 Set the Edit Configuration Mode in a NETCONF Session | 233 Specifying the merge Data Mode | 235 Specifying the replace Data Mode | 236 Specifying the none (no-change) Data Mode | 236 Handle Errors While Editing the Candidate Configuration in a NETCONF Session | 238 Replace the Candidate Configuration Using NETCONF | 239 Using <copy-config> to Replace the Configuration | 240 Using <edit-config> to Replace the Configuration | 240 ix Rolling Back to a Previously Committed Configuration | 241 Replacing the Candidate Configuration with the Rescue Configuration | 242 Roll Back Uncommitted Changes in the Candidate Configuration Using NETCONF | 244 Delete the Configuration Using NETCONF | 245 Change Individual Configuration Elements Using NETCONF | 246 Merge Configuration Elements Using NETCONF | 247 Create Configuration Elements Using NETCONF | 250 Delete Configuration Elements Using NETCONF | 252 Deleting a Hierarchy Level or Container Object | 253 Deleting a Configuration Object That Has an Identifier | 254 Deleting a Single-Value or Fixed-Form Option from a Configuration Object | 256 Deleting Values from a Multi-value Option of a Configuration Object | 257 Replace Configuration Elements Using NETCONF | 260 Replace Patterns in Configuration Data Using the NETCONF or Junos XML Protocol | 262 Replacing Patterns Globally Within the Configuration | 263 Replacing Patterns