Chapter 15. The NETCONF Server

All enabled NETCONF capabilities are advertised in the hello message that the server sends to the client.

A YANG module is supported by the NETCONF server if it's fxs file is found in ConfD's loadPath, and if the fxs files is exported to NETCONF.

The following YANG modules are built-in, which means that their fxs files must not be present in the loadPath:

All built-in modules except ietf-netconf-with-defaults are always supported by the server. Support for ietf-netconf-with-defaults can be controlled by a setting in confd.conf.

All YANG version 1 modules supported by the server are advertised in the hello message, according to the rules defined in RFC 6020.

All YANG version 1 and version 1.1 modules supported by the server are advertised in the module list defined in ietf-yang-library.

If a YANG module (any version) is supported by the server, and its .yang or .yin file is found in the fxs file or in the loadPath, then the module is also advertised in the schema list defined in ietf-netconf-monitoring, made available for download with the RPC operation get-schema, and if RESTCONF is enabled, also advertised in the schema leaf in ietf-yang-library. See Section 15.6, “Monitoring of the NETCONF Server”.

ConfD is delivered with a program netconf-subsys which is an OpenSSH subsystem program. It is invoked by the OpenSSH daemon after successful authentication. It functions as a relay between the ssh daemon and ConfD; it reads data from the ssh daemon from standard input, and writes the data to ConfD over a loopback socket, and vice versa. This program is delivered as source code in $CONFD_DIR/src/confd/netconf/netconf-subsys.c . It can be modified to fit the needs of the application. For example, it could be modified to read the group names for a user from an external LDAP server.

When using OpenSSH, the users are authenticated by OpenSSH, i.e. the user names are not stored in ConfD. To use OpenSSH, compile the netconf-subsys program, and put the executable in e.g. /usr/local/bin. Then add the following line to the ssh daemon's config file, sshd_config:

Subsystem     netconf   /usr/local/bin/netconf-subsys

The connection from netconf-subsys to ConfD can be arranged in one of two different ways:

By default the netconf-subsys program sends the names of the UNIX groups the authenticated user belongs to. To test this, make sure that ConfD is configured to give access to the group(s) the user belongs to. Easiest for test is to give access to all groups.

The server can also be configured to accept plain TCP traffic. This can be useful during development, for debugging purposes, but it can also be used to plug in any other transport protocol. The way this works is that some other daemon terminates the transport and authenticates the user. Then it connects to the NETCONF server over TCP (preferably over the loopback interface for security reasons) and relays the XML traffic to NETCONF.

In this case, the transport daemon will have to authenticate the user, and then tell the NETCONF server about it. This should be done as a header sent over the TCP socket before any other bytes are sent. The header looks like this:

[username;source;proto;uid;gid;subgids;homedir;group-list;]\n

username is the name of the authenticated user. source is the textual representation of the ipv4 or ipv6 address and port which the user connected from, with address and port separated by '/' (e.g. "10.0.0.1/1234"). proto is the name of the transport protocol the client used (e.g. "beep" or "ssh"). uid, gid, supgids and homedir are the UNIX user id, group id, supplementary group ids and home directory for this user. These four parameters are only used if the user invokes a NETCONF RPC which is implemented with an external program (see Section 15.5, “Extending the NETCONF Server”). group-list is a comma-separated list of group names for the user. This list should only be sent if the transport has the capability to determine which groups a user belongs to. If not, an empty list should be sent. In this case, the normal AAA mechanisms are used to determine group membership.

All NETCONF RPCs sent over this socket must use the framing protocol used by NETCONF over SSH.

The TCP socket is also used if we want to use a standard SSH daemon such as sshd instead of the built-in SSH implementation. Then we would configure sshd to invoke a special program for the "netconf" subsystem. This special program would connect to the TCP socket as described above. See more below.

When ConfD processes <get>, <get-config>, and <copy-config> requests, the resulting data set can be very large. To avoid buffering huge amounts of data, ConfD streams the reply to the client as it traverses the data tree and calls data provider functions to retrieve the data.

