Understand different types of northbound APIs and their working mechanism.
This section describes the various northbound programmatic APIs in NSO NETCONF, REST, and SNMP. These APIs are used by external systems that need to communicate with NSO, such as portals, OSS, or BSS systems.
NSO has two northbound interfaces intended for human usage, the CLI and the WebUI. These interfaces are described in NSO CLI and Web User Interface respectively.
There are also programmatic Java, Python, and Erlang APIs intended to be used by applications integrated with NSO itself. See Running Application Code for more information about these APIs.
There are two APIs to choose from when an external system should communicate with NSO:
NETCONF
REST
Which one to choose is mostly a subjective matter. REST may, at first sight, appear to be simpler to use, but is not as feature-rich as NETCONF. By using a NETCONF client library such as the open source Java library JNC or Python library ncclient, the integration task is significantly reduced.
Both NETCONF and REST provide functions for manipulating the configuration (including creating services) and reading the operational state from NSO. NETCONF provides more powerful filtering functions than REST.
NETCONF and SNMP can be used to receive alarms as notifications from NSO. NETCONF provides a reliable mechanism to receive notifications over SSH, whereas SNMP notifications are sent over UDP.
Regardless of the protocol you choose for integration, keep in mind all of them communicate with the NSO server over network sockets, which may be unreliable. Additionally, write transactions in NSO can fail if they conflict with another, concurrent transaction. As a best practice, the client implementation should be able to gracefully handle such errors and be prepared to retry requests. For details on the NSO concurrency, refer to the NSO Concurrency Model.
Description of SNMP agent.
The SNMP agent in NSO is used mainly for monitoring and notifications. It supports SNMPv1, SNMPv2c, and SNMPv3.
The following standard MIBs are supported by the SNMP agent:
SNMPv2-MIB RFC 3418
SNMP-FRAMEWORK-MIB RFC 3411
SNMP-USER-BASED-SM-MIB RFC 3414
SNMP-VIEW-BASED-ACM-MIB RFC 3415
SNMP-COMMUNITY-MIB RFC 3584
SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB RFC 3413
SNMP-MPD-MIB RFC 3412
TRANSPORT-ADDRESS-MIB RFC 3419
SNMP-USM-AES-MIB RFC 3826
IPV6-TC RFC 2465
The usmHMACMD5AuthProtocol authentication protocol and the usmDESPrivProtocol privacy protocol specified in SNMP-USER-BASED-SM-MIB are not supported, since they are not considered secure. The usmHMACSHAAuthProtocol authentication protocol specified in SNMP-USER-BASED-SM-MIB and the usmAesCfb128Protocol privacy protocol specified in SNMP-USM-AES-MIB are supported.
The SNMP agent is configured through any of the normal NSO northbound interfaces. It is possible to control most aspects of the agent through for example the CLI.
The YANG models describing all configuration capabilities of the SNMP agent reside under $NCS_DIR/src/ncs/snmp/snmp-agent-config/*.yang in the NSO distribution.
An example session configuring the SNMP agent through the CLI may look like:
The SNMP agent configuration data is stored in CDB as any other configuration data, but is handled as a transformation between the data shown above and the data stored in the standard MIBs.
If you want to have a default configuration of the SNMP agent, you must provide that in an XML file. The initialization data of the SNMP agent is stored in an XML file that has precisely the same format as CDB initialization XML files, but it is not loaded by CDB, rather it is loaded at first startup by the SNMP agent. The XML file must be called snmp_init.xml and it must reside in the load path of NSO. In the NSO distribution, there is such an initialization file in $NCS_DIR/etc/ncs/snmp/snmp_init.xml. It is strongly recommended that this file be customized with another engine ID and other community strings and v3 users.
If no snmp_init.xml file is found in the load path a default configuration with the agent disabled is loaded. Thus, the easiest way to start NSO without the SNMP agent is to ensure that the directory $NCS_DIR/etc/ncs/snmp/ is not part of the NSO load path.
Note, that this only relates to initialization the first time NSO is started. On subsequent starts, all the SNMP agent configuration data is stored in CDB and the snmp_init.xml is never used again.
The NSO SNMP alarm MIB is designed for ease of use in alarm systems. It defines a table of alarms and SNMP alarm notifications corresponding to alarm state changes. Based on the alarm model in NSO (see NSO Alarms), the notifications as well as the alarm table contain the parameters that are required for alarm standards compliance (X.733 and 3GPP). The MIB files are located in $NCS_DIR/src/ncs/snmp/mibs.
TAILF-TOP-MIB.mib The tail-f enterprise OID.
TAILF-TC-MIB.mib Textual conventions for the alarm mib.
TAILF-ALARM-MIB.mib The actual alarm MIB.
IANA-ITU-ALARM-TC-MIB.mib Import of IETF mapping of X.733 parameters.
ITU-ALARM-TC-MIB.mib Import of IETF mapping of X.733 parameters.
The alarm table has the following columns:
tfAlarmIndex An imaginary index for the alarm row that is persistent between restarts.
tfAlarmType This provides an identification of the alarm type and together with tfAlarmSpecificProblem forms a unique identification of the alarm.
tfAlarmDevice The alarming network device - can be NSO itself.
tfAlarmObject The alarming object within the device.
tfAlarmObjectOID In case the original alarm notification was an SNMP notification this column identifies the alarming SNMP object.
tfAlarmObjectStr Name of alarm object based on any other naming.
tfAlarmSpecificProblem This object is used when the 'tfAlarmType' object cannot uniquely identify the alarm type.
tfAlarmEventType The event type according to X.733 and based on the mapping of the alarm type in the NSO alarm model.
tfAlarmProbableCause The probable cause to X.733 and based on the mapping of the alarm type in the NSO alarm model. Note that you can configure this to match the probable cause values in the receiving alarm system.
tfAlarmOrigTime The time for the first occurrence of this alarm.
tfAlarmTime The time for the last state change of this alarm.
tfAlarmSeverity The latest severity (non-clear) reported for this alarm.
tfAlarmCleared Boolean indicated if the latest state change reports a clear.
tfAlarmText The latest alarm text.
tfAlarmOperatorState The latest operator alarm state such as ack.
tfAlarmOperatorNote The latest operator note.
The MIB defines separate notifications for every severity level to support SNMP managers that only can map severity levels to individual notifications. Every notification contains the parameters of the alarm table.
Alarm Managers should subscribe to the notifications and read the alarm table to synchronize the alarm list. To do this you need an access view that matches the alarm MIB and creates a SNMP target. Default SNMP settings in NSO let you read the alarm MIB with v2c and community public. A target is set up in the following way, (assuming the SNMP Alarm Manager has IP address 192.168.1.1 and wants community string public in the v2c notifications):
Description of the RESTCONF API.
RESTCONF is an HTTP-based protocol as defined in RFC 8040. RESTCONF standardizes a mechanism to allow Web applications to access the configuration data, state data, data-model-specific Remote Procedure Call (RPC) operations, and event notifications within a networking device.
RESTCONF uses HTTP methods to provide Create, Read, Update, Delete (CRUD) operations on a conceptual datastore containing YANG-defined data, which is compatible with a server that implements NETCONF datastores as defined in RFC 6241.
Configuration data and state data are exposed as resources that can be retrieved with the GET method. Resources representing configuration data can be modified with the DELETE, PATCH, POST, and PUT methods. Data is encoded with either XML (W3C.REC-xml-20081126) or JSON (RFC 7951).
This section describes the NSO implementation and extension to or deviation from RFC 8040 respectively.
As of this writing, the server supports the following specifications:
RFC 6020 - YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)
RFC 6021 - Common YANG Data Types
RFC 6470 - NETCONF Base Notifications
RFC 6536 - NETCONF Access Control Model
RFC 6991 - Common YANG Data Types
RFC 7950 - The YANG 1.1 Data Modeling Language
RFC 7951 - JSON Encoding of Data Modeled with YANG
RFC 7952 - Defining and Using Metadata with YANG
RFC 8040 - RESTCONF Protocol
RFC 8072 - YANG Patch Media Type
RFC 8341 - Network Configuration Access Control Model
RFC 8525 - YANG Library
RFC 8528 - YANG Schema Mount
I-D.draft-ietf-netconf-restconf-trace-ctx-headers-00 - RESTCONF Extension to support Trace Context Headers
To enable RESTCONF in NSO, RESTCONF must be enabled in the ncs.conf configuration file. The web server configuration for RESTCONF is shared with the WebUI's config, but you may define a separate RESTCONF transport section. The WebUI does not have to be enabled for RESTCONF to work.
Here is a minimal example of what is needed in the ncs.conf.
If you want to run RESTCONF with a different transport configuration than what the WebUI is using, you can specify a separate RESTCONF transport section.
It is now possible to do a RESTCONF requests towards NSO. Any HTTP client can be used, in the following examples curl will be used. The example below will show what a typical RESTCONF request could look like.
In the rest of the document, in order to simplify the presentation, the example above will be expressed as:
Note the HTTP return code (200 OK) in the example, which will be displayed together with any relevant HTTP headers returned and a possible body of content.
Send a RESTCONF query to get a representation of the top-level resource, which is accessible through the path: /restconf.
As can be seen from the result, the server exposes three additional resources:
data: This mandatory resource represents the combined configuration and state data resources that can be accessed by a client.
operations: This optional resource is a container that provides access to the data-model-specific RPC operations supported by the server.
yang-library-version: This mandatory leaf identifies the revision date of the ietf-yang-library YANG module that is implemented by this server. This resource exposes which YANG modules are in use by the NSO system.
data ResourceTo fetch configuration, operational data, or both, from the server, a request to the data resource is made. To restrict the amount of returned data, the following example will prune the amount of output to only consist of the topmost nodes. This is achieved by using the depth query argument as shown in the example below:
Let's assume we are interested in the dhcp/subnet resource in our configuration. In the following examples, assume that it is defined by a corresponding Yang module that we have named dhcp.yang, looking like this:
We can issue an HTTP GET request to retrieve the value content of the resource. In this case, we find that there is no such data, which is indicated by the HTTP return code 204 No Content.
Note also how we have prefixed the dhcp:dhcp resource. This is how RESTCONF handles namespaces, where the prefix is the YANG module name and the namespace is as defined by the namespace statement in the YANG module.
We can now create the dhcp/subnet resource by sending an HTTP POST request + the data that we want to store. Note the Content-Type HTTP header, which indicates the format of the provided body. Two formats are supported: XML or JSON. In this example, we are using XML, which is indicated by the Content-Type value: application/yang-data+xml.
Note the HTTP return code (201 Created) indicating that the resource was successfully created. We also got a Location header, which always is returned in a reply to a successful creation of a resource, stating the resulting URI leading to the created resource.
If we now want to modify a part of our dhcp/subnet config, we can use the HTTP PATCH method, as shown below. Note that the URI used in the request needs to be URL-encoded, such that the key value: 10.254.239.0/27 is URL-encoded as: 10.254.239.0%2F27.
Also, note the difference of the PATCH URI compared to the earlier POST request. With the latter, since the resource does not yet exist, we POST to the parent resource (dhcp:dhcp), while with the PATCH request we address the (existing) resource (10.254.239.0%2F27).
We can also replace the subnet with some new configuration. To do this, we make use of the PUT HTTP method as shown below. Since the operation was successful and no body was returned, we will get a 204 No Content return code.
To delete the subnet, we make use of the DELETE HTTP method as shown below. Since the operation was successful and no body was returned, we will get a 204 No Content return code.
RESTCONF makes it possible to specify where the RESTCONF API is located, as described in the RESTCONF RFC 8040.
As per default, the RESTCONF API root is /restconf. Typically there is no need to change the default value although it is possible to change this by configuring the RESTCONF API root in the ncs.conf file as:
The RESTCONF API root will now be /my_own_restconf_root.
A client may discover the root resource by getting the /.well-known/host-meta resource as shown in the example below:
In this guide, all examples will assume the RESTCONF API root to be /restconf.
A RESTCONF capability is a set of functionality that supplements the base RESTCONF specification. The capability is identified by a uniform resource identifier (URI). The RESTCONF server includes a capability URI leaf-list entry identifying each supported protocol feature. This includes the basic-mode default-handling mode, optional query parameters, and may also include other, NSO-specific, capability URIs.
To view currently enabled capabilities, use the ietf-restconf-monitoring YANG model, which is available as: /restconf/data/ietf-restconf-monitoring:restconf-state.
defaults CapabilityThis Capability identifies the basic-mode default-handling mode that is used by the server for processing default leafs in requests for data resources.
The capability URL will contain a query parameter named basic-mode which value tells us what the default behavior of the RESTCONF server is when it returns a leaf. The possible values are shown in the table below (basic-mode values):
The values presented in the table above can also be used by the Client together with the with-defaults query parameter to override the default RESTCONF server behavior. Added to these values, the Client can also use the report-all-tagged value.
The table below lists additional with-defaults value.
Referring back to the example: Example: NSO RESTCONF Capabilities, where the RESTCONF server returned the default capability:
It tells us that values that have been set by a client to the YANG default value will be reported but default values that have not been set by the Client will not be returned. Again, note that this is the default RESTCONF server behavior which can be overridden by the Client by using the with-defaults query argument.
A set of optional RESTCONF Capability URIs are defined to identify the specific query parameters that are supported by the server. They are defined as:
The table shows query parameter capabilities.
For a description of the query parameter functionality, see Query Parameters.
Each RESTCONF operation allows zero or more query parameters to be present in the request URI. Query parameters can be given in any order, but can appear at most once. Supplying query parameters when invoking RPCs and actions is not supported, if supplied the response will be 400 (Bad Request) and the error-app-tag will be set to invalid-value. However, the query parameters trace-id and unhide are exempted from this rule and supported for RPC and action invocation. The defined query parameters and in what type of HTTP request they can be used are shown in the table below (Query parameters).
content Query ParameterThe content query parameter controls if configuration, non-configuration, or both types of data should be returned. The content query parameter values are listed below.
The allowed values are:
depth Query ParameterThe depth query parameter is used to limit the depth of subtrees returned by the server. Data nodes with a value greater than the depth parameter are not returned in response to a GET request.
The value of the depth parameter is either an integer between 1 and 65535 or the string unbounded. The default value is: unbounded.
fields Query ParameterThe fields query parameter is used to optionally identify data nodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource.
For a full definition of the fields value can be constructed, refer to the RFC 8040, Section 4.8.3.
Note that the fields query parameter cannot be used together with the exclude query parameter. This will result in an error.
exclude Query ParameterThe exclude query parameter is used to optionally exclude data nodes within the target resource from being retrieved with a GET request. The client can use this parameter to exclude a subset of all nodes in a resource. Only nodes below the target resource can be excluded, not the target resource itself.
Note that the exclude query parameter cannot be used together with the fields query parameter. This will result in an error.
The exclude query parameter uses the same syntax and has the same restrictions as the fields query parameter, as defined in RFC 8040, Section 4.8.3.
Selecting multiple nodes to exclude can be done the same way as for the fields query parameter, as described in RFC 8040, Section 4.8.3.
exclude using wildcards (*) will exclude all child nodes of the node. For lists and presence containers, the parent node will be visible in the output but not its children, i.e. it will be displayed as an empty node. For non-presence containers, the parent node will be excluded from the output as well.
exclude can be used together with the depth query parameter to limit the depth of the output. In contrast to fields, where depth is counted from the node selected by fields, for exclude the depth is counted from the target resource, and the nodes are excluded if depth is deep enough to encounter an excluded node.
When exclude is not used:
Using exclude to exclude low and high from range, note that these are absent in the output:
filter, start-time, and stop-time Query ParametersThese query parameters are only allowed on an event stream resource and are further described in Streams.
insert Query ParameterThe insert query parameter is used to specify how a resource should be inserted within an ordered-by user list. The allowed values are shown in the table below (The content query parameter values).
This parameter is only valid if the target data represents a YANG list or leaf-list that is ordered-by user. In the example below, we will insert a new router value, first, in the ordered-by user leaf-list of dhcp-options/router values. Remember that the default behavior is for new entries to be inserted last in an ordered-by user leaf-list.
To verify that the router value really ended up first:
point Query ParameterThe point query parameter is used to specify the insertion point for a data resource that is being created or moved within an ordered-by user list or leaf-list. In the example below, we will insert the new router value: two.acme.org, after the first value: one.acme.org in the ordered-by user leaf-list of dhcp-options/router values.
To verify that the router value really ended up after our insertion point:
There are additional NSO query parameters available for the RESTCONF API. These additional query parameters are described in the table below (Additional Query Parameters).
Two edit collision detection and prevention mechanisms are provided in RESTCONF for the datastore resource: a timestamp and an entity tag. Any change to configuration data resources will update the timestamp and entity tag of the datastore resource. This makes it possible for a client to apply precondition HTTP headers to a request.
The NSO RESTCONF API honors the following HTTP response headers: Etag and Last-Modified, and the following request headers: If-Match, If-None-Match, If-Modified-Since, and If-Unmodified-Since.
Etag: This header will contain an entity tag which is an opaque string representing the latest transaction identifier in the NSO database. This header is only available for the running datastore and hence, only relates to configuration data (non-operational).
Last-Modified: This header contains the timestamp for the last modification made to the NSO database. This timestamp can be used by a RESTCONF client in subsequent requests, within the If-Modified-Since and If-Unmodified-Since header fields. This header is only available for the running datastore and hence, only relates to configuration data (non-operational).
If-None-Match: This header evaluates to true if the supplied value does not match the latest Etag entity-tag value. If evaluated to false, an error response with status 304 (Not Modified) will be sent with no body. This header carries only meaning if the entity tag of the Etag response header has previously been acquired. The usage of this could for example be a HEAD operation to get information if the data has changed since the last retrieval.
If-Modified-Since: This request-header field is used with an HTTP method to make it conditional, i.e if the requested resource has not been modified since the time specified in this field, the request will not be processed by the RESTCONF server; instead, a 304 (Not Modified) response will be returned without any message-body. Usage of this is for instance for a GET operation to retrieve the information if (and only if) the data has changed since the last retrieval. Thus, this header should use the value of a Last-Modified response header that has previously been acquired.
If-Match: This header evaluates to true if the supplied value matches the latest Etag value. If evaluated to false, an error response with status 412 (Precondition Failed) will be sent with no body. This header carries only meaning if the entity tag of the Etag response header has previously been acquired. The usage of this can be in the case of a PUT, where If-Match can be used to prevent the lost update problem. It can check if the modification of a resource that the user wants to upload will not override another change that has been done since the original resource was fetched.
If-Unmodified-Since: This header evaluates to true if the supplied value has not been last modified after the given date. If the resource has been modified after the given date, the response will be a 412 (Precondition Failed) error with no body. This header carries only meaning if the Last-Modified response header has previously been acquired. The usage of this can be the case of a POST, where editions are rejected if the stored resource has been modified since the original value was retrieved.
If rollbacks have been enabled in the configuration using the rollback-id query parameter, the fixed ID of the rollback file created during an operation is returned in the results. The below examples show the creation of a new resource and the removal of that resource using the rollback created in the first step.
Then using the fixed ID returned above as input to the apply-rollback-file action:
The RESTCONF protocol supports YANG-defined event notifications. The solution preserves aspects of NETCONF event notifications [RFC5277] while utilizing the Server-Sent Events, W3C.REC-eventsource-20150203, transport strategy.
RESTCONF event notification streams are described in Sections 6 and 9.2 of RFC 8040, where also notification examples can be found.
RESTCONF event notification is a way for RESTCONF clients to retrieve notifications for different event streams. Event streams configured in NSO can be subscribed to using different channels such as the RESTCONF or the NETCONF channel.
More information on how to define a new notification event using Yang is described in RFC 6020.
How to add and configure notifications support in NSO is described in the ncs.conf(3) man page.
The design of RESTCONF event notification is inspired by how NETCONF event notification is designed. More information on NETCONF event notification can be found in RFC 5277.
For this example, we will define a notification stream, named interface in the ncs.conf configuration file as shown below.
We also enable the built-in replay store which means that NSO automatically stores all notifications on disk, ready to be replayed should a RESTCONF event notification subscriber ask for logged notifications. The replay store uses a set of wrapping log files on a disk (of a certain number and size) to store the notifications.
To view the currently enabled event streams, use the ietf-restconf-monitoring YANG model. The streams are available under the /restconf/data/ietf-restconf-monitoring:restconf-state/streams container.
Note the URL value we get in the location element in the example above. This URL should be used when subscribing to the notification events as is shown in the next example.
RESTCONF clients can determine the URL for the subscription resource (to receive notifications) by sending an HTTP GET request for the location leaf with the stream list entry. The value returned by the server can be used for the actual notification subscription.
The client will send an HTTP GET request for the (location) URL returned by the server with the Accept type text/event-stream as shown in the example below. Note that this request works like a long polling request which means that the request will not return. Instead, server-side notifications will be sent to the client where each line of the notification will be prepended with data:.
Since we have enabled the replay store, we can ask the server to replay any notifications generated since the specific date we specify. After those notifications have been delivered, we will continue waiting for new notifications to be generated.
Errors occurring during streaming of events will be reported as Server-Sent Events (SSE) comments as described in W3C.REC-eventsource-20150203 as shown in the example below.
RFC 8040, Section 3.7 describes the retrieval of YANG modules used by the server via the RPC operation get-schema. The YANG source is made available by NSO in two ways: compiled into the fxs file or put in the loadPath. See Monitoring of the NETCONF Server.
The example below shows how to list the available Yang modules. Since we are interested in the dhcp module, we only show that part of the output:
We can now retrieve the dhcp Yang module via the URL we got in the schema leaf of the reply. Note that the actual URL may point anywhere. The URL is configured by the schemaServerUrl setting in the ncs.conf file.
The NSO RESTCONF API also supports the YANG Patch Media Type, as defined in RFC 8072.
A YANG Patch is an ordered list of edits that are applied to the target datastore by the RESTCONF server. A YANG Patch request is sent as an HTTP PATCH request containing a body describing the edit operations to be performed. The format of the body is defined in the RFC 8072.
Referring to the example above (DHCP Yang model) in the Getting Started section; we will show how to use YANG Patch to achieve the same result but with fewer amount of requests.
To create the resources, we send an HTTP PATCH request where the Content-Type indicates that the body in the request consists of a Yang-Patch message. Our Yang-Patch request will initiate two edit operations where each operation will create a new subnet. In contrast, compare this with using plain RESTCONF where we would have needed two POST requests to achieve the same result.
Let us modify the max-lease-time of one subnet and delete the max-lease-time value of the second subnet. Note that the delete will cause the default value of max-lease-time to take effect, which we will verify using a RESTCONF GET request.
To verify that our modify and delete operations took place we make use of two RESTCONF GET requests as shown below.
Note how we in the last GET request make use of the with-defaults query parameter to request that a default value should be returned and also be tagged as such.
Network Management Datastore Architecture (NMDA), as defined in RFC 8527, extends the RESTCONF protocol. This enables RESTCONF clients to discover which datastores are supported by the RESTCONF server, determine which modules are supported in each datastore, and interact with all the datastores supported by the NMDA.
A RESTCONF client can test if a server supports the NMDA by using either the HEAD or GET methods on /restconf/ds/ietf- datastores:operational, as shown below:
A RESTCONF client can discover which datastores and YANG modules the server supports by reading the YANG library information from the operational state datastore. Note in the example below that, since the result consists of three top nodes, it can't be represented in XML; hence we request the returned content to be in JSON format. See also Collections.
To avoid any potential future conflict with the RESTCONF standard, any extensions made to the NSO implementation of RESTCONF are located under the URL path: /restconf/tailf, or is controlled by means of a vendor-specific media type.
There is no index of extensions under /restconf/tailf. To list extensions, access /restconf/data/ietf-yang-library:modules-state and follow published links for schemas.
The RESTCONF specification states that a result containing multiple instances (e.g. a number of list entries) is not allowed if XML encoding is used. The reason for this is that an XML document can only have one root node.
This functionality is supported if the http://tail-f.com/ns/restconf/collection/1.0 capability is presented. See also How to View the Capabilities of the RESTCONF Server.
To remedy this, an HTTP GET request can make use of the Accept: media type: application/vnd.yang.collection+xml as shown in the following example. The result will then be wrapped within a collection element.
The NSO RESTCONF Query API consists of a number of operations to start a query which may live over several RESTCONF requests, where data can be fetched in suitable chunks. The data to be returned is produced by applying an XPath expression where the data also may be sorted.
The RESTCONF client can check if the NSO RESTCONF server supports this functionality by looking for the http://tail-f.com/ns/restconf/query-api/1.0 capability. See also How to View the Capabilities of the RESTCONF Server.
The tailf-rest-query.yang and the tailf-common-query.yang YANG models describe the structure of the RESTCONF Query API messages. By using the Schema Resource functionality, as described in Schema Resource, you can get hold of them.
The API consists of the following requests:
start-query: Start a query and return a query handle.
fetch-query-result: Use a query handle to repeatedly fetch chunks of the result.
immediate-query: Start a query and return the entire result immediately.
reset-query: (Re)set where the next fetched result will begin from.
stop-query: Stop (and close) the query.
The API consists of the following replies:
start-query-result: Reply to the start-query request.
query-result: Reply to the fetch-query-result and immediate-query requests.
In the following examples, we'll use this data model:
The actual format of the payload should be represented either in XML or JSON. Note how we indicate the type of content using the Content-Type HTTP header. For XML, it could look like this:
The same request in JSON format would look like:
An informal interpretation of this query is:
For each /x/host where enabled is true, select its name, and address, and return the result sorted by name, in chunks of 100 result items at a time.
Let us discuss the various pieces of this request. To start with, when using XML, we need to specify the namespace as shown:
The actual XPath query to run is specified by the foreach element. The example below will search for all /x/host nodes that have the enabled node set to true:
Now we need to define what we want to have returned from the node set by using one or more select sections. What to actually return is defined by the XPath expression.
Choose how the result should be represented. Basically, it can be the actual value or the path leading to the value. This is specified per select chunk. The possible result types are string, path, leaf-value, and inline.
The difference between string and leaf-value is somewhat subtle. In the case of string, the result will be processed by the XPath function: string() (which if the result is a node-set will concatenate all the values). The leaf-value will return the value of the first node in the result. As long as the result is a leaf node, string and leaf-value will return the same result. In the example above, the string is used as shown below. Note that at least one result-type must be specified.
The result-type inline makes it possible to return the full sub-tree of data, either in XML or in JSON format. The data will be enclosed with a tag: data.
It is possible to specify an optional label for a convenient way of labeling the returned data:
The returned result can be sorted. This is expressed as an XPath expression, which in most cases is very simple and refers to the found node-set. In this example, we sort the result by the content of the name node:
With the offset element, we can specify at which node we should start to receive the result. The default is 1, i.e., the first node in the resulting node set.
It is possible to set a custom timeout when starting or resetting a query. Each time a function is called, the timeout timer resets. The default is 600 seconds, i.e. 10 minutes.
The reply to this request would look something like this:
The query handle (in this example '12345') must be used in all subsequent calls. To retrieve the result, we can now send:
Which will result in something like the following:
If we try to get more data with the fetch-query-result, we might get more result entries in return until no more data exists and we get an empty query result back:
Finally, when we are done we stop the query:
If we want to go back into the stream of received data chunks and have them repeated, we can do that with the reset-query request. In the example below, we ask to get results from the 42nd result entry:
If we want to get the entire result sent back to us, using only one request, we can do this by using the immediate-query. This function takes similar arguments as start-query and returns the entire result analogous with the result from a fetch-query-result request. Note that it is not possible to paginate or set an offset start node for the result list; i.e. the options limit and offset are ignored.
This functionality is supported if the http://tail-f.com/ns/restconf/partial-response/1.0 capability is presented. See also How to View the Capabilities of the RESTCONF Server.
By default, the server sends back the full representation of a resource after processing a request. For better performance, the server can be instructed to send only the nodes the client really needs in a partial response.
To request a partial response for a set of list entries, use the offset and limit query parameters to specify a limited set of entries to be returned.
In the following example, we retrieve only two entries, skipping the first entry and then returning the next two entries:
This functionality is supported if the http://tail-f.com/ns/restconf/unhide/1.0 capability is presented. See also How to View the Capabilities of the RESTCONF Server.
By default, hidden nodes are not visible in the RESTCONF interface. To unhide hidden nodes for retrieval or editing, clients can use the query parameter unhide or set parameter showHidden to true under /confdConfig/restconf in confd.conf file. The query parameter unhide is supported for RPC and action invocation.
The format of the unhide parameter is a comma-separated list of
As an example:
This example unhides the unprotected group extra and the password-protected group debug with the password secret;.
This functionality is supported if the urn:ietf:params:xml:ns:yang:traceparent:1.0 and urn:ietf:params:xml:ns:yang:tracestate:1.0 capability is presented. See also How to View the Capabilities of the RESTCONF Server.
RESTCONF supports the IETF standard draft I-D.draft-ietf-netconf-restconf-trace-ctx-headers-00, that is an adaption of the W3C Trace Context standard. Trace Context standardizes the format of trace-id, parent-id, and key-value pairs to be sent between distributed entities. The parent-id will become the parent-span-id for the next generated span-id in NSO.
Trace Context consists of two HTTP headers traceparent and tracestate. Header traceparent must be of the format
where version = "00" and flags = "01". The support for the values of version and flags may change in the future depending on the extension of the standard or functionality.
An example of header traceparent in use is:
Header tracestate is a vendor-specific list of key-value pairs. An example of the header tracestate in use is:
where a value may contain space characters but not end with a space.
NSO implements Trace Context alongside the legacy way of handling trace-id, where the trace-id comes as a query parameter. These two different ways of handling trace-id cannot be used at the same time. If both are used, the request generates an error response. If a request does not include trace-id or the header traceparent, a traceparent will be generated internally in NSO. NSO will consider the headers of Trace Context in RESTCONF requests if the trace-id element is enabled in the configuration file. Trace Context is handled by the progress trace functionality, see also Progress Trace in Development.
It is possible to associate metadata with the configuration data. For RESTCONF, resources such as containers, lists as well as leafs and leaf-lists can have such meta-data. For XML, this meta-data is represented as attributes attached to the XML element in question. For JSON, there does not exist a natural way to represent this info. Hence a special special notation has been introduced, based on the RFC 7952, see the example below.
The meta-data for an object is represented by another object constructed either of an "@" sign if the meta-data object refers to the parent object, or by the object name prefixed with an "@" sign if the meta-data object refers to a sibling object.
Note that the meta-data node types, e.g., tags and annotations, are prefixed by the module name of the YANG module where the meta-data object is defined. This representation conforms to RFC 7952 Section 5.2. The YANG module name prefixes for meta-data node types are listed below:
Compare this to the encoding in NSO versions prior to 6.3, where we represented meta-data for an object by another object constructed of the object name prefixed with either one or two "@" signs. The meta-data object "@x" referred to the sibling object "x" and the "@@x" object referred to the parent object. No module name prefixes were included for the meta-data data object types. This did not conform to RFC 7952 for legacy reasons. See the example below.
To continue using the old meta-data format, set legacy-attribute-format to true in ncs.conf. The default is false, which uses the RFC 7952 format. The legacy-attribute-format setting is deprecated and will be removed in a future release.
It is also possible to set meta-data objects in JSON format, which was previously only possible with XML. Note that the new attribute format must be used and legacy-attribute-format set to false. Except for setting the default and insert meta-data types, which are not supported using JSON.
The RESTCONF server maintains an authentication cache. When authenticating an incoming request for a particular User:Password, it is first checked if the User exists in the cache and if so, the request is processed. This makes it possible to avoid the, potentially time-consuming, login procedure that will take place in case of a cache miss.
Cache entries have a maximum Time-To-Live (TTL) and upon expiry, a cache entry is removed which will cause the next request for that User to perform the normal login procedure. The TTL value is configurable via the auth-cache-ttl parameter, as shown in the example. Note that, by setting the TTL value to PT0S (zero), the cache is effectively turned off.
It is also possible to combine the Client's IP address with the User name as a key into the cache. This behavior is disabled by default. It can be enabled by setting the enable-auth-cache-client-ip parameter to true. With this enabled, only a Client coming from the same IP address may get a hit in the authentication cache.
It is possible to configure the NSO RESTCONF server to pick up the client IP address via an HTTP header in the request. A list of HTTP headers to look for is configurable via the proxy-headers parameter as shown in the example.
To avoid misuse of this feature, only requests from trusted sources will be searched for such an HTTP header. The list of trusted sources is configured via the allowed-proxy-ip-prefix as shown in the example.
The NSO RESTCONF server can be set up to pass a long, a token used for authentication and/or validation of the client. Note that this requires external authentication/validation to be set up properly. See External Token Validation and External Authentication for details.
With token authentication, we mean that the client sends a User:Password to the RESTCONF server, which will invoke an external executable that performs the authentication and upon success produces a token that the RESTCONF server will return in the X-Auth-Token HTTP header of the reply.
With token validation, we mean that the RESTCONF server will pass along any token, provided in the X-Auth-Token HTTP header, to an external executable that performs the validation. This external program may produce a new token that the RESTCONF server will return in the X-Auth-Token HTTP header of the reply.
To make this work, the following need to be configured in the ncs.conf file:
It is also possible to have the RESTCONF server to return a HTTP cookie containing the token.
An HTTP cookie (web cookie, browser cookie) is a small piece of data that a server sends to the user's web browser. The browser may store it and send it back with the next request to the same server. This can be convenient in certain solutions, where typically, it is used to tell if two requests came from the same browser, keeping a user logged in, for example.
To make this happen, the name of the cookie needs to be configured as well as a directives string which will be sent as part of the cookie.
The RESTCONF server can be configured to reply with particular HTTP headers in the HTTP response. For example, to support Cross-Origin Resource Sharing (CORS, https://www.w3.org/TR/cors/) there is a need to add a couple of headers to the HTTP Response.
We add the extra configuration parameter in ncs.conf.
A number of HTTP headers have been deemed so important by security reasons that they, with sensible default values, per default will be included in the RESTCONF reply. The values can be changed by configuration in the ncs.conf file. Note that a configured empty value will effectively turn off that particular header from being included in the RESTCONF reply. The headers and their default values are:
xFrameOptions: DENY
The default value indicates that the page cannot be displayed in a frame/iframe/embed/object regardless of the site attempting to do so.
xContentTypeOptions: nosniff
The default value indicates that the MIME types advertised in the Content-Type headers should not be changed and be followed. In particular, should requests for CSS or Javascript be blocked in case a proper MIME type is not used.
xXssProtection: 1; mode=block
This header is a feature of Internet Explorer, Chrome and Safari that stops pages from loading when they detect reflected cross-site scripting (XSS) attacks. It enables XSS filtering and tells the browser to prevent rendering of the page if an attack is detected.
strictTransportSecurity: max-age=15552000; includeSubDomains
The default value tells browsers that the RESTCONF server should only be accessed using HTTPS, instead of using HTTP. It sets the time that the browser should remember this and states that this rule applies to all of the server's subdomains as well.
contentSecurityPolicy: default-src 'self'; block-all-mixed-content; base-uri 'self'; frame-ancestors 'none';
The default value means that: Resources like fonts, scripts, connections, images, and styles will all only load from the same origin as the protected resource. All mixed contents will be blocked and frame-ancestors like iframes and applets are prohibited.
Swagger is a documentation language used to describe RESTful APIs. The resulting specifications are used to both document APIs as well as generating clients in a variety of languages. For more information about the Swagger specification itself and the ecosystem of tools available for it, see swagger.io.
The RESTCONF API in NSO provides an HTTP-based interface for accessing data. The YANG modules loaded into the system define the schema for the data structures that can be manipulated using the RESTCONF protocol. The yanger tool provides options to generate Swagger specifications from YANG files. The tool currently supports generating specifications according to OpenAPI/Swagger 2.0 using JSON encoding. The tool supports the validation of JSON bodies in body parameters and response bodies, and XML content validation is not supported.
YANG and Swagger are two different languages serving slightly different purposes. YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols such as NETCONF and RESTCONF. Swagger is an API definition language that documents API resource structure as well as HTTP body content validation for applicable HTTP request methods. Translation from YANG to Swagger is not perfect in the sense that there are certain constructs and features in YANG that is not possible to capture completely in Swagger. The design of the translation is designed such that the resulting Swagger definitions are more restrictive than what is expressed in the YANG definitions. This means that there are certain cases where a client can do more in the RESTCONF API than what the Swagger definition expresses. There is also a set of well-known resources defined in the RESTCONF RFC 8040 that are not part of the generated Swagger specification, notably resources related to event streams.
The yanger tool is a YANG parser and validator that provides options to convert YANG modules to a multitude of formats including Swagger. You use the -f swagger option to generate a Swagger definition from one or more YANG files. The following command generates a Swagger file named example.json from the example.yang YANG file:
It is only supported to generate Swagger from one YANG module at a time. It is possible however to augment this module by supplying additional modules. The following command generates a Swagger document from base.yang which is augmented by base-ext-1.yang and base-ext-2.yang:
Only supplying augmenting modules is not supported.
Use the --help option to the yanger command to see all available options:
The complete list of options related to Swagger generation is:
Using the example-jukebox.yang from the RESTCONF RFC 8040, the following example generates a comprehensive Swagger definition using a variety of Swagger-related options:
Description of northbound NETCONF implementation in NSO.
This section describes the northbound NETCONF implementation in NSO. As of this writing, the server supports the following specifications:
: NETCONF Configuration Protocol
: Using the NETCONF Configuration Protocol over Secure Shell (SSH)
: NETCONF Event Notifications
: Partial Lock Remote Procedure Call (RPC) for NETCONF
: YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)
: Common YANG Data Types
: YANG Module for NETCONF Monitoring
: Network Configuration Protocol (NETCONF)
: Using the NETCONF Configuration Protocol over Secure Shell (SSH)
: With-defaults capability for NETCONF
: NETCONF Base Notifications
: NETCONF Access Control Model
: Common YANG Data Types
: YANG Module Library
: The YANG 1.1 Data Modeling Language
: NETCONF Call Home and RESTCONF Call Home
: Network Management Datastore Architecture (NMDA)
: YANG Library
: YANG Schema Mount
: NETCONF Extensions to Support the Network Management Datastore Architecture
: Subscription to YANG Notifications
: Dynamic Subscription to YANG Events and Datastores over NETCONF
: Subscription to YANG Notifications for Datastore Updates
For the <delete-config> operation specified in RFC 4741 / RFC 6241, only <url> with scheme file is supported for the <target> parameter - i.e. no data stores can be deleted. The concept of deleting a data store is not well defined and is at odds with the transaction-based configuration management of NSO. To delete the entire contents of a data store, with full transactional support, a <copy-config> with an empty <config/> element for the <source> parameter can be used.
For the <partial-lock> operation, RFC 5717, section 2.4.1 says that if a node in the scope of the lock is deleted by the session owning the lock, it is removed from the scope of the lock. In NSO this is not true; the deleted node is kept in the scope of the lock.
When integrating NSO into larger OSS/NMS environments, the NETCONF API is a good choice of integration point.
The following list of optional standard capabilities is also supported:
In addition to the protocol capabilities listed above, NSO also implements a set of YANG modules that are closely related to the protocol.
with-defaults: Advertised if the server supports the :with-defaults capability, which NSO does.
configured: Indicates that the server supports configured subscriptions. This feature is not advertised.
dscp: Indicates that the server supports the ability to set the Differentiated Services Code Point (DSCP) value in outgoing packets. This feature is not advertised.
encode-json: Indicates that the server supports JSON encoding of notifications. This is not applicable to NETCONF, and this feature is not advertised.
encode-xml: Indicates that the server supports XML encoding of notifications. This feature is advertised by NSO.
interface-designation: Indicates that a configured subscription can be configured to send notifications over a specific interface. This feature is not advertised.
qos: Indicates that a publisher supports absolute dependencies of one subscription's traffic over another as well as weighted bandwidth sharing between subscriptions. This feature is not advertised.
replay: Indicates that historical event record replay is supported. This feature is advertised by NSO.
subtree: Indicates that the server supports subtree filtering of notifications. This feature is advertised by NSO.
supports-vrf: Indicates that a configured subscription can be configured to send notifications from a specific VRF. This feature is not advertised.
xpath: Indicates that the server supports XPath filtering of notifications. This feature is advertised by NSO.
In addition to this, NSO does not support pre-configuration or monitoring of subtree filters, and thus advertises a deviation module that deviates /filters/stream-filter/filter-spec/stream-subtree-filter and /subscriptions/subscription/target/stream/stream-filter/within-subscription/filter-spec/stream-subtree-filter as "not-supported".
NSO does not generate subscription-modified notifications when the parameters of a subscription change, and there is currently no mechanism to suspend notifications so subscription-suspended and subscription-resumed notifications are never generated.
There is basic support for monitoring subscriptions via the /subscriptions container. Currently, it is possible to view dynamic subscriptions' attributes: subscription-id, stream, encoding, receiver, stop-time, and stream-xpath-filter. Unsupported attributes are: stream-subtree-filter, receiver/sent-event-records, receiver/excluded-event-records, and receiver/state.
on-change: Indicates that on-change triggered notifications are supported. This feature is advertised by NSO but only supported on the running datastore.
In addition to this, NSO does not support pre-configuration or monitoring of subtree filters and thus advertises a deviation module that deviates /filters/selection-filter/filter-spec/datastore-subtree-filter and /subscriptions/subscription/target/datastore/selection-filter/within-subscription/filter-spec/datastore-subtree-filter as "not-supported".
The monitoring of subscriptions via the subscriptions container does currently not support the attributes: periodic/period, periodic/state, on-change/dampening-period, on-change/sync-on-start, on-change/excluded-change.
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 its fxs file is found in NSO's loadPath, and if the fxs file is exported to NETCONF.
The following YANG modules are built-in, which means that their fxs files need not be present in the loadPath. If they are found in the loadPath they are skipped.
ietf-netconf
ietf-netconf-with-defaults
ietf-yang-library
ietf-yang-types
ietf-inet-types
ietf-restconf
ietf-datastores
ietf-yang-patch
All built-in modules are always supported by the server.
All YANG version 1 and version 1.1 modules supported by the server are advertised in the YANG library.
For example, to get the YANG library data for the device x0, we can do:
The set of modules reported for a device is the set of modules that NSO knows, i.e., the set of modules compiled for the specific device type. This means that all devices of the same device type will report the same set of modules. Also, note that the device may support other modules that are not known to NSO. Such modules are not reported here.
The NETCONF server natively supports the mandatory SSH transport, i.e., SSH is supported without the need for an external SSH daemon (such as sshd). It also supports integration with OpenSSH.
NSO 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 NSO; it reads data from the ssh daemon from standard input and writes the data to NSO over a loopback socket, and vice versa. This program is delivered as source code in $NCS_DIR/src/ncs/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 NSO. 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:
The connection from netconf-subsys to NSO 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 NSO is configured to give access to the group(s) the user belongs to. The easiest for test is to give access to all groups.
When NSO processes <get>, <get-config>, and <copy-config> requests, the resulting data set can be very large. To avoid buffering huge amounts of data, NSO streams the reply to the client as it traverses the data tree and calls data provider functions to retrieve the data.
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:
If a get_next call fails in the processing of a list, a reply might look like this:
netconf-consoleThe netconf-console program is a simple NETCONF client. It is delivered as Python source code and can be used as-is or modified.
When NSO has been started, we can use netconf-console to query the configuration of the NETCONF Access Control groups:
With the -x flag an XPath expression can be specified, to retrieve only data matching that expression. This is a very convenient way to extract portions of the configuration from the shell or from shell scripts.
This data model defines an RPC operation, get-schema, which is used to retrieve YANG modules from the NETCONF server. NSO will report the YANG modules for all fxs files that are reported as capabilities, and for which the corresponding YANG or YIN file is stored in the fxs file or found in the loadPath. If a file is found in the loadPath, it has priority over a file stored in the fxs file. Note that by default, the module and its submodules are stored in the fxs file by the compiler.
If the YANG (or YIN files) are copied into the loadPath, they can be stored as is or compressed with gzip. The filename extension MUST be .yang, .yin, .yang.gz, or .yin.gz.
Also available is a Tail-f-specific data model, tailf-netconf-monitoring, which augments ietf-netconf-monitoring with additional data about files available for usage with the <copy-config> command with a file <url> source or target. /ncs-config/netconf-north-bound/capabilities/url/enabled and /ncs-config/netconf-north-bound/capabilities/url/file/enabled must both be set to true. If rollbacks are enabled, those files are listed as well, and they can be loaded using <copy-config>.
This data model also adds data about which notification streams are present in the system and data about sessions that subscribe to the streams.
This section describes how NETCONF notifications are implemented within NSO, and how the applications generate these events.
Central to NETCONF notifications is the concept of a stream. The stream serves two purposes. It works like a high-level filtering mechanism for the client. For example, if the client subscribes to notifications on the security stream, it can expect to get security-related notifications only. Second, each stream may have its own log mechanism. For example, by keeping all debug notifications in a debug stream, they can be logged separately from the security stream.
NSO can be configured to listen to notifications from devices and send those notifications to northbound NETCONF clients. The stream device-notifications is used for this purpose. To enable this, the stream device-notifications must be configured in ncs.conf, and additionally, subscriptions must be created in /ncs:devices/device/notifications.
The well-known stream NETCONF does not have to be listed, but if it isn't listed, it will not support replay.
NSO has built-in support for logging of notifications, i.e., if replay support has been enabled for a stream, NSO automatically stores all notifications on disk ready to be replayed should a NETCONF client ask for logged notifications. In the ncs.conf fragment above the security stream has been set up to use the built-in notification log/replay store. The replay store uses a set of wrapping log files on a 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. are also kept to a minimum, i.e., automatically taken care of by NSO.
This section describes how Subscribed Notifications are implemented for NETCONF within NSO.
Multiple subscriptions on a single transport session
Support for dynamic and configured subscriptions
Modification of an existing subscription in progress
Per-subscription operational counters
Negotiation of subscription parameters (through the use of hints returned as part of declined subscription requests)
Subscription state change notifications (e.g., publisher-driven suspension, parameter modification)
Independence from transport
Both NETCONF notifications and Subscribed Notifications can be used at the same time and are configured the same way in ncs.conf. However, there are some differences and limitations.
For Subscribed Notifications, a new subscription is requested by invoking the RPC establish-subscription. For NETCONF notifications, the corresponding RPC is create-subscription.
A NETCONF session can only have either the subscribers started with create-subscription or establish-subscription simultaneously.
If a session has subscribers established with establish-subscription and receives a request to create subscriptions with create-subscription, an <rpc-error> is sent containing <error-tag> operation-not-supported.
If a session has subscribers created with create-subscription and receives a request to establish subscriptions with establish-subscription, an <rpc-error> is sent containing <error-tag> operation-not-supported.
Dynamic subscriptions send all notifications on the transport session where they were established.
Existing subscriptions and their configuration can be found in the /subscriptions container.
For example, for viewing all established subscriptions, we can do:
It is not possible to establish a subscription with a stored filter from /filters.
The support for monitoring subscriptions has basic functionality. It is possible to read subscription-id, stream, stream-xpath-filter, replay-start-time, stop-time, encoding, receivers/receiver/name, and receivers/receiver/state.
The leaf stream-subtree-filter is deviated as "not-supported", hence can not be read.
The unsupported leafs in the subscriptions container are the following: stream-subtree-filter, receiver/sent-event-records, and receiver/excluded-event-records.
This section describes how YANG-Push is implemented for NETCONF within NSO.
push-update notification is a complete, filtered update that reflects the data of the subscribed datastore. It is the type of notification that is used for periodic subscriptions. A push-update notification can also be used for the on-change subscriptions in case of a receiver asks for synchronization, either at the start of a new subscription or by sending a resync request for an established subscription.
An example push-update notification:
An example push-change-update notification:
For periodic subscriptions, updates are triggered periodically according to specified time interval. Optionally a reference anchor-time can be provided for a specified period.
For on-change subscriptions, updates are triggered whenever a change is detected on the subscribed information. In the case of rapidly changing data, instead of receiving frequent notifications for every change, a receiver may specify a dampening-period to receive update notifications in a lower frequency. A receiver may request for synchronization at the start of a subscription by using sync-on-start option. A receiver may filter out specific types of changes by providing a list of excluded-change parameters.
In addition to RPCs defined in subscribed notifications, YANG-Push defines resync-subscription RPC. Upon receipt of resync-subscription, if the subscription is an on-change triggered type, a push-update notification is sent to the receiver according to the terms of the subscription. Otherwise, an appropriate error response is sent.
resync-subscription
YANG-Push filters differ from the filters of Subscribed Notifications and they are specified as datastore-xpath-filter and datastore-subtree-filter. The leaf datastore-subtree-filter is deviated as "not-supported", and hence can not be monitored. Also, YANG-Push specific update trigger parameters periodic/period, periodic/anchor-time, on-change/dampening-period, on-change/sync-on-start and on-change/excluded-change are not supported for monitoring.
modify-subscriptions operation does not support changing a subscriptions update trigger type from periodic to on-change or vice versa.
on-change subscriptions do not work for changes that are made through the CDB-API.
on-change subscriptions do not work on internal callpoints such as ncs-state, ncs-high-availability, and live-status.
This capability is deprecated since actions are now supported in standard YANG 1.1. It is recommended to use standard YANG 1.1 for actions.
This capability introduces a new RPC operation that is used to invoke actions defined in the data model. When an action is invoked, the instance on which the action is invoked is explicitly identified by a hierarchy of configuration or state data.
Here is a simple example that invokes the action sync-from on the device ce1. It uses the netconf-console command:
The actions capability is identified by the following capability string:
This capability introduces four new RPC operations that 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. It is recommended that this module be enabled.
A typical sequence of operations looks like this:
None.
The transactions capability is identified by the following capability string:
<start-transaction>Starts a transaction towards a configuration datastore. There can be a single ongoing transaction per session at any time.
When a transaction has been started, the client can send any NETCONF operation, but any <edit-config> or <copy-config> operation sent from the client must specify the same <target> as the <start-transaction>, and any <get-config> must specify the same <source> as <start-transaction>.
If the server receives an <edit-config> or <copy-config> with another <target>, or a <get-config> with another <source>, an error must be returned with an <error-tag> set to invalid-value.
The modifications sent in the <edit-config> operations are not immediately applied to the configuration datastore. Instead, they are kept in the transaction state of the server. The transaction state is only applied when a <commit-transaction> is received.
The client sends a <prepare-transaction> when all modifications have been sent.
target:
Name of the configuration datastore towards which the transaction is started.
with-inactive:
If this parameter is given, the transaction will handle the inactive and active attributes. If given, it must also be given in the <edit-config> and <get-config> invocations in the transaction.
If the device can satisfy the request, an <rpc-reply> is sent that contains an <ok> element.
An <rpc-error> element is included in the <rpc-reply> if the request cannot be completed for any reason.
If there is an ongoing transaction for this session already, an error must be returned with <error-app-tag> set to bad-state.
<prepare-transaction>Prepares the transaction state for commit. The server may reject the prepare request for any reason, for example, due to lack of resources or if the combined changes would result in an invalid configuration datastore.
After a successful <prepare-transaction>, the next transaction-related RPC operation must be <commit-transaction> or <abort-transaction>. Note that an <edit-config> cannot be sent before the transaction is either committed or aborted.
Care must be taken by the server to make sure that if <prepare-transaction> succeeds then the <commit-transaction> should not fail, since this might result in an inconsistent distributed state. Thus, <prepare-transaction> should allocate any resources needed to make sure the <commit-transaction> will succeed.
None.
If the device was able to satisfy the request, an <rpc-reply> is sent that contains an <ok> element.
An <rpc-error> element is included in the <rpc-reply> if the request cannot be completed for any reason.
If there is no ongoing transaction in this session, or if the ongoing transaction already has been prepared, an error must be returned with <error-app-tag> set to bad-state.
<commit-transaction>Applies the changes made in the transaction to the configuration datastore. The transaction is closed after a <commit-transaction>.
None.
If the device was able to satisfy the request, an <rpc-reply> is sent that contains an <ok> element.
An <rpc-error> element is included in the <rpc-reply> if the request cannot be completed for any reason.
If there is no ongoing transaction in this session, or if the ongoing transaction already has not been prepared, an error must be returned with <error-app-tag> set to bad-state.
<abort-transaction>Aborts the ongoing transaction, and all pending changes are discarded. <abort-transaction> can be given at any time during an ongoing transaction.
None.
If the device was able to satisfy the request, an <rpc-reply> is sent that contains an <ok> element.
An <rpc-error> element is included in the <rpc-reply> if the request cannot be completed for any reason.
If there is no ongoing transaction in this session, an error must be returned with <error-app-tag> set to bad-state.
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 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.
To not confuse clients who 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 to make it active, the active XML attribute 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:
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 that is inactive will fail, and an attempt to delete a node that is inactive will succeed. Further, the NETCONF server accepts the inactive and active attributes in the data hierarchy, 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.
This request creates an inactive interface:
This request shows the inactive interface:
This request shows that inactive data is not returned unless the client asks for it:
This request activates the interface:
This request creates an inactive interface:
This module extends existing operations with a with-rollback-id parameter which will, when set, extend the result with information about the rollback that was generated for the operation if any.
The rollback ID returned is the ID from within the rollback file which is stable with regards to new rollbacks being created.
None.
The transactions capability is identified by the following capability string:
This module adds a parameter with-rollback-id to the following RPCs:
If with-rollback-id is given, rollbacks are enabled, and the operation results in a rollback file being created the response will contain a rollback reference.
Trace Context consists of two XML attributes traceparent and tracestate corresponding to the capabilities urn:ietf:params:xml:ns:yang:traceparent:1.0 and urn:ietf:params:xml:ns:yang:tracestate:1.0 respectively. The attributes belong to the start XML element rpc in a NETCONF request.
Attribute traceparent must be of the format:
where version = "00" and flags = "01". The support for the values of version and flags may change in the future depending on the extension of the standard or functionality.
Attribute tracestate is a vendor-specific list of key-value pairs and must be of the format:
Where a value may contain space characters but not end with a space.
Here is an example of the usage of the attributes traceparent and tracestate:
The YANG module tailf-netconf-ncs augments some NETCONF operations with additional parameters to control the behavior in NSO over NETCONF. See that YANG module for all the details. In this section, the options are summarized.
To control the commit behavior of NSO the following input parameters are available:
no-revision-drop
NSO will not run its data model revision algorithm, which requires all participating managed devices to have all parts of the data models for all data contained in this transaction. Thus, this flag forces NSO to never silently drop any data set operations towards a device.
no-overwrite
NSO will check that the data that should be modified has not changed on the device compared to NSO's view of the data.
no-networking
Do not send any data to the devices. This is a way to manipulate CDB in NSO without generating any southbound traffic.
no-out-of-sync-check
Continue with the transaction even if NSO detects that a device's configuration is out of sync.
no-deploy
Commit without invoking the service create method, i.e., write the service instance data without activating the service(s). The service(s) can later be redeployed to write the changes of the service(s) to the network.
reconcile/keep-non-service-config
Reconcile the service data. All data which existed before the service was created will now be owned by the service. When the service is removed that data will also be removed. In technical terms, the reference count will be decreased by one for everything that existed prior to the service. If manually configured data exists below in the configuration tree that data is kept.
reconcile/discard-non-service-config
Reconcile the service data but do not keep manually configured data that exists below in the configuration tree.
use-lsa
Force handling of the LSA nodes as such. This flag tells NSO to propagate applicable commit flags and actions to the LSA nodes without applying them on the upper NSO node itself. The commit flags affected are dry-run, no-networking, no-out-of-sync-check, no-overwrite and no-revision-drop.
no-lsa
Do not handle any of the LSA nodes as such. These nodes will be handled as any other device.
commit-queue/async
Commit the transaction data to the commit queue. The operation returns successfully if the transaction data has been successfully placed in the queue.
commit-queue/sync/timeout
Commit the transaction data to the commit queue. The operation does not return until the transaction data has been sent to all devices, or a timeout occurs. The timeout value specifies a maximum number of seconds to wait for the completion.
commit-queue/sync/infinity
Commit the transaction data to the commit queue. The operation does not return until the transaction data has been sent to all devices.
commit-queue/bypass
If /devices/global-settings/commit-queue/enabled-by-default is true the data in this transaction will bypass the commit queue. The data will be written directly to the devices.
commit-queue/atomic
Sets the atomic behavior of the resulting queue item. Possible values are: true and false. If this is set to false, the devices contained in the resulting queue item can start executing if the same devices in other non-atomic queue items ahead of it in the queue are completed. If set to true, the atomic integrity of the queue item is preserved.
commit-queue/block-others
The resulting queue item will block subsequent queue items, which use any of the devices in this queue item, from being queued.
commit-queue/lock
Place a lock on the resulting queue item. The queue item will not be processed until it has been unlocked, see the actions unlock and lock in /devices/commit-queue/queue-item. No following queue items, using the same devices, will be allowed to execute as long as the lock is in place.
commit-queue/tag
The value is a user-defined opaque tag. The tag is present in all notifications and events sent referencing the specific queue item.
These optional input parameters are augmented into the following NETCONF operations:
commit
edit-config
copy-config
prepare-transaction
The operation prepare-transaction is also augmented with an optional parameter dry-run, which can be used to show the effects that would have taken place, but not actually commit anything to the datastore or to the devices. dry-run takes an optional parameter outformat, which can be used to select in which format the result is returned. Possible formats are xml (default), cli, and native. The optional reverse parameter can be used together with the native format to display the device commands for getting back to the current running state in the network if the commit is successfully executed. Beware that if any changes are done later on the same data the reverse device commands returned are invalid.
FASTMAP attributes such as back pointers and reference counters are typically internal to NSO and are not shown by default. The optional parameter with-service-meta-data can be used to include these in the NETCONF reply. The parameter is augmented into the following NETCONF operations:
get
get-config
get-data
The Query API consists of several RPC operations to start queries, fetch chunks of the result from a query, restart a query, and stop a query.
In the installed release there are two YANG files named tailf-netconf-query.yang and tailf-common-query.yang that defines these operations. An easy way to find the files is to run the following command from the top directory of the release installation:
The API consists of the following operations:
start-query: Start a query and return a query handle.
fetch-query-result: Use a query handle to repeatedly fetch chunks of the result.
immediate-query: Start a query and return the entire result immediately.
reset-query: (Re)set where the next fetched result will begin from.
stop-query: Stop (and close) the query.
In the following examples, the following data model is used:
Here is an example of a start-query operation:
An informal interpretation of this query is:
For each /x/host where enabled is true, select its name, and address, and return the result sorted by name, in chunks of 100 results at the time.
Let us discuss the various pieces of this request.
The actual XPath query to run is specified by the foreach element. The example below will search for all /x/host nodes that have the enabled node set to true:
Now we need to define what we want to have returned from the node set by using one or more select sections. What to actually return is defined by the XPath expression.
We must also choose how the result should be represented. Basically, it can be the actual value or the path leading to the value. This is specified per select chunk The possible result types are: string , path , leaf-value and inline.
The difference between string and leaf-value is somewhat subtle. In this case of string the result will be processed by the XPath function string() (which if the result is a node-set will concatenate all the values). The leaf-value will return the value of the first node in the result. As long as the result is a leaf node, string and leaf-value will return the same result. In the example above, we are using string as shown below. At least one result-type must be specified.
The result-type inline makes it possible to return the full sub-tree of data in XML format. The data will be enclosed with a tag: data.
Finally, we can specify an optional label for a convenient way of labeling the returned data. In the example we have the following:
The returned result can be sorted. This is expressed as XPath expressions, which in most cases are very simple and refer to the found node-set. In this example, we sort the result by the content of the name node:
To limit the maximum amount of results in each chunk that fetch-query-result will return we can set the limit element. The default is to get all results in one chunk.
With the offset element we can specify at which node we should start to receive the result. The default is 1, i.e., the first node in the resulting node set.
Now, if we continue by putting the operation above in a file query.xml we can send a request, using the command netconf-console, like this:
The result would look something like this:
The query handle (in this example 12345) must be used in all subsequent calls. To retrieve the result, we can now send:
Which will result in something like the following:
If we try to get more data with the fetch-query-result we might get more result entries in return until no more data exists and we get an empty query result back:
If we want to send the query and get the entire result with only one request, we can do this by using immediate-query. This function takes similar arguments as start-query and returns the entire result analogous fetch-query-result. Note that it is not possible to paginate or set an offset start node for the result list; i.e. the options limit and offset are ignored.
An example request and response:
If we want to go back in the "stream" of received data chunks and have them repeated, we can do that with the reset-query operation. In the example below, we ask to get results from the 42nd result entry:
Finally, when we are done we stop the query:
NSO supports three pieces of meta-data data nodes: tags, annotations, and inactive.
An annotation is a string that acts as a comment. Any data node present in the configuration can get an annotation. An annotation does not affect the underlying configuration but can be set by a user to comment what the configuration does.
An annotation is encoded as an XML attribute annotation on any data node. To remove an annotation, set the annotation attribute to an empty string.
Any configuration data node can have a set of tags. Tags are set by the user for data organization and filtering purposes. A tag does not affect the underlying configuration.
All tags on a data node are encoded as a space-separated string in an XML attribute tags. To remove all tags, set the tags attribute to an empty string.
Annotation, tags, and inactive attributes can be present in <edit-config>, <copy-config>, <get-config>, and <get>. For example:
NSO adds an additional namespace which is used to define elements that are included in the <error-info> element. This namespace also describes which <error-app-tag/> elements the server might generate, as part of an <rpc-error/>.
| Value | Description |
|---|---|
| Value | Description |
|---|---|
| Name | URI |
|---|---|
| Name | Method | Description |
|---|---|---|
| Value | Description |
|---|---|
| Value | Description |
|---|---|
| Name | Methods | Description |
|---|---|---|
| Meta-data type | Prefix |
|---|---|
NSO NETCONF northbound API can be used by arbitrary NETCONF clients. A simple Python-based NETCONF client called netconf-console is shipped as source code in the distribution. See for details. Other NETCONF clients will work too, as long as they adhere to the NETCONF protocol. If you need a Java client, the open-source client can be used.
The NETCONF server in NSO supports the following capabilities in both NETCONF 1.0 () and NETCONF 1.1 ().
| Capability | Description |
|---|
| Capability | Description |
|---|
ietf-netconf-nmda: This module from defines the NMDA extension to NETCONF. It defines the following features:
origin: Indicates that the server supports the origin annotation. It is not advertised by default. The support for origin can be enabled in ncs.conf (see in Manual Pages ). If it is enabled, the origin feature is advertised.
ietf-subscribed-notifications: This module from defines operations, configuration data nodes, and operational state data nodes related to notification subscriptions. It defines the following features:
ietf-yang-push: This module from extends operations, data nodes, and operational state defined in ietf-subscribed-notifications; and also introduces continuous and customizable notification subscriptions for updates from running and operational datastores. It defines the same features as ietf-subscribed-notifications and also the following feature:
All YANG version 1 modules supported by the server are advertised in the hello message, according to the rules defined in .
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 .
NSO uses to mount the data models for the devices. There are two mount points, one for the configuration (in /devices/device/config), and one for operational state data (in /devices/device/live-status). As defined in , a client can read the module list from the YANG library in each of these mount points to learn which YANG models each device supports via NSO.
Make sure NSO is configured to listen to TCP traffic on localhost, port 2023, and disable SSH in ncs.conf (see in Manual Pages ). (Re)start sshd and NSO. Or:
Compile netconf-subsys to use a connection to the IPC port instead of the NETCONF TCP transport (see the netconf-subsys.c source for details), and disable both TCP and SSH in ncs.conf. (Re)start sshd and NSO. This method may be preferable since it makes it possible to use the IPC Access Check (see ) to restrict the unauthenticated access to NSO that is needed by netconf-subsys.
NSO itself is configured through a configuration file called ncs.conf. For a description of the parameters in this file, please see the in Manual Pages man page.
If a data provider fails to return the data it is supposed to return, NSO 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 /ncs-config/netconf/rpc-errors configuration parameter (see in Manual Pages).
defines a YANG module, ietf-netconf-monitoringfor monitoring of the NETCONF server. It contains statistics objects such as the number of RPCs received, status objects such as user sessions, and an operation to retrieve data models from the NETCONF server.
NSO has built-in support for the well-known stream NETCONF, defined in and . NSO supports the notifications defined in 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 streams it supports. In NSO, this is done in ncs.conf (see in Manual Pages). Each stream must be listed, and whether it supports replay or not. The following example enables the built-in stream device-notifications with replay support, and an additional, application-specific stream debug without replay support:
Subscribed Notifications is defined in and the NETCONF transport binding is defined in . Subscribed Notifications build upon NETCONF notifications defined in and have a number of key improvements:
YANG-Push is defined in and the NETCONF transport binding is defined in . YANG-Push implementation in NSO introduces a subscription service that provides updates from a datastore. This implementation supports dynamic subscriptions on updates of datastore nodes. A subscribed receiver is provided with update notifications according to the terms of the subscription. There are two types of notification messages defined to provide updates and these are used according to subscription terms.
push-change-update notification is the most common type of notification that is used for on-change subscriptions. It provides a set of filtered changes that happened on the subscribed datastore since the last update notification. The update records are constructed in the form of YANG-Patch Media Type that is defined in .
To provide updates for on-change subscriptions on operational datastore, data provider applications are required to implement push-on-change callbacks. For more details, see the in the Manual Pages section of in Manual Pages.
YANG-Push subscriptions can be monitored in a similar way to Subscribed Notifications through /subscriptions container. For more information, see .
NETCONF supports the IETF standard draft , that is an adaption of the standard. Trace Context standardizes the format of trace-id, parent-id, and key-value pairs sent between distributed entities. The parent-id will become the parent-span-id for the next generated span-id in NSO.
NSO implements Trace Context alongside the legacy way of handling trace-id found in . The support of Trace Context covers the same scenarios as the legacy trace-id functionality, except for the scenario where both trace-id and Trace Context are absent in a request, in which case legacy trace-id is generated. The two different ways of handling trace-id cannot be used at the same time. If both are used, the request generates an error response. Read about trace-id legacy functionality in .
NETCONF also lets LSA clusters to be part of Trace Context handling. A top LSA node will pass down the Trace Context to all LSA nodes beneath. For NSO to consider the attributes of Trace Context in a NETCONF request, the trace-id element in the configuration file must be enabled. As Trace Context is handled by the progress trace functionality, see also .
commit-queue/error-option
The error option to use. Depending on the selected error option NSO will store the reverse of the original transaction to be able to undo the transaction changes and get back to the previous state. This data is stored in the /devices/commit-queue/completed tree from where it can be viewed and invoked with the rollback action. When invoked the data will be removed. Possible values are: continue-on-error, rollback-on-error, and stop-on-error. The continue-on-error value means that the commit queue will continue on errors. No rollback data will be created. The rollback-on-error value means that the commit queue item will roll back on errors. The commit queue will place a lock with block-others on the devices and services in the failed queue item. The rollback action will then automatically be invoked when the queue item has finished its execution. The lock will be removed as part of the rollback. The stop-on-error means that the commit queue will place a lock with block-others on the devices and services in the failed queue item. The lock must then either manually be released when the error is fixed or the rollback action under /devices/commit-queue/completed be invoked.
Read about error recovery in for a more detailed explanation.
trace-id
Use the provided trace ID as part of the log messages emitted while processing. If no trace ID is given, NSO will generate and assign a trace ID to the processing.
Note: trace-id within NETCONF extensions is deprecated from NSO version 6.3. Capabilities within Trace Context will provide support for trace-id, see the section .
report-all
Values set to the YANG default value are reported.
trim
Values set to the YANG default value are not reported.
explicit
Values that has been set by a client to the YANG default value will be reported.
report-all-tagged
Works as the report-all but a default value will include an XML/JSON attribute to indicate that the value is in fact a default value.
depth
urn:ietf:params:restconf:capability:depth:1.0
fields
urn:ietf:params:restconf:capability:fields:1.0
filter
urn:ietf:params:restconf:capability:filter:1.0
replay
urn:ietf:params:restconf:capability:replay:1.0
with.defaults
urn:ietf:params:restconf:capability:with.defaults:1.0
content
GET,HEAD
Select config and/or non-config data resources.
depth
GET,HEAD
Request limited subtree depth in the reply content.
fields
GET,HEAD
Request a subset of the target resource contents.
exclude
GET,HEAD
Exclude a subset of the target resource contents.
filter
GET,HEAD
Boolean notification filter for event stream resources.
insert
POST,PUT
Insertion mode for ordered-by user data resources
point
POST,PUT
Insertion point for ordered-by user data resources
start-time
GET,HEAD
Replay buffer start time for event stream resources.
stop-time
GET,HEAD
Replay buffer stop time for event stream resources.
with-defaults
GET,HEAD
Control the retrieval of default values.
with-origin
GET
Include the "origin" metadata annotations, as detailed in the NMDA.
config
Return only configuration descendant data nodes.
nonconfig
Return only non-configuration descendant data nodes.
all
Return all descendant data nodes.
first
Insert the new data as the new first entry.
last
Insert the new data as the new last entry. This is the default value.
before
Insert the new data before the insertion point, as specified by the value of the point parameter.
after
Insert the new data after the insertion point, as specified by the value of the point parameter.
dry-run
POST
PUT
PATCH
DELETE
Validate and display the configuration changes but do not perform the actual commit. Neither CDB nor the devices are affected. Instead, the effects that would have taken place are shown in the returned output. Possible values are: xml, cli, and native. The value used specifies in what format we want the returned diff to be.
dry-run-reverse
POST
PUT
PATCH
DELETE
Used together with the dry-run=native parameter to display the device commands for getting back to the current running state in the network if the commit is successfully executed. Beware that if any changes are done later on the same data the reverse device commands returned are invalid.
no-networking
POST
PUT
PATCH
DELETE
Do not send any data to the devices. This is a way to manipulate CDB in NSO without generating any southbound traffic.
no-out-of-sync-check
POST
PUT
PATCH
DELETE
Continue with the transaction even if NSO detects that a device's configuration is out of sync. Can't be used together with no-overwrite.
no-overwrite
POST
PUT
PATCH
DELETE
NSO will check that the data that should be modified has not changed on the device compared to NSO's view of the data. Can't be used together with no-out-of-sync-check.
no-revision-drop
POST
PUT
PATCH
DELETE
NSO will not run its data model revision algorithm, which requires all participating managed devices to have all parts of the data models for all data contained in this transaction. Thus, this flag forces NSO to never silently drop any data set operations towards a device.
no-deploy
POST
PUT
PATCH
DELETE
Commit without invoking the service create method, i.e, write the service instance data without activating the service(s). The service(s) can later be re-deployed to write the changes of the service(s) to the network.
reconcile
POST
PUT
PATCH
DELETE
Reconcile the service data. All data which existed before the service was created will now be owned by the service. When the service is removed that data will also be removed. In technical terms, the reference count will be decreased by one for everything that existed prior to the service. If the manually configured data exists below in the configuration tree, that data is kept unless the option discard-non-service-config is used.
use-lsa
POST
PUT
PATCH
DELETE
Force handling of the LSA nodes as such. This flag tells NSO to propagate applicable commit flags and actions to the LSA nodes without applying them on the upper NSO node itself. The commit flags affected are dry-run, no-networking, no-out-of-sync-check, no-overwrite and no-revision-drop.
no-lsa
POST
PUT
PATCH
DELETE
Do not handle any of the LSA nodes as such. These nodes will be handled as any other device.
commit-queue
POST
PUT
PATCH
DELETE
Commit the transaction data to the commit queue. Possible values are: async, sync, and bypass. If the async value is set the operation returns successfully if the transaction data has been successfully placed in the queue. The sync value will cause the operation to not return until the transaction data has been sent to all devices, or a timeout occurs. The bypass value means that if /devices/global-settings/commit-queue/enabled-by-default is true the data in this transaction will bypass the commit queue. The data will be written directly to the devices.
commit-queue-atomic
POST
PUT
PATCH
DELETE
Sets the atomic behavior of the resulting queue item. Possible values are: true and false. If this is set to false, the devices contained in the resulting queue item can start executing if the same devices in other non-atomic queue items ahead of it in the queue are completed. If set to true, the atomic integrity of the queue item is preserved.
commit-queue-block-others
POST
PUT
PATCH
DELETE
The resulting queue item will block subsequent queue items, which use any of the devices in this queue item, from being queued.
commit-queue-lock
POST
PUT
PATCH
DELETE
Place a lock on the resulting queue item. The queue item will not be processed until it has been unlocked, see the actions unlock and lock in /devices/commit-queue/queue-item. No following queue items, using the same devices, will be allowed to execute as long as the lock is in place.
commit-queue-tag
POST
PUT
PATCH
DELETE
The value is a user-defined opaque tag. The tag is present in all notifications and events sent referencing the specific queue item.
commit-queue-timeout
POST
PUT
PATCH
DELETE
Specifies a maximum number of seconds to wait for completion. Possible values are infinity or a positive integer. If the timer expires, the transaction is kept in the commit-queue, and the operation returns successfully. If the timeout is not set, the operation waits until completion indefinitely.
commit-queue-error-option
POST
PUT
PATCH
DELETE
The error option to use. Depending on the selected error option, NSO will store the reverse of the original transaction to be able to undo the transaction changes and get back to the previous state. This data is stored in the /devices/commit-queue/completed tree from where it can be viewed and invoked with the rollback action. When invoked, the data will be removed. Possible values are: continue-on-error, rollback-on-error, and stop-on-error. The continue-on-error value means that the commit queue will continue on errors. No rollback data will be created. The rollback-on-error value means that the commit queue item will roll back on errors. The commit queue will place a lock with block-others on the devices and services in the failed queue item. The rollback action will then automatically be invoked when the queue item has finished its execution. The lock will be removed as part of the rollback. The stop-on-error means that the commit queue will place a lock with block-others on the devices and services in the failed queue item. The lock must then either manually be released when the error is fixed or the rollback action under /devices/commit-queue/completed be invoked. Read about error recovery in Commit Queue for a more detailed explanation.
trace-id
POST
PUT
PATCH
DELETE
Use the provided trace ID as part of the log messages emitted while processing. If no trace ID is given, NSO will generate and assign a trace ID to the processing. The trace-id query parameter can also be used with RPCs and actions to relay a trace-id from northbound requests. The trace-id will be included in the X-Cisco-NSO-Trace-ID header in the response.
NOTE: trace-id as a query parameter is deprecated from NSO version 6.3. Capabilities within Trace Context will provide support for trace-id, see Trace Context.
limit
GET
Used by the client to specify a limited set of list entries to retrieve. See The value of the limit parameter is either an integer greater than or equal to 1, or the string unbounded. The string unbounded is the default value. See Partial Responses for an example.
offset
GET
Used by the client to specify the number of list elements to skip before returning the requested set of list entries. See The value of the offset parameter is an integer greater than or equal to 0. The default value is 0. See Partial Responses for an example.
rollback-comment
POST
PUT
PATCH
DELETE
Used to specify a comment to be attached to the Rollback File that will be created as a result of the POST operation. This assumes that Rollback File handling is enabled.
rollback-label
POST
PUT
PATCH
DELETE
Used to specify a label to be attached to the Rollback File that will be created as a result of the POST operation. This assume that Rollback File handling is enabled.
rollback-id
POST
PUT
PATCH
DELETE
Return the rollback ID in the response if a rollback file was created during this operation. This requires rollbacks to be enabled in the NSO to take effect.
with-service-meta-data
GET
Include FASTMAP attributes such as backpointers and reference counters in the reply. These are typically internal to NSO and thus not shown by default.
origin
ietf-origin
inactive/active
tailf-netconf-inactive
default
tailf-netconf-defaults
All other
tailf_netconf
| This capability is always advertised. |
| Not supported by NSO. |
| Not supported by NSO. |
|
| NSO supports both version 1.0 and 1.1 of this capability. |
| Not supported by NSO. |
| The URL schemes supported are Note that user name and password must be given for |
|
|
| NSO implements the If the capability is enabled, NSO also implements the |
|
|
This capability allows the client to set the <error-option> parameter to rollback-on-error. The other permitted values are stop-on-error (default) and continue-on-error. Note that the meaning of the word "error" in this context is not defined in the specification. Instead, the meaning of this word must be defined by the data model. Also, note that if stop-on-error or continue-on-error is triggered by the server, it means that some parts of the edit operation succeeded, and some parts didn't. The error partial-operation must be returned in this case. partial-operation is obsolete and should not be returned by a server. If some other error occurs (i.e. an error not covered by the meaning of "error" above), the server generates an appropriate error message, and the data store is unaffected by the operation.
The NSO server never allows partial configuration changes, since it might result in inconsistent configurations, and recovery from such a state can be very difficult for a client. This means that regardless of the value of the <error-option> parameter, NSO will always behave as if it had the value rollback-on-error. So in NSO, the meaning of the word "error" in stop-on-error and continue-on-error, is something that never can happen.
It is possible to configure the NETCONF server to generate an operation-not-supported error if the client asks for the error-option continue-on-error. See in Manual Pages.
The NETCONF server supports XPath according to the W3C XPath 1.0 specification ().
NSO implements the urn:ietf:params:netconf:capability:notification:1.0 capability, including support for the optional replay feature. See for details.
NSO implements the urn:ietf:params:netconf:capability:yang-library:1.0 capability, which informs the client that the server implements the YANG module library , and informs the client about the current module-set-id.
NSO implements the urn:ietf:params:netconf:capability:yang-library:1.1 capability, which informs the client that the server implements the YANG library , and informs the client about the current content-id.