Start a 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
information emitted by the other, using it to determine whether they
can communicate successfully. Specifically, the client application
emits an <?xml?> PI and an opening <junoscript> tag. The following sections describe
how to start a Junos XML protocol session:
Emitting the <?xml?> PI
The client application begins by emitting an <?xml?> PI.
In the following example (and in all examples in this document of tag elements emitted by a client application), bold font 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 Verifying Software Compatibility.
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"?>
If the application fails to emit the <?xml?> PI before emitting the opening <junoscript> tag, the Junos XML protocol server emits an error message and immediately
closes the session and connection.
Emitting the Opening <junoscript> Tag
The client application then emits its opening <junoscript> tag, which has
the following syntax:
<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 Verifying Software Compatibility.
version |
(Required) Specifies the version of the 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 configuration element is an identifier for its parent element. The only acceptable value is "key". For more information, see Requesting Identifier Indicators for Configuration Elements Using the Junos XML Protocol. |
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 the value of the |
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 the client application is running on the
machine called client1. The release="20.4R1" attribute indicates that the switch, router, or security device
is running the initial version of Junos OS Release 20.4.
<junoscript version="1.0" hostname="client1" release="20.4R1">
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>
<!-- session end at YYYY-MM-DD hh:mm:ss TZ -->
</junoscript>
For more information about the <xnm:error> tag, see Handling an Error or Warning
in Junos XML Protocol Sessions.
Parsing the Junos XML Protocol Server’s <?xml?> PI
When the Junos XML protocol session begins, the Junos XML protocol
server emits an <?xml?> PI and an opening <junoscript> tag.
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 Verifying Software Compatibility.
| version | The version of XML with which tag elements emitted by the Junos XML 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" attribute indicates that the server is using 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" \ 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 |
| schemaLocation | The XML namespace for the XML Schema-language representation of the Junos OS 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 |
| xmlns:junos | The XML
namespace for the tag elements enclosed by the |
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 20.4. 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/20.4R1/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/20.4R1/junos" \
schemaLocation="http://xml.juniper.net/junos/20.4R1/junos" os="JUNOS" \
release="20.4R1.8" hostname="big-device" version="1.0">
Verifying Software Compatibility
Exchanging the <?xml?> and <junoscript> elements enables a client application
and the 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 software is later than that of the Junos XML protocol
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, so this is often a valid 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.
Table 1 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.
Software and Versions |
PI or Tag |
Attribute |
|---|---|---|
XML 1.0 |
|
|
ANSI-standardized 7-bit ASCII character set |
|
|
Junos XML protocol 1.0 |
|
|
Junos OS Release |
|
|