If a data provider fails to return the data it is supposed to return, ConfD can take one of two actions. Either it simply closes the NETCONF transport (default), or it can reply with an inline rpc error and continue to process the next data element. This behavior can be controlled with the /confdConfig/netconf/rpcErrors configuration parameter (see confd.conf(5)). .

An inline error is always generated as a child element to the parent of the faulty element. For example, if an error occurs when retrieving the leaf element "mac-address" of an "interface" the error might be:

<interface>
  <name>atm1</name>
  <rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <error-type>application</error-type>
    <error-tag>operation-failed</error-tag>
    <error-severity>error</error-severity>
    <error-message xml:lang="en">Failed to talk to hardware</error-message>
    <error-info>
      <bad-element>mac-address</bad-element>
    </error-info>
  </rpc-error>
  ...
</interface>

If a get_next call fails in the processing of a list, a reply might look like this:

<interface>
  <!-- successfully retrieved list entry -->
  <name>eth0</name>
  <mtu>1500</mtu>
  <!-- more leafs here -->
</interface>
<rpc-error xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <error-type>application</error-type>
  <error-tag>operation-failed</error-tag>
  <error-severity>error</error-severity>
  <error-message xml:lang="en">Failed to talk to hardware</error-message>
  <error-info>
    <bad-element>interface</bad-element>
  </error-info>
</rpc-error>

In this case, the RPC is implemented as an ordinary executable program, which communicate with ConfD over stdin/stdout. When ConfD invokes the program, it will pass the entire XML operation on stdin. The program is responsible for parsing the operation data and placing its reply on stdout, and then terminate with exit status zero. ConfD wraps this reply in a <rpc-reply> element. Note that ConfD does not interpret the reply XML sent by the program; it merely sends the data as-is to the NETCONF client. Thus, it is the responsibility of the program to produce a valid NETCONF XML reply. Note that a rpc reply MUST contain one of <ok/>, <data> or <rpc-error>.

A program can also be run in batch mode, which can be used to send asynchronous data to the client. In this case, the program does not exit after having replied to the original RPC. Instead it signals that the reply has been sent by sending a NUL byte to ConfD. ConfD will enter its main loop and listen for new requests from the client and data from the external programs. When data is received from one source, this source is handled, while the others are (potentially) blocked. The asynchronous data sent by the external program must be a complete self-contained XML chunk, followed by a single NUL byte. The program can exit at any time, the session towards the client is not terminated just because the program exits.

The maximum number of concurrently running batch processes can be set in confd.conf (see confd.conf(5)) using the parameter /confdConfig/netconf/maxBatchProcesses. The default is no limit.

Here's an example of an rpc operation defined in this way:

module math-rpc {
  namespace "http://example.com/math/1.0";
  prefix math;

  import tailf-common {
    prefix tailf;
  }

  rpc math {
    tailf:exec "/usr/bin/math" {
      tailf:raw-xml;
    }
  }
}

All these examples are available under netconf_extensions/simple_rpc in the examples distribution.

Now suppose that the following rpc is received by the NETCONF server:

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <math xmlns="http://example.com/math/1.0">
    <add>
      <operand>2</operand>
      <operand>3</operand>
    </add>
  </math>
</rpc>

ConfD will invoke /usr/local/bin/math and pass:

<math xmlns="http://example.com/math/1.0">
  <add>
    <operand>2</operand>
    <operand>3</operand>
  </add>
</math>

on stdin. The program will print the rpc-reply to stdout, and ConfD relays this data to the client.

In this case, the RPC is implemented as an ordinary executable program, with all XML parameters converted by ConfD into command-line arguments to the program. If the program terminates normally without producing any output on stdout, ConfD replies with an <ok/> rpc-reply. If the program terminates normally and also generates data on stdout, ConfD interprets this data and passes it with <data> tags. If the program terminates abnormally without producing any data, a generic operation-failed error is returned. Finally, if the program terminates abnormally and also generates data on stdout, ConfD interprets this data as an rpc-error, and sends the resulting XML to the client.

Here's an example of the same rpc operation as above defined this way:

module math-rpc {
  namespace "http://example.com/math/1.0";
  prefix math;

  import tailf-common {
    prefix tailf;
  }

