Remote configuration via NETCONF

Virtual Service Router can be configured remotely thanks to the NETCONF protocol.

XML request format

NETCONF uses XML requests to communicate with Virtual Service Router. The easiest way to write those requests is to use the CLI.

Configuration requests

To write a configuration request, generate the wanted configuration with the CLI, and call show config xml absolute:

vsr> edit running
vsr running config# / system hostname myhostname
vsr running config# show / system hostname myhostname
vsr running config# show config xml absolute system hostname
<config xmlns="urn:6wind:vrouter">
  <system xmlns="urn:6wind:vrouter/system">
    <hostname>myhostname</hostname>
  </system>
</config>

This result of the last command must be encapsulated in the NETCONF configuration tag, like this:

<config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <config xmlns="urn:6wind:vrouter">
    <system xmlns="urn:6wind:vrouter/system">
      <hostname>myhostname</hostname>
    </system>
  </config>
</config>

State requests

To write a state request, retrieve the desired state with the CLI, and call show state xml absolute:

vsr> show state xml absolute system hostname
<state xmlns="urn:6wind:vrouter">
  <system xmlns="urn:6wind:vrouter/system">
    <hostname>vsr</hostname>
  </system>
</state>

Then, generate a filter by removing the leaf value, like this:

<state xmlns="urn:6wind:vrouter">
  <system xmlns="urn:6wind:vrouter/system">
    <hostname></hostname>
  </system>
</state>

RPC requests

To write a cmd, flush, or show rpc request, use the dry-run option in the CLI:

vsr> show dry-run xml product version
<show-product xmlns="urn:6wind:vrouter/system">
  <version/>
</show-product>

Note

Some rpcs are long to run, and are designed to be used by the CLI. They will return other rpcs that should be called, like this:

<?xml version='1.0' encoding='UTF-8'?>
  <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="urn:uuid:31d28770-078b-494e-90b5-e2ba9d5042d1">
    <status-rpc xmlns="urn:6wind:vrouter/bgp"><get-command-status xmlns="urn:6wind:vrouter/commands"><uid>26</uid></get-command-status></status-rpc>
    <refresh-rpc xmlns="urn:6wind:vrouter/bgp"><refresh-command xmlns="urn:6wind:vrouter/commands"><uid>26</uid></refresh-command></refresh-rpc>
    <stop-rpc xmlns="urn:6wind:vrouter/bgp"><stop-command xmlns="urn:6wind:vrouter/commands"><uid>26</uid></stop-command></stop-rpc>
    <buffer xmlns="urn:6wind:vrouter/bgp"/>
</nc:rpc-reply>

The refresh-rpc must be called from time to time to keep the command alive, the stop-rpc should be called if the rpc should be stopped, and the status-rpc will accumulate the rpc output in the buffer attribute.

Those rpcs are marked with the long-cmd-status and long-cmd-output extensions in the YANG model.

We don’t recommend calling those rpcs using the NETCONF api.

Example of use

We will use ncclient as a NETCONF client. On another machine that will configure the router, install ncclient dependencies.

root@local# python3 -m pip install ncclient

Create a netconf.py file with this content.

It will configure the hostname twice and it will check whether the system state has properly changed after each change.

#!/usr/bin/env python3
# pip install xmltodict ncclient

import json
from ncclient import manager
import time
import xmltodict

