Configure RFC-Compliant NETCONF Sessions

Understanding RFC-Compliant NETCONF Sessions

When you use NETCONF to manage Junos devices, you can require that the NETCONF session enforce certain behaviors that are compliant with specific RFCs. You can configure Junos devices to be compliant with the following RFCs:

• RFC 4741, NETCONF Configuration Protocol

• RFC 6242, Using the NETCONF Protocol over Secure Shell (SSH)

To enforce RFC 4741 compliance, configure the rfc-compliant statement at the [edit system services netconf] hierarchy level. Configuring the rfc-compliant statement affects the following aspects of the NETCONF session:

• Namespaces emitted in NETCONF server replies

• NETCONF server replies for <get> and <get-config> operations in cases where there is no configuration data to return

• NETCONF server replies that would return both an <ok/> element and an <rpc-error> element with a severity level of warning

• NETCONF server replies for <commit> and <validate> operations

To also enforce RFC 6242 compliance, configure both the rfc-compliant and version-1.1 statements at the [edit system services netconf] hierarchy level. If you configure RFC 6242 compliance, and both peers advertise the :base:1.1 capability in the capabilities exchange, the NETCONF session uses chunked framing instead of the end-of-message character sequence (]]>]]>) for message framing. For additional details, see (RFC 6242) Chunked Framing.

The session differences are described in detail in the corresponding sections.

Benefits of RFC-Compliant Sessions

• Standards Compliance: Ensures that NETCONF communications are compliant with the latest industry standards, facilitating interoperability with other compliant systems.

• Enhanced Reliability: By using chunked framing, NETCONF messages are encoded in a way that prevents misinterpretation of character sequences within XML elements, ensuring reliable message parsing.

(RFC 4741) Namespaces

By default, the NETCONF server, sets the default namespace to the NETCONF namespace in the opening tag of the server’s reply, and NETCONF tag names are not qualified. For example:

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities>
    <capability>urn:ietf:params:netconf:base:1.0</capability>
    ...
  </capabilities>
  <session-id>27700</session-id>
<hello>


<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/15.1R1/junos">

When you configure the rfc-compliant statement, the NETCONF server does not define a default namespace in its replies. Instead, the server includes a namespace declaration for the NETCONF namespace, which is bound to the nc prefix, and qualifies all NETCONF tags in its replies with the prefix. If you set the default namespace to the NETCONF namespace in an RPC request, the server discards the default namespace and emits its reply using only the declared namespace that is bound to the nc prefix.

The following sample output shows the NETCONF server’s <hello> message and capabilities exchange when the rfc-compliant statement is configured. The <hello> tag contains the xmlns:nc declaration, and all NETCONF tags include the nc prefix.

<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <nc:capabilities>
    <nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>
    ...
  </nc:capabilities>
  <nc:session-id>27703</nc:session-id>
</nc:hello>

The following output shows a sample RPC reply when the rfc-compliant statement is configured:

<nc:rpc-reply 
    xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
    xmlns:junos="http://xml.juniper.net/junos/15.1R1/junos">
  <nc:data>
    <configuration xmlns="http://xml.juniper.net/xnm/1.1/xnm" 
          junos:changed-seconds="1417554471" 
          junos:changed-localtime="2014-12-02 13:07:51 PST">
       <!--configuration data-->
    </configuration>
    <database-status-information>
      <database-status>
        <user>root</user>
        <terminal></terminal>
        <pid>47868</pid>
        <start-time junos:seconds="1417560303">2014-12-02 14:45:03 PST</start-time>
        <edit-path></edit-path>
      </database-status>
    </database-status-information>
  </nc:data>
</nc:rpc-reply>

Starting with Junos OS Release 17.2R1, when you configure the rfc-compliant statement and request configuration data in a NETCONF session, the server sets the default namespace for the <configuration> element to the same namespace as in the corresponding YANG model.

<rpc>
  <get-config>
    <source>
      <running/>
    </source>
  </get-config>
</rpc>
]]>]]>

<nc:rpc-reply 
  xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
  xmlns:junos="http://xml.juniper.net/junos/17.2R1/junos">
<nc:data>
<configuration 
  xmlns="http://yang.juniper.net/yang/1.1/jc/configuration/junos/17.2R1.13"
  junos:commit-seconds="1493761452" 
  junos:commit-localtime="2017-05-02 14:44:12 PDT" 
  junos:commit-user="user">
  ...
</configuration>
</nc:data>
</nc:rpc-reply>
]]>]]>

(RFC 4741) Changes to <get> and <get-config> Operations

The rfc-compliant statement affects the <get> and <get-config> server replies in cases where there is no configuration data to return. This can occur, for example, when you apply a filter to return a subset of the configuration, and that portion of the configuration is empty.

In these cases, if you do not configure the rfc-compliant statement, the RPC reply contains an empty <configuration> element inside the <data> element.

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/15.1D0/junos">
<data>
<configuration>
</configuration>
</data>
</rpc-reply>

If you configure the rfc-compliant statement, the RPC reply instead returns an empty <data> element and omits the <configuration> element.

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/15.1R1/junos">
<nc:data>
</nc:data>
</nc:rpc-reply>

(RFC 4741) <rpc-error> Elements with a Severity Level of Warning in RPC Replies

Starting in Junos OS Release 17.4R3, 18.2R2, 18.3R2, and 18.4R1, when you configure the rfc-compliant statement, the NETCONF server cannot return an RPC reply that includes both an <rpc-error> element and an <ok/> element. If the operation is successful, but the server reply would include one or more <rpc-error> elements with a severity level of warning in addition to the <ok/> element, then the warnings are omitted. In addition, starting in Junos OS Release 21.2R1, any warnings that are omitted during a <commit> operation are redirected to the system log file for tracking.