  rpc math {
    tailf:exec "/usr/bin/math";
    input {
      choice op {
        container add {
          leaf-list operand {
            type int32;
            min-elements 2;
            max-elements 2;
          }
        }
        container sub {
          leaf-list operand {
            type int32;
            min-elements 2;
            max-elements 2;
          }
        }
      }
    }
    output {
      leaf result {
        type int32;
      }
    }
  }
}

Now suppose that the same RPC request as in Code listing 2 above is received. ConfD parses the XML and invokes the command as:

/usr/local/bin/math add __BEGIN operand 2 operand 3 add __END

In general, the XML is flattened, and each XML element generates two strings on the command line. If a container is received, the strings "elem-name" "__BEGIN" is generated. When the corresponding close element is received, "elem-name" "__END" is generated. An element with a value will generate "elem-name" "value". An empty element with no subelements will generate "elem-name" "__LEAF".

Next, the math program replies by printing on stdout:

result 5

The same translation rules applies to the result, and ConfD thus sends the following reply to the client:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <data>
    <result xmlns="http://example.com/math/1.0">5</result>
  </data>
</rpc-reply>

In this case, the RPC is implemented as a callback function in C, with all XML parameters converted by ConfD into a C data structure.

Here's an example of the same rpc operation as above defined this way:

module math-rpc {
  namespace "http://example.com/math/1.0";
  prefix math;

  import tailf-common {
    prefix tailf;
  }

  rpc math {
    tailf:actionpoint "math";
    input {
      choice op {
        container add {
          leaf-list operand {
            type int32;
            min-elements 2;
            max-elements 2;
          }
        }
        container sub {
          leaf-list operand {
            type int32;
            min-elements 2;
            max-elements 2;
          }
        }
      }
    }
    output {
      leaf result {
        type int32;
      }
    }
  }
}

The code that implements this looks like this:

static void register_math(struct confd_daemon_ctx *dctx)
{
    struct confd_action_cbs acb;

    memset(&acb, 0, sizeof(acb));
    strcpy(acb.actionpoint, "math");
    acb.init = init_action;  /* this function is not shown here */
    acb.action = do_math;
    if (confd_register_action_cbs(dctx, &acb) != CONFD_OK)
        confd_fatal("Couldn't register action callbacks\n");
    if (confd_register_done(dctx) != CONFD_OK)
        confd_fatal("Failed to complete registration \n");
}

static int do_math(struct confd_user_info *uinfo,
                   struct xml_tag *name,
                   confd_hkeypath_t *kp,
                   confd_tag_value_t *params,
                   int nparams)
{
    confd_tag_value_t reply[1];
    int op1, op2, result;

    /*
      we know that we get exactly 4 parameters;
         add | del BEGIN
         operand 1
         operand 2
         add | del END
    */

    op1 = CONFD_GET_INT32(CONFD_GET_TAG_VALUE(&params[1]));
    op2 = CONFD_GET_INT32(CONFD_GET_TAG_VALUE(&params[2]));
    switch (CONFD_GET_TAG_TAG(&params[0])) {
    case math_add:
        result = op1 + op2;
        break;
    case math_del:
        result = op1 - op2;
        break;
    }

    CONFD_SET_TAG_INT32(&reply[0], math_result, result);
    confd_action_reply_values(uinfo, reply, 1);

    return CONFD_OK;
}

ConfD has built-in support for the well-known stream NETCONF, defined in RFC 5277. ConfD supports the notifications defined in RFC 6470 - NETCONF Base Notifications on this stream. If the application needs to send any additional notifications on this stream, it can do so.

It is up to the application to define which additional streams it supports. In ConfD, this is done in confd.conf (see confd.conf(5)). Each stream must be listed, and whether it supports replay or not. An example which defines two streams, security and debug:

<notifications>
  <eventStreams>
    <stream>
      <name>security</name>
      <description>Security related notifications</description>
      <replaySupport>true</replaySupport>
      <builtinReplayStore>
        <enabled>true</enabled>
        <dir>/var/log</dir>
        <maxSize>S10M</maxSize>
        <maxFiles>50</maxFiles>
      </builtinReplayStore>
    </stream>
    <stream>
      <name>debug</name>
      <description>Debug notifications</description>
      <replaySupport>true</replaySupport>
    </stream>
  </eventStreams>