def connect(host, user, password):
    conn = manager.connect(host=host,
                           username=user,
                           password=password,
                           timeout=10,
                           hostkey_verify=False)

    state = """
<state xmlns="urn:6wind:vrouter">
  <system xmlns="urn:6wind:vrouter/system">
    <hostname></hostname>
  </system>
</state>
"""

    conf = """
<config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <config xmlns="urn:6wind:vrouter">
    <system xmlns="urn:6wind:vrouter/system">
      <hostname>vsr</hostname>
    </system>
  </config>
</config>
"""

    new_hostname_conf = """
<config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <config xmlns="urn:6wind:vrouter">
    <system xmlns="urn:6wind:vrouter/system">
      <hostname>myhostname</hostname>
    </system>
  </config>
</config>
"""

    get_state = conn.get(filter=('subtree', state))
    print('***************** hostname before configuration ****************')
    print(json.dumps(xmltodict.parse(get_state.data_xml), indent=2))

    print('***************** set hostname to "myhostname" ****************')
    send_config = conn.edit_config(target='running', config=new_hostname_conf, default_operation='merge')

    get_state = conn.get(filter=('subtree', state))
    print('***************** hostname is now "myhostname" ****************')
    print(json.dumps(xmltodict.parse(get_state.data_xml), indent=2))

    print('***************** revert to "vsr" ****************')
    send_config = conn.edit_config(target='running', config=conf, default_operation='merge')

    get_state = conn.get(filter=('subtree', state))
    print('***************** hostname is now "vsr" ****************')
    print(json.dumps(xmltodict.parse(get_state.data_xml), indent=2))

    conn.close_session()

if __name__ == '__main__':
    connect('<myip>', 'root', '<rootpass>')

Update the connect line to put the router IP, and the root password of the router, and launch the script. The following output is displayed.

root@local# python3 netconf_hostname.py
***************** hostname before configuration ****************
{
  "data": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:base:1.0",
    "@xmlns:nc": "urn:ietf:params:xml:ns:netconf:base:1.0",
    "state": {
      "@xmlns": "urn:6wind:vrouter",
      "system": {
        "@xmlns": "urn:6wind:vrouter/system",
        "hostname": "vsr"
      }
    }
  }
}
***************** set hostname to "myhostname" ****************
***************** hostname is now "myhostname" ****************
{
  "data": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:base:1.0",
    "@xmlns:nc": "urn:ietf:params:xml:ns:netconf:base:1.0",
    "state": {
      "@xmlns": "urn:6wind:vrouter",
      "system": {
        "@xmlns": "urn:6wind:vrouter/system",
        "hostname": "myhostname"
      }
    }
  }
}
***************** revert to "vsr" ****************
***************** hostname is now "vsr" ****************
{
  "data": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:base:1.0",
    "@xmlns:nc": "urn:ietf:params:xml:ns:netconf:base:1.0",
    "state": {
      "@xmlns": "urn:6wind:vrouter",
      "system": {
        "@xmlns": "urn:6wind:vrouter/system",
        "hostname": "vsr"
      }
    }
  }
}

Remote subscriptions via NETCONF

Virtual Service Router can send notifications using the NETCONF protocol.

Basic example

This chapter expects that the requirements from the previous chapter are met.

We will start a script that will subscribe to NETCONF notifications, and display the notification when one is received.

Create a netconf_subscribe.py file with this content

#!/usr/bin/env python3
import json
from ncclient import manager
from ncclient.xml_ import to_ele
import xmltodict

create_subscription="""<create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"/>"""

def connect(host, user, password):
    conn = manager.connect(host=host,
                           username=user,
                           password=password,
                           timeout=10,
                           hostkey_verify=False)

    conn.dispatch(to_ele(create_subscription))

    print('Waiting for events')
    while True:
        notification = conn.take_notification()
        print(json.dumps(xmltodict.parse(notification.notification_xml), indent=2))

if __name__ == '__main__':
    connect('<myip>', 'root', '<rootpass>')

Update the connect line to put the router IP, and the root password of the router, and launch the script. Then, on the router, log as admin, and logout. The following output is displayed.

root@local# python3 netconf_subscribe.py
Waiting for events
{
  "notification": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:notification:1.0",
    "eventTime": "2022-10-05T14:05:10.125719825+00:00",
    "netconf-session-start": {
      "@xmlns": "urn:ietf:params:xml:ns:yang:ietf-netconf-notifications",
      "username": "admin",
      "session-id": "12"
    }
  }
}
{
  "notification": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:notification:1.0",
    "eventTime": "2022-10-05T14:05:22.267006931+00:00",
    "netconf-session-end": {
      "@xmlns": "urn:ietf:params:xml:ns:yang:ietf-netconf-notifications",
      "username": "admin",
      "session-id": "12",
      "termination-reason": "closed"
    }
  }
}