In earlier releases, or when the rfc-compliant statement is not configured, the NETCONF server might issue an RPC reply that includes both an <rpc-error> element with a severity level of warning and an <ok/> element. For example, a commit operation might be successful but return a warning as in the following NETCONF server reply:

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/17.4R1/junos">
    <nc:rpc-error>
        <nc:error-severity>warning</nc:error-severity>
        <nc:error-message>
            uid changed for jadmin (2001->2014)
        </nc:error-message>
    </nc:rpc-error>
    <nc:ok/>
</nc:rpc-reply>
]]>]]>

If you configure the rfc-compliant statement, then the warning is omitted.

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/18.4R1/junos">
<nc:ok/>
</nc:rpc-reply>
]]>]]>

(RFC 4741) NETCONF Server Response to <commit> and <validate> Operations

Starting in Junos OS Release 21.2R1, when you configure the rfc-compliant statement, the NETCONF server's response to <commit> operations includes the following changes:

• If a successful <commit> operation returns a response with one or more warnings, the warnings are redirected to the system log file, in addition to being omitted from the response.

• The NETCONF server response emits the <source-daemon> element as a child of the <error-info> element instead of the <rpc-error> element.

• If you also configure the flatten-commit-results statement at the [edit system services netconf] hierarchy level, the NETCONF server emits only an <ok/> or <rpc-error> element in its response and suppresses any <commit-results> XML subtree.

Starting in Junos OS Release 23.2R1 and Junos OS Evolved Release 23.4R1, when you configure the rfc-compliant statement, the NETCONF server emits only an <ok/> or <rpc-error> element in response to <validate> operations. In earlier releases, the RPC reply also includes the <commit-results> element.

(RFC 6242) Chunked Framing

NETCONF sessions use a framing mechanism to separate the messages that the NETCONF server and client send within a session. By default, the NETCONF server emits the :base:1.0 capability, and both the NETCONF server and client use the character sequence ]]>]]> defined in RFC 4742 as the message separator. However, this character sequence can also potentially appear in XML attributes, comments, and processing instructions, where it could be misinterpreted as a message boundary.

To clearly define message boundaries, you can configure RFC 6242 compliance with support for chunked framing on Junos devices that support this feature. Chunked framing is a standardized framing mechanism that ensures that character sequences within XML elements are not misinterpreted as message boundaries. When you enable RFC 6242 compliance, and both peers advertise the :base:1.1 capability in the capabilities exchange, the NETCONF session uses chunked framing for the remainder of the session.

The chunked framing mechanism encodes all NETCONF messages as chunked following the Augmented Backus-Naur Form (ABNF) rule Chunked-Message, which is defined as follows:

Chunked-Message = 1*chunk
                  end-of-chunks

chunk          = LF HASH chunk-size LF
                  chunk-data                  
chunk-size     = 1*DIGIT1 0*DIGIT
chunk-data     = 1*OCTET

end-of-chunks  = LF HASH HASH LF

DIGIT1         =  %x31-39       
DIGIT          =  %x30-39       
HASH           =  %x23          
LF             =  %x0A          
OCTET          =  %x00-FF       

The chunk framing protocol divides NETCONF messages into distinct chunks, each with a specified size (chunk-size) and data (chunk-data), followed by an end-of-chunks marker. This structure ensures that sequences such as ]]>]]> within XML elements are not misinterpreted as end-of-message markers.

For example, when the NETCONF client emits the <get-system-information> RPC using the end-of-document character sequence, it emits the message as follows:

<rpc message-id="102"
     xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-system-information/>
</rpc>
]]>]]>

When the NETCONF client emits the same RPC using chunked framing, it might structure the message as follows:

#4
<rpc
#18
  message-id="102"
#85
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-system-information/>
</rpc>
##

Similary, the NETCONF server returns its reply using chunked framing.

#141
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/24.4R1/junos"  message-id="102" >

#21
<system-information>

#90
<host-name>R1</host-name>
<hardware-model>mx960</hardware-model>
<os-name>junos</os-name>

#73
<os-version>24.4R1.10</os-version>
<serial-number>ABC123</serial-number>

#22
</system-information>

#16
</nc:rpc-reply>

##

To enable RFC 6242 compliance with chunked framing support:

1. Enable the NETCONF service.

   content_copy zoom_out_map

   [edit system services netconf]
   user@host# set ssh

2. Configure NETCONF session compliance with RFC 4741 and RFC 6242.

   content_copy zoom_out_map

   [edit system services netconf]
   user@host# set rfc-compliant
   user@host# set version-1.1

3. Commit the configuration.

   content_copy zoom_out_map

   [edit system services netconf]
   user@host# commit

To use chunked framing in the NETCONF session, the client application and NETCONF server must both advertise the :base:1.1 capability in the capabilities exchange. For example:

admin@host:~$ ssh 198.51.100.1 -p 830 -s netconf
<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <nc:capabilities>
    <nc:capability>urn:ietf:params:netconf:base:1.1</nc:capability>
  </nc:capabilities>
</nc:hello>
]]>]]>

<!-- No zombies were killed during the creation of this user interface -->
<!-- user admin, class j-super-user -->
<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
   <nc:capabilities>
    <nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>
    <nc:capability>urn:ietf:params:netconf:base:1.1</nc:capability>
    ...
  </nc:capabilities>
  <nc:session-id>80206</nc:session-id>
</nc:hello>
]]>]]>

After both peers advertise the :base:1.1 capability, the NETCONF session uses chunked framing for the remainder of the session.