</notifications>

The well-known stream NETCONF does not have to be listed, but if it isn't listed, it will not support replay.

ConfD has builtin support for logging of notifications, i.e., if replay support has been enabled for a stream, ConfD automatically stores all notifications on disk ready to be replayed should a NETCONF client ask for logged notifications. In the confd.conf fragment above the security stream has been setup to use the builtin notification log/replay store. The replay store uses a set of wrapping log files on disk (of a certain number and size) to store the security stream notifications.

The reason for using a wrap log is to improve replay performance whenever a NETCONF client asks for notifications in a certain time range. Any problems with log files not being properly closed due to hard power failures etc. is also kept to a minimum, i.e., automatically taken care of by ConfD.

As an alternative to the builtin notification replay store the application can roll its own. This is described in the next sub-section.

If a stream supports replay, the logging and replay functionality can alternatively be implemented by the application. In order to do this, the application must register a set of callback functions with ConfD using the function confd_register_notification_stream(). The callbacks are get_log_start_time() and replay(). The first one is called by ConfD in order to find the earliest event time available in the log. The second one is invoked whenever a NETCONF client asks for a replay subscription. For full details on the notification API, please see the confd_lib_dp(3) manual page.

The following example is available in full source code form in the examples directory. A single stream interface is used, and it supports replay.

/* The notification context (filled in by ConfD) for the live feed */
static struct confd_notification_ctx *live_ctx;


          struct confd_notification_stream_cbs ncb;


          memset(&ncb, 0, sizeof(ncb));
    ncb.fd = workersock;
    ncb.get_log_times = log_times;
    ncb.replay = start_replay;
    strcpy(ncb.streamname, "interface");
    ncb.cb_opaque = NULL;
    if (confd_register_notification_stream(dctx, &ncb, &live_ctx) != CONFD_OK) {
        confd_fatal("Couldn't register stream %s\n", ncb.streamname);
    }
    if (confd_register_done(dctx) != CONFD_OK) {
        confd_fatal("Failed to complete registration\n");
    }

In this simple example, we keep the replay log in memory, in an array:

struct notif {
    struct confd_datetime eventTime;
    confd_tag_value_t *vals;
    int nvals;
};

/* Our replay buffer is kept in memory in this example.  It's a circular
 * buffer of struct notif.
 */
#define MAX_BUFFERED_NOTIFS 4
static struct notif replay_buffer[MAX_BUFFERED_NOTIFS];
static unsigned int first_replay_idx = 0;
static unsigned int next_replay_idx = 0;

static struct confd_datetime replay_creation;
static int replay_has_aged_out = 0;
static struct confd_datetime replay_aged_time;

The get_log_start_time() callback simply returns the time of the first notification in the log:

static int log_times(struct confd_notification_ctx *nctx)
{
    struct confd_datetime *aged;

    if (replay_has_aged_out)
        aged = &replay_aged_time;
    else
        aged = NULL;

    return confd_notification_reply_log_times(nctx, &replay_creation, aged);
}

When a client asks for a replay subscription, ConfD invokes the callback replay. The actual replay notifications must not be sent from the callback. In this example, the callback allocates a replay structure, and marks it as being active. The main loop will check for any active replays, and do the sending there.

#define MAX_REPLAYS 10
struct replay {
    int active;
    int started;
    unsigned int idx;
    struct confd_notification_ctx *ctx;
    struct confd_datetime start;
    struct confd_datetime stop;
    int has_stop;
};
/* Keep tracks of active replays */
static struct replay replay[MAX_REPLAYS];


      static int start_replay(struct confd_notification_ctx *nctx,
                        struct confd_datetime *start,
                        struct confd_datetime *stop)
{
    int rnum;

    for (rnum = 0; rnum < MAX_REPLAYS; rnum++) {
        if (!replay[rnum].active) {
            replay[rnum].active = 1;
            replay[rnum].started = 0;
            replay[rnum].idx = first_replay_idx;
            replay[rnum].ctx = nctx;
            replay[rnum].start = *start;
            if (stop) {
                replay[rnum].has_stop = 1;
                replay[rnum].stop = *stop;
            } else
                replay[rnum].has_stop = 0; /* stop when caught up to live */
            return CONFD_OK;
        }
    }
    confd_notification_seterr(nctx, "Max no. of replay requests reached");
    return CONFD_ERR;
}

