Understanding the Session Protocol in Automation Scripts

The Junos XML management protocol is a Juniper Networks proprietary protocol that is used to request information from and configure devices running Junos OS. The NETCONF XML management protocol is a standard that is used to request and change configuration information on a routing, switching, or security device. The NETCONF protocol is defined in RFC 6241, NETCONF Configuration Protocol, which is available at http://www.ietf.org/rfc/rfc6241.txt .

The jcs:open() function, which is used in SLAX and XSLT scripts to establish a connection with a device, includes the option to create a session either with the Junos XML protocol server on devices running Junos OS or with the NETCONF server on devices where NETCONF service over SSH is enabled. Prior to Junos OS Release 11.4, the function supported only sessions with the Junos XML protocol server on devices running Junos OS. The additional support for NETCONF sessions enables automation scripts to configure and manage devices in a multi-vendor environment.

The jcs:open() function supports the following session protocol types:

• junoscript—Session with the Junos XML protocol server on a routing, switching, or security device running Junos OS. This session type supports the operations defined in the Junos XML protocol and the Junos XML API, which are used to configure devices running Junos OS or to request information about the device configuration or operation. This is the default session type.

• netconf—Session with the NETCONF XML protocol server on a routing, switching, or security device over an SSHv2 connection. The device to which the connection is made must be enabled for NETCONF service over SSH. NETCONF over SSH is described in RFC 4742, Using the NETCONF Configuration Protocol over Secure SHell (SSH), which is available at http://www.ietf.org/rfc/rfc4742.txt .

• junos-netconf—Proprietary session with the NETCONF XML protocol server over an SSHv2 connection on a routing, switching, or security device running Junos OS.

The NETCONF server on a device running Junos OS has the additional capabilities defined in http://xml.juniper.net/netconf/junos/1.0 . The NETCONF server on these devices supports NETCONF XML protocol operations, most Junos XML protocol operations, and the tag elements defined in the Junos XML API. For netconf and junos-netconf sessions with devices running Junos OS, you should use only native NETCONF XML protocol operations and the extensions available in the Junos XML protocol for configuration functions as documented in the NETCONF XML Management Protocol Developer Guide.

The syntax for the jcs:open() function when specifying a session protocol is:

SLAX Syntax

var $connection = jcs:open(remote-hostname, session-options);

XSLT Syntax

<xsl:variable name="connection" select="jcs:open(remote-hostname, session-options)"/>

The session-options parameter is an XML node-set that specifies the session type and connection parameters. The session type is one of three values: junoscript, netconf, or junos-netconf. If you do not specify a session type, the default is junoscript, which opens a session with the Junos XML protocol server on a device running Junos OS. The format of the node-set is:

var $session-options := {
           <method> ("junoscript" | "netconf" | "junos-netconf");
           <username> "username";
           <passphrase> "passphrase";
           <password> "password";
           <port> "port-number";
           <instance> "routing-instance-name";
           <routing-instance> "routing-instance-name";
       } 

If you do not specify a username and it is required for the connection, the script uses the local name of the user executing the script. The <passphrase> and <password> elements serve the same purpose. If you do not specify a passphrase or password element and it is required for authentication, you should be prompted for one during script execution by the device to which you are connecting.

Optionally, you can specify the server port number for netconf and junos-netconf sessions. The default NETCONF server port number is 830. If you do not specify a port number for a netconf or junos-netconf session, jcs:open() connects to the NETCONF server using port 830. However, if you specify a port number, jcs:open() connects to the given port instead. Specifying a port number has no impact on junoscript sessions, which are always established over SSH port 22.

To redirect the SSH connection to originate from within a specific routing instance, include the instance or routing-instance element and the routing instance name. The routing instance must be configured at the [edit routing-instances] hierarchy level. The remote device must be reachable either using the routing table for that routing instance or from one of the interfaces configured under that routing instance. The instance and routing-instance elements serve the same purpose.

To verify the protocol for a specific connection, call the jcs:get-protocol(connection) extension function and pass the connection handle as the argument. The function returns “junoscript”, “netconf”, or “junos-netconf”, depending on the session type.

During session establishment with a NETCONF server, the client application and NETCONF server each emit a <hello> tag element to specify which operations, or capabilities, they support from among those defined in the NETCONF specification or published as proprietary extensions. In netconf and junos-netconf sessions, you can retrieve the session capabilities of the NETCONF server by calling the jcs:get-hello(connection) extension function.

For example, the NETCONF server on a typical device running Junos OS might return the following capabilities:

<hello>
  <capabilities>
     <capability>urn:ietf:params:xml:ns:netconf:base:1.0</capability>
     <capability>
       urn:ietf:params:xml:ns:netconf:capability:candidate:1.0
     </capability>
     <capability>
       urn:ietf:params:xml:ns:netconf:capability:confirmed-commit:1.0
     </capability>
     <capability>
       urn:ietf:params:xml:ns:netconf:capability:validate:1.0
     </capability>
     <capability>
       urn:ietf:params:xml:ns:netconf:capability:url:1.0?protocol=http,ftp,file
     </capability>
     <capability>http://xml.juniper.net/netconf/junos/1.0</capability>
     <capability>http://xml.juniper.net/dmi/system/1.0</capability>
  </capabilities>
  <session-id>20826</session-id>
</hello>