Establishing a Junos XML Management Protocol Session

The Junos XML protocol server communicates 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 rules defined 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 the Junos XML protocol server using one of the protocols listed in Supported Access Protocols. To authenticate with the Junos XML protocol server, they use either a Junos XML protocol-specific mechanism or 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:

For an example of a complete Junos XML protocol session, see Example of a Junos XML Protocol Session.

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.

Table 5: Supported Access Protocols and Authentication Mechanisms

Access Protocol	Authentication Mechanism
clear-text, a Junos XML protocol-specific access protocol for sending unencrypted text over a Transmission Control Protocol (TCP) connection	Junos XML protocol-specific
SSH	Standard SSH
Outbound SSH	Outbound SSH
Secure Sockets Layer (SSL)	Junos XML protocol-specific
Telnet	Standard Telnet

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 a Connection. For authentication instructions, see Authenticating with the Junos XML Protocol Server.

Prerequisites for Establishing a Connection

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

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

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.

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.

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-passwordNew password: passwordRetype new password: password

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
Repeat the preceding steps on each device where the client application establishes Junos XML protocol sessions.
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:

Verify that the application 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.
Satisfy the prerequisites discussed in Prerequisites for All Access Protocols.
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
By default, the Junos XML protocol server supports up to 75 simultaneous clear-text sessions and 150 connection attempts per minute. Optionally, you can include 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 limituser@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.
Commit the configuration:
[edit]user@host# commit
Repeat Step 2 through Step 4 on each device where the client application 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:

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.
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/ .
Satisfy the prerequisites discussed in Prerequisites for All Access Protocols.
(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. Perform the following steps:
1. Working on the computer where the client application runs, issue the ssh-keygen command in a standard command shell (not the Junos OS CLI). By providing the appropriate arguments, you encode the public key with either RSA (supported by SSH versions 1 and 2) or the Digital Signature Algorithm (DSA), supported by SSH version 2. For more information, see the man page provided by your SSH vendor for the ssh-keygen command. The Junos OS uses SSH version 2 by default but also supports version 1.
  % ssh-keygen options
2. 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.
3. 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.
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
Commit the configuration:
[edit]user@host# commit
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 configure outbound SSH, you add an outbound-ssh configuration statement to the device. Once configured and committed, the device running Junos OS will begin to initiate 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:

Satisfy the prerequisites discussed in Prerequisites for All Access Protocols.
In the [edit system services ssh] hierarchy level, set the SSH protocol to v2:
```
[edit system services ssh]
set protocol-version v2
```
Generate/obtain a public/private key pair for the device running Junos OS. This key pair will be used to encrypt the data transferred across the SSH connection. For more information on generating key pairs, see the Junos System Basics Configuration Guide.
If the public key will be installed on the application management system manually, transfer the public key to the NSM server.
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;
        }
    }
}
```
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 of maintaining a current copy of the router's public key on the configuration 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 receiving a 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 to reconnect 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 clients by adding each client's IP 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.
  - retry number– Number of times the device running Junos OS attempts to establish 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 attempts to establish an outbound SSH connection before giving up. The default is 15 seconds.
Commit the configuration:
[edit]user@host# commit

To set up the configuration management server:

Satisfy the prerequisites discussed in Prerequisites for All Access Protocols.
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.
- 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/ .
(Optional) Manually install the device's public key for use with the SSH connection.
Configure the client system to receive and process initialization broadcast requests. The intialization requests use the following syntax:
- If the secret attribute is configured, the device running Junos OS will send its public SSH key along with the intialization sequence (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
```

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:

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 install a prerequisites package that includes the necessary SSL software. For instructions, see Downloading the Junos XML Protocol Perl Client and Prerequisites Package.
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/ .
Satisfy the prerequisites discussed in Prerequisites for All Access Protocols.
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

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-name is a name you choose to identify the certificate uniquely (for example, 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.

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 characters that constitute the private key and certificate, marking them as SECRET-DATA. The load-key-file keyword is not recorded in the configuration.

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 can include 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 limituser@host# set system services xnm-ssl rate-limit limit
For more information about the xnm-ssl statement, see the Junos System Basics Configuration Guide.
Commit the configuration:
[edit]user@host# commit
Repeat Step 1 on each computer where the client application runs, and Step 2 through Step 6 on each device to which the client application connects.

Prerequisites for Telnet Connections

To enable a client application to use the 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.

Verify that the application can access the Telnet software. On most operating systems, Telnet is accessible in the standard distribution.
Satisfy the prerequisites discussed in Prerequisites for All Access Protocols.
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
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

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.

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.

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:
1. Emits the initialization PI and tag, as described in Emitting the Initialization PI and Tag.
2. Authenticates with the Junos XML protocol server, as described in Authenticating with the Junos XML Protocol Server.
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.
3. Emits the initialization PI and tag, as described in Emitting the Initialization PI and Tag.

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 junoscript interactive 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. You can then type sequences of tag elements that represent operational and configuration operations, which are described in Requesting Information, Changing Configuration Information, and Committing a Configuration. 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 closes your connection instead 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.

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

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

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), 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 Supported Software Versions.

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 message and immediately closes the session and connection. For more information, see Emitting the Opening <junoscript> Tag.

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.

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 an Indicator for Identifiers.
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.
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 the client application is running on 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.

<junoscript version="1.0" hostname="client1" release="10.3R1">

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.

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

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.

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

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 a release of the Junos OS. For example, the value 10.3R1 represents 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">

Verifying Software Compatibility

Exchanging <?xml?> and <junoscript> tag 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.

Supported Software Versions

Table 6 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

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"

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

See the following sections:

Submitting an Authentication Request

The client application begins the authentication process by emitting an <rpc> tag element enclosing the <request-login> tag element. In the <request-login> tag element, it encloses 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 protocol server device, as described in Prerequisites for All Access Protocols. 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 sequence is appropriate if the application automates access to routing, switching, or security platform information and does not interact with users, or obtains the password from a user before beginning the authentication process.

Providing Only the Username

To omit the password and specify only the username, the application 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 already begun. In this case, the Junos XML protocol server returns the <challenge> tag element within an <rpc-reply> tag element to request the password associated with the username. The tag element encloses the 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><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 the username that the client application 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 Junos XML protocol session begins, as described in Starting the Junos XML Protocol Session.

Server Response When Authentication Fails

If the password 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><status>fail</status><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.