Before an application can send a notification, the notification must be defined in a YANG module. In this example, a notification link-down is defined. The notification has a single parameter if-index:

  notification linkDown {
    leaf ifIndex {
      type leafref {
        path "/interfaces/interface/ifIndex";
      }
      mandatory true;
    }
  }

When the application sends an application, it uses the function confd_notification_send().

static void send_notifdown(int index)
{
    confd_tag_value_t vals[3];
    int i = 0;

    CONFD_SET_TAG_XMLBEGIN(&vals[i], notif_linkDown,     notif__ns);  i++;
    CONFD_SET_TAG_UINT32(&vals[i],   notif_ifIndex,      index);      i++;
    CONFD_SET_TAG_XMLEND(&vals[i],   notif_linkDown,     notif__ns);  i++;
    send_notification(vals, i);
}


      static void send_notification(confd_tag_value_t *vals, int nvals)
{
    int sz;
    struct confd_datetime now;
    struct notif *notif;

    getdatetime(&now);
    notif = &replay_buffer[next_replay_idx];
    if (notif->vals) {
        /* we're aging out this notification */
        replay_has_aged_out = 1;
        replay_aged_time = notif->eventTime;
        first_replay_idx = (first_replay_idx + 1) % MAX_BUFFERED_NOTIFS;
        free(notif->vals);
    }
    notif->eventTime = now;
    sz = nvals * sizeof(confd_tag_value_t);
    notif->vals = malloc(sz);
    memcpy(notif->vals, vals, sz);
    notif->nvals = nvals;
    next_replay_idx = (next_replay_idx + 1) % MAX_BUFFERED_NOTIFS;
    OK(confd_notification_send(live_ctx,
                               &notif->eventTime,
                               notif->vals,
                               notif->nvals));
}

This capability introduces one new rpc method which is used to invoke actions (methods) defined in the data model. When an action is invoked, the instance on which the action is invoked is explicitly identified by an hierarchy of configuration or state data.

Here's a simple example which resets an interface.

  <rpc message-id="101"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <action xmlns="http://tail-f.com/ns/netconf/actions/1.0">
      <data>
        <interfaces xmlns="http://example.com/interfaces/1.0">
          <interface>
            <name>eth0</name>
            <reset/>
          </interface>
        </interfaces>
      </data>
    </action>
  </rpc>

  <rpc-reply message-id="101"
             xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <ok/>
  </rpc-reply>

The alternative is to use a specialized rpc method for each action. There are a couple of drawbacks with that:

None.

The actions capability is identified by the following capability string:

  http://tail-f.com/ns/netconf/actions/1.0

None.

This XML Schema defines the new action rpc.

  <?xml version="1.0" encoding="UTF-8"?>
  <xs:schema targetNamespace="http://tail-f.com/ns/netconf/actions/1.0"
	     xmlns="http://tail-f.com/ns/netconf/actions/1.0"
	     xmlns:xs="http://www.w3.org/2001/XMLSchema"
             xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"
             elementFormDefault="qualified"
             attributeFormDefault="unqualified"
	     xml:lang="en">

    <!--  <action> operation -->
    <xs:complexType name="ActionType">
      <xs:complexContent>
        <xs:extension base="netconf:rpcOperationType">
          <xs:sequence>
            <xs:element name="data" type="netconf:dataInlineType" />
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>

    <xs:element name="action" type="ActionType"
                substitutionGroup="netconf:rpcOperation"/>

  </xs:schema>

This capability introduces four new rpc methods which are used to control a two-phase commit transaction on the NETCONF server. The normal <edit-config> operation is used to write data in the transaction, but the modifications are not applied until an explicit <commit-transaction> is sent.

This capability is formally defined in the YANG module "tailf-netconf-transactions".