The subscription can be targeted to a particular type of subscription, using a filter. For instance, the following filter targets ietf-yang-push push updates, ietf-alarms alarm notifications, and ietf-netconf-notifications netconf-session-start, netconf-session-end and netconf-config-change.

create_subscription="""
<create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <filter xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" netconf:type="subtree"
       xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push"
       xmlns:al="urn:ietf:params:xml:ns:yang:ietf-alarms"
       xmlns:nn="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <yp:push-update/>
    <yp:push-change-update/>
    <al:alarm-notification/>
    <nn:netconf-session-start/>
    <nn:netconf-session-end/>
    <nn:netconf-config-change/>
  </filter>
</create-subscription>"""

The subscriptions for the ietf-netconf-notification and ietf-alarms can also be replayed. For instance, the following request will replay the NETCONF notifications since 2022-03-02T15:25:00+00:00.

create_subscription="""
<create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
   <startTime>2022-03-02T15:25:00+00:00</startTime>
</create-subscription>"""

Yang push example

Virtual Service Router supports the yang push functionality (RFC 8641), which triggers notifications on a periodic basic, or on change in the NETCONF datastores.

The following script subscribes to changes on the /state/vrf/interface/physical/enabled leaf, and requests periodic updates every 30s for the /state/vrf/interface/physical/counters container.

#!/usr/bin/env python3
import json
from ncclient import manager
from ncclient.xml_ import to_ele
import xmltodict

yang_push_operational_periodic="""
 <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
  <datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push" xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
  <datastore-xpath-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">/state/vrf/interface/physical/counters</datastore-xpath-filter>
  <periodic xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
   <period>3000</period>
  </periodic>
 </establish-subscription>
"""

yang_push_operational_on_change="""
 <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
   <datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push" xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
   <datastore-xpath-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">/state/vrf/interface/physical/enabled</datastore-xpath-filter>
   <on-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"/>
 </establish-subscription>
"""

yang_push_state="""
 <streams xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
 <subscriptions xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
"""

create_subscription="""
 <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <filter xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" netconf:type="subtree" xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <yp:push-update/>
  </filter>
 </create-subscription>
"""

def connect(host, user, password):
    with manager.connect(host=host,
                           username=user,
                           password=password,
                           timeout=10,
                           hostkey_verify=False) as conn:

        # conn.create_subscription(start_time="2020-03-02T15:25:00+00:00") does not work, use dispatch
        # See: https://github.com/ncclient/ncclient/issues/224
        conn.dispatch(to_ele(create_subscription))

        conn.dispatch(to_ele(yang_push_operational_on_change))
        conn.dispatch(to_ele(yang_push_operational_periodic))

        get_state = conn.get(filter=('subtree', yang_push_state))
        print('*********** Dump subscribed notifications ***********')
        print(json.dumps(xmltodict.parse(get_state.data_xml), indent=2))

        print('*****************************************************')
        print('Waiting for events')
        while True:
            notification = conn.take_notification()
            print(json.dumps(xmltodict.parse(notification.notification_xml), indent=2))

if __name__ == '__main__':
    connect('<myip>', 'root', '<rootpass>')

The following output is displayed:

*********** Dump subscribed notifications ***********
{
  "data": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:base:1.0",
    "subscriptions": {
      "@xmlns": "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications",
      "subscription": [
        {
          "id": "19",
          "receivers": {
            "receiver": {
              "name": "NETCONF session 14",
              "sent-event-records": "1",
              "excluded-event-records": "0",
              "state": "active"
            }
          }
        },
        {
          "id": "20",
          "receivers": {
            "receiver": {
              "name": "NETCONF session 14",
              "sent-event-records": "1",
              "excluded-event-records": "0",
              "state": "active"
            }
          }
        }
      ]
    }
  }
}
*****************************************************
Waiting for events
{
  "notification": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:notification:1.0",
    "eventTime": "2022-10-06T06:44:20.110765456+00:00",
    "push-update": {
      "@xmlns": "urn:ietf:params:xml:ns:yang:ietf-yang-push",
      "id": "19",
      "datastore-contents": {
        "state": {
          "@xmlns": "urn:6wind:vrouter",
          "vrf": {
            "name": "main",
            "interface": {
              "@xmlns": "urn:6wind:vrouter/interface",
              "physical": {
                "name": "ens3",
                "enabled": "true"
              }
            }
          }
        }
      }
    }
  }
}
{
  "notification": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:notification:1.0",
    "eventTime": "2022-10-06T06:44:20.258909358+00:00",
    "push-update": {
      "@xmlns": "urn:ietf:params:xml:ns:yang:ietf-yang-push",
      "id": "20",
      "datastore-contents": {
        "state": {
          "@xmlns": "urn:6wind:vrouter",
          "vrf": {
            "name": "main",
            "interface": {
              "@xmlns": "urn:6wind:vrouter/interface",
              "physical": {
                "name": "ens3",
                "counters": {
                  "in-octets": "30923",
                  "in-unicast-pkts": "175",
                  "in-discards": "0",
                  "in-errors": "0",
                  "out-octets": "6943",
                  "out-unicast-pkts": "55",
                  "out-discards": "0",
                  "out-errors": "0"
                }
              }
            }
          }
        }
      }
    }
  }
}

The on-change functionality is not available for all the leaves. The ones that support it are marked as “(pushed)” in the command-reference.

Alarm example

Virtual Service Router supports the alarm functionality (RFC 8632), which triggers notifications when an alarm is triggered.

The following script subscribes to all the alarms on the system.

#!/usr/bin/env python3
import json
from ncclient import manager
from ncclient.xml_ import to_ele
import xmltodict

create_subscription="""
 <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <filter xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" netconf:type="subtree"
       xmlns:al="urn:ietf:params:xml:ns:yang:ietf-alarms">
    <al:alarm-notification/>
  </filter>
 </create-subscription>
"""

def connect(host, user, password):
    with manager.connect(host=host,
                           username=user,
                           password=password,
                           timeout=10,
                           hostkey_verify=False) as conn:

        # conn.create_subscription(start_time="2020-03-02T15:25:00+00:00") does not work, use dispatch
        # See: https://github.com/ncclient/ncclient/issues/224
        conn.dispatch(to_ele(create_subscription))

        print('Waiting for events')
        while True:
            notification = conn.take_notification()
            print(json.dumps(xmltodict.parse(notification.notification_xml), indent=2))

if __name__ == '__main__':
    connect('<myip>', 'root', '<rootpass>')

The following output is displayed in case the ntp service is configured, but a crash occurs:

{
  "notification": {
    "@xmlns": "urn:ietf:params:xml:ns:netconf:notification:1.0",
    "eventTime": "2022-10-06T06:55:14.351217458+00:00",
    "alarm-notification": {
      "@xmlns": "urn:ietf:params:xml:ns:yang:ietf-alarms",
      "resource": "/vrf[name=\"main\"]/ntp/enabled",
      "alarm-type-id": {
        "@xmlns:vrouter-alarm": "urn:6wind:vrouter/alarm",
        "#text": "vrouter-alarm:service-alarm"
      },
      "alarm-type-qualifier": "ntp",
      "time": "2022-10-06T06:55:14.350704+00:00",
      "perceived-severity": "major",
      "alarm-text": "The ntp service is down when configured up in vrf main."
    }
  }
}

Configured subscriptions via NETCONF

Virtual Service Router can configure subscriptions to send notifications to a remote collector, also called receiver. Configured Subscriptions are specified in the following RFC: https://www.rfc-editor.org/rfc/rfc8639#section-2.5 The content of the notifications headers is described in the draft: https://datatracker.ietf.org/doc/html/draft-ietf-netconf-udp-notif

Examples

To set up a configured subscription, it is necessary to add receivers to the configuration. Then configured subscriptions can use these receivers to send notifications.

First it is necessary to configure a UDP collector, the simplest collector can be a netcat listening on a UDP port:

nc -lu 12345

This netcat server will receive the UDP notifications.

The UDP collector can also be a tool like telemetryd in the pmacct repository. See: https://github.com/pmacct/pmacct To build and use pmtelemetryd, type these commands:

# apt install -y libpcap-dev libjansson-dev
# git clone https://github.com/pmacct/pmacct
# cd pmacct
# ./autogen.sh && ./configure --enable-unyte-udp-notif --enable-jansson && make -j && make install
# echo "telemetry_daemon_decoder: json
telemetry_daemon_udp_notif_port: 12345" > pmtelemetryd.conf
# pmtelemetryd -d -f pmtelemetryd.conf -O /dev/stdout -o /dev/stdout

Then set up a netconf configuration with a receiver and a subscription. The receiver-instance-ref is a reference to a receiver-instance.

It is possible to configure the message segmentation by adding the enable-segmentation and max-segment-size fields. In the following example, the segmentation is enabled. The size of the segments is at most 1400 bytes. If the notification is larger, it will be split into several messages.

Create a netconf_configured_subscribe.py file with this content:

#!/usr/bin/env python3
from ncclient import manager


def connect(host, user, password, collector_addr, collector_port, vrf_name, router_addr):
    conn = manager.connect(host=host,
                           username=user,
                           password=password,
                           timeout=10,
                           hostkey_verify=False)

    conf_sub = """
    <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
      <subscriptions xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
        <subscription>
          <id>1</id>
          <stream>NETCONF</stream>
          <encoding>encode-json</encoding>
          <receivers>
            <receiver>
              <name>name1</name>
              <receiver-instance-ref xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers">receiver1</receiver-instance-ref>
            </receiver>
          </receivers>
          <purpose>send notifications</purpose>
          <source-vrf>{vrf_name}</source-vrf>
          <source-address>{source_addr}</source-address>
        </subscription>
        <receiver-instances xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers">
          <receiver-instance>
            <name>receiver1</name>
            <udp-notif-receiver xmlns="urn:ietf:params:xml:ns:yang:ietf-udp-notif-transport">
              <remote-address>{remote_addr}</remote-address>
              <remote-port>{remote_port}</remote-port>
              <enable-segmentation>true</enable-segmentation>
              <max-segment-size>1400</max-segment-size>
            </udp-notif-receiver>
          </receiver-instance>
        </receiver-instances>
      </subscriptions>
    </config>
    """.format(vrf_name=vrf_name, source_addr=router_addr, remote_addr=collector_addr, remote_port=collector_port)

    send_config = conn.edit_config(target='running', config=conf_sub,
                                default_operation='merge')
    conn.close_session()

if __name__ == '__main__':
    connect('<myip>', 'root', '<rootpass>', '<collector_addr>', '<collector_port>', '<vrf_name>', '<router_addr>')

pmtelemetryd should output telemetry_data which contain the received notification:

{"event_type": "log", "seq": 1, "timestamp": "2023-09-21 17:09:31.632079", "telemetry_node": "127.0.0.1", "telemetry_port": 37181, "telemetry_data": {"ietf-subscribed-notifications:notification": {"eventTime": "2023-09-21T17:09:31.631435329+01:00", "sysName":"hostname", "publisherId":0, "sequenceNumber":1, "ietf-netconf-notifications:netconf-session-start": {"username": "root", "session-id": 5, "source-host": "127.0.0.1"}}}, "serialization": "json"}
{"event_type": "log", "seq": 2, "timestamp": "2023-09-21 17:09:32.192457", "telemetry_node": "127.0.0.1", "telemetry_port": 37181, "telemetry_data": {"ietf-subscribed-notifications:notification": {"eventTime": "2023-09-21T17:09:32.191932567+01:00", "sysName":"hostname", "publisherId":0, "sequenceNumber":2, "ietf-netconf-notifications:netconf-session-end": {"username": "root", "session-id": 5, "source-host": "127.0.0.1", "termination-reason": "closed"}}}, "serialization": "json"}