Start a Junos XML Protocol Session

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

The attributes are as follows:

• 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

For a list of the attribute values that are acceptable in the current version of the Junos XML management protocol, see Verifying Software Compatibility.

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/ .

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 and immediately closes the session and connection.

The client application then emits its opening <junoscript> tag, which has the following syntax:

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 release attribute, use the standard notation for Junos OS version numbers. For example, the value 20.4R1 represents the initial version of Junos OS Release 20.4.

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 network device is running the initial version of Junos OS Release 20.4.

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:

Note:

For more information about the <xnm:error> tag, see Handling an Error or Warning in Junos XML Protocol Sessions.

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:

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.

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):

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 20.4R1 represents the initial version of Junos OS Release 20.4.
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 <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 a release of the Junos OS. For example, the value 20.4R1 represents the initial version of Junos OS Release 20.4.

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.

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.

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

Software and Versions	PI or Tag	Attribute
XML 1.0	<?xml?>	version="1.0"
ANSI-standardized 7-bit ASCII character set	<?xml?>	encoding="us-ascii"
Junos XML protocol 1.0	<junoscript>	version="1.0"
Junos OS Release	<junoscript>	release="m.nZb" For example:release="10.3R1"