A typical sequence of operations looks like this:

               C                           S
               |                           |
               |  capability exchange      |
               |-------------------------->|
               |<------------------------->|
               |                           |
               |   <start-transaction>     |
               |-------------------------->|
               |<--------------------------|
               |         <ok/>             |
               |                           |
               |     <edit-config>         |
               |-------------------------->|
               |<--------------------------|
               |         <ok/>             |
               |                           |
               |  <prepare-transaction>    |
               |-------------------------->|
               |<--------------------------|
               |         <ok/>             |
               |                           |
               |   <commit-transaction>    |
               |-------------------------->|
               |<--------------------------|
               |         <ok/>             |
               |                           |

None.

The transactions capability is identified by the following capability string:

  http://tail-f.com/ns/netconf/transactions/1.0

The <edit-config> operation is modified so that if it is received during an ongoing transaction, the modifications are not immediately applied to the configuration target. Instead they are kept in the transaction state of the server. The transaction state is only applied when a <commit-transaction> is received.

Note that it doesn't matter if the <test-option> is 'set' or 'test-then-set' in the <edit-config>, since nothing is actually set when the <edit-config> is received.

This XML Schema defines the new transaction rpcs.

  <?xml version="1.0" encoding="UTF-8"?>
  <xs:schema targetNamespace="http://tail-f.com/ns/netconf/transactions/1.0"
	     xmlns="http://tail-f.com/ns/netconf/transactions/1.0"
	     xmlns:xs="http://www.w3.org/2001/XMLSchema"
             xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"
             elementFormDefault="qualified"
             attributeFormDefault="unqualified"
	     xml:lang="en">

    <!-- Type for <target> element -->
    <xs:complexType name="TargetType">
      <xs:choice>
        <xs:element name="running"/>
        <xs:element name="startup"/>
        <xs:element name="candidate"/>
      </xs:choice>
    </xs:complexType>

    <!--  <start-transaction> operation -->
    <xs:complexType name="StartTransactionType">
      <xs:complexContent>
        <xs:extension base="netconf:rpcOperationType">
          <xs:sequence>
            <xs:element name="target" type="TargetType"/>
            <xs:element name="with-inactive" minOccurs="0"/>
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>

    <xs:element name="start-transaction" type="StartTransactionType"
                substitutionGroup="netconf:rpcOperation"/>

    <xs:element name="prepare-transaction"
                substitutionGroup="netconf:rpcOperation"/>

    <xs:element name="commit-transaction"
                substitutionGroup="netconf:rpcOperation"/>

    <xs:element name="abort-transaction"
                substitutionGroup="netconf:rpcOperation"/>

  </xs:schema>

The Proxy Forwarding capability makes it possible to forward NETCONF requests to a target host through a proxy NETCONF server. It can be used in situations where a client does not have direct network access to a target host:

                     +--------+
                     | Client |
                     +--------+
                         |
                         | 
                         |
                     +--------+
                     | Proxy  |
                     | server |
                     +--------+
                       /    \
                      /      \ 
                     /        \
               +--------+   +--------+
               | Proxy  |   | Proxy  |
               | target |   | target |
               +--------+   +--------+

See RFC 2663 for a definition of a proxy. This RFC defines two terms "Application Level Gateway" (ALG) and "Proxy":

    ALGs are similar to Proxies, in that, both ALGs and proxies
    facilitate Application specific communication between clients
    and servers. Proxies use a special protocol to communicate with
    proxy clients and relay client data to servers and vice
    versa. Unlike Proxies, ALGs do not use a special protocol to
    communicate with application clients and do not require changes
    to application clients.

A client that wants to set up a NETCONF session to a Proxy target first connects to the Proxy server, which advertises the "forward" capability. The client issues a <forward> RPC, with a <target> parameter which specifies which Proxy target to connect to. The Proxy server sets up a NETCONF connection to the Proxy target, and after successful authentication, replies with the Proxy target's capability list to the client. From this point, the session is established, and any data received by the Proxy server from any side is sent as-is (without interpretation) to the other side.

    Client                     Server                      Target
      |                           |                           |
      |                           |                           |
      |    capability exchange    |                           |
      |<------------------------->|                           |
      |                           |                           |
      |       <forward>           |                           |
      |-------------------------->|                           |
      |<--------------------------|                           |
      |       <mechanisms>        |                           |
      |                           |                           |
      |       <forward>           |                           |
      |        <mechanism>        |                           |
      |-------------------------->|                           |
      |<--------------------------|                           |
      |       <challenge>         |                           |
      |                           |                           |
      |    <challenge-response>   |                           |
      |-------------------------->|                           |
      |                           |    connect+authenticate   |
      |                           |-------------------------->|
      |                           |<--------------------------|
      |                           |        <hello>            |
      |     <capabilities>        |                           |
      |<--------------------------|                           |
      |                           |                           |
      |        data               |                           |
      |-------------------------->|          data             |
      |                           |-------------------------->|
      |                           |                           |
      |                           |          data             |
      |        data               |<--------------------------|
      |<--------------------------|                           |
      |                           |                           |
      |                           |                           |

None.

The proxy forwarding capability is identified by the following capability string:

  http://tail-f.com/ns/netconf/forward/1.0

None.

None.

This XML Schema defines the new forwarding rpcs.

  <?xml version="1.0" encoding="UTF-8"?>
  <xs:schema targetNamespace="http://tail-f.com/ns/netconf/forward/1.0"
	     xmlns:xs="http://www.w3.org/2001/XMLSchema"
	     xmlns="http://tail-f.com/ns/netconf/forward/1.0"
	     xmlns:fwd="http://tail-f.com/ns/netconf/forward/1.0"
             xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
             elementFormDefault="qualified"
             attributeFormDefault="unqualified"
	     xml:lang="en">

    <!-- <forward> operation -->
    <xs:element name="forward" substitutionGroup="nc:rpcOperation">
      <xs:complexType>
        <xs:complexContent>
          <xs:extension base="nc:rpcOperationType">
              <xs:sequence>
                <xs:element name="target" type="xs:string"/>
                <xs:element name="auth" minOccurs="0">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="mechanism" type="xs:string"/>
                      <xs:element name="initial-response" minOccurs="0"
                                  type="xs:string"/>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
              </xs:sequence>
          </xs:extension>
        </xs:complexContent>
      </xs:complexType>
    </xs:element>


    <!-- <challenge-response> operation -->
    <xs:element name="challenge-response" substitutionGroup="nc:rpcOperation">
      <xs:complexType>
        <xs:complexContent>
          <xs:extension base="nc:rpcOperationType">
              <xs:sequence>
                <xs:element name="response" type="xs:string"/>
              </xs:sequence>
          </xs:extension>
        </xs:complexContent>
      </xs:complexType>
    </xs:element>

    <!-- reply to <forward> and <challenge-response> operations -->
    <xs:element name="capabilities">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="capability"
                      minOccurs="0" maxOccurs="unbounded"
                      type="xs:uri"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>

    <!-- reply to <forward> and <challenge-response> operations -->
    <xs:element name="challenge" type="xs:string"/>

    <!-- <error-info> content when <error-app-tag> is "sasl-failure" -->
    <xs:element name="failure">
      <xs:complexType>
        <xs:sequence>
          <xs:choice>
            <xs:element name="incorrect-encoding">
              <xs:complexType/>
            </xs:element>
            <xs:element name="invalid-authzid">
              <xs:complexType/>
            </xs:element>
            <xs:element name="invalid-mechanism">
              <xs:complexType/>
            </xs:element>
            <xs:element name="mechanism-too-weak">
              <xs:complexType/>
            </xs:element>
            <xs:element name="not-authorized">
              <xs:complexType/>
            </xs:element>
            <xs:element name="temporary-auth-failure">
              <xs:complexType/>
            </xs:element>
          </xs:choice>
        </xs:sequence>
      </xs:complexType>
    </xs:element>

    <!--
       <error-info> content when <error-app-tag> is
       "sasl-authentication-needed"
    -->
    <xs:element name="mechanisms">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="mechanism"
                      minOccurs="0" maxOccurs="unbounded"
                      type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    <xs:element>


  </xs:schema>

This capability is used by the NETCONF server to indicate that it supports marking nodes as being inactive. A node that is marked as inactive exists in the data store, but is not used by the server. Any node can be marked as inactive.

In order to not confuse clients that do not understand this attribute, the client has to instruct the server to display and handle the inactive nodes. An inactive node is marked with an "inactive" XML attribute, and in order to make it active, the "active" XML atribute is used.

This capability is formally defined in the YANG module "tailf-netconf-inactive".

None.

The inactive capability is identified by the following capability string:

  http://tail-f.com/ns/netconf/inactive/1.0

None.

A new parameter, <with-inactive>, is added to the <get>, <get-config>, <edit-config>, <copy-config>, and <start-transaction> operations.

The <with-inactive> element is defined in the http://tail-f.com/ns/netconf/inactive/1.0 namespace, and takes no value.

If this parameter is present in <get>, <get-config>, or <copy-config>, the NETCONF server will mark inactive nodes with the "inactive" attribute.

If this parameter is present in <edit-config> or <copy-config>, the NETCONF server will treat inactive nodes as existing, so that an attempt to create a node which is inactive will fail, and an attempt to delete a node which is inactive will succeed. Further, the NETCONF server accepts the "inactive" and "active" attributes in the data hierarchy, in order to make nodes inactive or active, respectively.

If the parameter is present in <start-transaction>, it MUST also be present in any <edit-config>, <copy-config>, <get>, or <get-config> operations within the transaction. If it is not present in <start-transaction>, it MUST NOT be present in any <edit-config> operation within the transaction.

The "inactive" and "active" attributes are defined in the http://tail-f.com/ns/netconf/inactive/1.0 namespace. The "inactive" attribute's value is the string "inactive", and the "active" attribute's value is the string "active".

  <rpc message-id="101"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <edit-config>
      <target>
        <running/>
      </target>
      <with-inactive
         xmlns="http://tail-f.com/ns/netconf/inactive/1.0"/>
      <config>
        <top xmlns="http://example.com/schema/1.2/config">
          <interface inactive="inactive">
            <name>Ethernet0/0</name>
            <mtu>1500</mtu>
          </interface>
        </top>
      </config>
    </edit-config>
  </rpc>

  <rpc-reply message-id="101"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <ok/>
  </rpc-reply>

  <rpc message-id="102"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <get-config>
      <source>
        <running/>
      </source>
      <with-inactive
         xmlns="http://tail-f.com/ns/netconf/inactive/1.0"/>
    </get-config>
  </rpc>

  <rpc-reply message-id="102"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <data>
      <top xmlns="http://example.com/schema/1.2/config">
        <interface inactive="inactive">
          <name>Ethernet0/0</name>
          <mtu>1500</mtu>
        </interface>
      </top>
    </data>
  </rpc-reply>

  <rpc message-id="103"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <get-config>
      <source>
        <running/>
      </source>
    </get-config>
  </rpc>

  <rpc-reply message-id="103"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <data>
    </data>
  </rpc-reply>

  <rpc message-id="104"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <edit-config>
      <target>
        <running/>
      </target>
      <with-inactive
         xmlns="http://tail-f.com/ns/netconf/inactive/1.0"/>
      <config>
        <top xmlns="http://example.com/schema/1.2/config">
          <interface active="active">
            <name>Ethernet0/0</name>
          </interface>
        </top>
      </config>
    </edit-config>
  </rpc>

  <rpc-reply message-id="104"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <ok/>
  </rpc-reply>

This capability is used by a NETCONF peer to inform the other peer about the NETCONF stack and NETCONF client. The receiving peer can use this information in log files etc.

The information a peer may advertise is:

All these parameters are free form strings, advertised as query parameters to the capability URI, in the <hello> message.

None.

The identification capability is identified by the following capability string:

  http://tail-f.com/ns/netconf/identification/1.0

This is an example of how a client might advertise its identification information. Whitespace is added to make the example more readable.

  <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <capabilities>
      <capability>
        urn:ietf:params:netconf:base:1.1
      </capability>
      <capability>
        http://tail-f.com/ns/netconf/identification/1.0?
               vendor=tail-f
          &amp;product=ncs
          &amp;version=1.8
          &amp;client-identity=admin
      </capability>
    </capabilities>
  </hello>

If a NETCONF client advertises this capability, ConfD picks up the information, and stores it in the user session. The information is available to application programmers through the function maapi_get_user_session_identification().