1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. SPDX-License-Identifier: CC-BY-4.0
3 .. Copyright (C) 2019 highstreet technologies GmbH and others
6 sim/o1-interface Overview
7 ==========================
9 Network Topology Simulator (NTS) | next generation
10 ==================================================
12 The Network Topology Simulator is a framework that allows simulating devices that expose a management interface through a NETCONF/YANG interface.
20 The NETCONF/YANG management interface is simulated, and any YANG models can be loaded by the framework to be exposed. Random data is generated based on the specific models, such that each simulated device presents different data on its management interface.
22 The NTS framework is based on several open-source projects:
24 * `cJSON <https://github.com/DaveGamble/cJSON>`_
26 * `libcurl <https://curl.haxx.se>`_
28 * `libyang <https://github.com/CESNET/libyang>`_
30 * `sysrepo <https://github.com/sysrepo/sysrepo>`_
32 * `libnetconf2 <https://github.com/CESNET/libnetconf2>`_
34 * `Netopeer2 <https://github.com/CESNET/Netopeer2>`_
36 The NTS Manager can be used to specify the simulation details and to manage the simulation environment at runtime.
38 Each simulated device is represented as a docker container, where the NETCONF Server is running. The creation and deletion of docker containers associated with simulated devices is handled by the NTS Manager. The NTS Manager is also running as a docker container and exposes a NETCONF/YANG interface to control the simulation.
43 The purpose of the NTS Manager is to ease the utilization of the NTS framework. It enables the user to interact with the simulation framework through a NETCONF/YANG interface. The user has the ability to modify the simulation parameters at runtime and to see the status of the current state of the NTS. The NETCONF/YANG interface will be detailed below.
50 +\-\-rw network\-functions
52 | +\-\-rw network\-function\* [function\-type]
54 | +\-\-rw function\-type identityref
56 | +\-\-rw started\-instances uint16
58 | +\-\-rw mounted\-instances uint16
60 | +\-\-rw mount\-point\-addressing\-method? enumeration
62 | +\-\-rw docker\-instance\-name string
64 | +\-\-rw docker\-version\-tag string
66 | +\-\-rw docker\-repository string
68 | +\-\-rw fault\-generation
70 | | +\-\-rw fault\-delay\-list\* [index]
72 | | | +\-\-rw index uint16
74 | | | +\-\-rw delay\-period? uint16
76 | | +\-\-ro fault\-count {faults\-status}?
78 | | +\-\-ro normal? uint32
80 | | +\-\-ro warning? uint32
82 | | +\-\-ro minor? uint32
84 | | +\-\-ro major? uint32
86 | | +\-\-ro critical? uint32
90 | | +\-\-rw faults\-enabled? boolean
92 | | +\-\-rw call\-home? boolean
96 | | +\-\-rw faults\-enabled? boolean
98 | | +\-\-rw pnf\-registration? boolean
100 | | +\-\-rw heartbeat\-period? uint16
104 | +\-\-ro instance\* [name]
106 | +\-\-ro mount\-point\-addressing\-method? enumeration
108 | +\-\-ro name string
112 | +\-\-ro docker\-ip? inet:ip\-address
114 | +\-\-ro docker\-port\* inet:port\-number
116 | +\-\-ro host\-ip? inet:ip\-address
118 | +\-\-ro host\-port\* inet:port\-number
120 +\-\-rw sdn\-controller
122 | +\-\-rw controller\-ip? inet:ip\-address
124 | +\-\-rw controller\-port? inet:port\-number
126 | +\-\-rw controller\-netconf\-call\-home\-port? inet:port\-number
128 | +\-\-rw controller\-username? string
130 | +\-\-rw controller\-password? string
132 +\-\-rw ves\-endpoint
134 | +\-\-rw ves\-endpoint\-protocol? enumeration
136 | +\-\-rw ves\-endpoint\-ip? inet:ip\-address
138 | +\-\-rw ves\-endpoint\-port? inet:port\-number
140 | +\-\-rw ves\-endpoint\-auth\-method? authentication\-method\-type
142 | +\-\-rw ves\-endpoint\-username? string
144 | +\-\-rw ves\-endpoint\-password? string
146 | +\-\-rw ves\-endpoint\-certificate? string
148 +\-\-ro base\-port? inet:port\-number
150 +\-\-ro ssh\-connections? uint8
152 +\-\-ro tls\-connections? uint8
154 +\-\-ro cpu\-usage? percent
156 +\-\-ro mem\-usage? uint32
159 ### Detailed information about the YANG attributes
160 ==================================================
162 Under **simulation** there are 3 configuration containers and a couple of statistics leafs:
164 * **network-functions** - represents the simulation data, which will be best described below
166 * **sdn-controller** - this container groups the configuration related to the ODL based SDN controller that the simulated devices can connect to
168 \* \*\*controller\-ip\*\* \- the IP address of the ODL based SDN controller where the simulated devices can be mounted. Both IPv4 and IPv6 are supported
170 \* \*\*controller\-port\*\* \- the port of the ODL based SDN controller
172 \* \*\*controller\-netconf\-call\-home\-port\*\* \- the NETCONF Call Home port of the ODL based SDN controller
174 \* \*\*controller\-username\*\* \- the username to be used when connecting to the ODL based SDN controller
176 \* \*\*controller\-password\*\* \- the password to be used when connecting to the ODL based SDN controller
178 * **ves-endpoint** - this container groups the configuration related to the VES endpoint where the VES messages are targeted
180 \* \*\*ves\-endpoint\-protocol\*\* \- the protocol of the VES endpoint where VES messages are targeted
182 \* \*\*ves\-endpoint\-ip\*\* \- the IP address of the VES endpoint where VES messages are targeted
184 \* \*\*ves\-endpoint\-port\*\* \- the port address of the VES endpoint where VES messages are targeted
186 \* \*\*ves\-endpoint\-auth\-method\*\* \- the authentication method to be used when sending the VES message to the VES endpoint. Possible values are:
188 + \*no\-auth\* \- no authentication
190 + \*cert\-only\* \- certificate only authentication in this case the certificate to be used for the communication must be configured
192 + \*basic\-auth\* \- classic username/password authentication in this case both the username and password need to be configured
194 + \*cert\-basic\-auth\* \- authentication that uses both username/password and a certificate all three values need to be configured in this case
196 \* \*\*ves\-endpoint\-username\*\* \- the username to be used when authenticating to the VES endpoint
198 \* \*\*ves\-endpoint\-password\*\* \- the password to be used when authenticating to the VES endpoint
200 \* \*\*ves\-endpoint\-certificate\*\* \- the certificate to be used when authenticating to the VES endpoint
202 * base-port - status node indicating the start port for mapping the simulated network functions; ports are assigned in an increasing order starting from this base port
204 * ssh-connections - status node indicating the number of SSH Endpoints each network function instance exposes
206 * tls-connections - status node indicating the number of TLS Endpoints each network function instance exposes
208 * cpu-usage - status node indicating the **total** CPU usage of the simulation
210 * mem-usage - status node indicating the **total** memory usage of the simulation
212 Under the **network-functions** there is the **network-function** list. This list is automatically populated by the NTS Manager at start time with the available network functions. No changes at the actual list are allowed (adding or removing elements), only the changes of the properties of the elements have effect. The structure of an element of this list is described below:
214 * **function-type** - the function type
216 * **started-devices** - represents the number of simulated devices. The default value is 0, meaning that when the NTS is started, there are no simulated devices. When this value is increased to **n**, the NTS Manager starts docker containers in order to reach **n** simulated devices. If the value is decreased to **k**, the NTS Manager will remove docker containers in a LIFO manner, until the number of simulated devices reaches **k**
218 * **mounted-devices** - represents the number of devices to be mounted to an ODL based SDN Controller. The same phylosophy as in the case of the previous leaf applies. If this number is increased, the number of ODL mountpoints increases. Else, the simulated devices are being unmounted from ODL. The number of mounted devices cannot exceed the number of started devices. The details about the ODL controller where to mount/unmount are given by the **sdn-controller** container
220 * **mount-point-addressing-method** - addressing method of the mount point. Possible values are:
222 + \*docker\-mapping\* \- [default value] future started simulated devices will be mapped on the Docker container
224 + \*host\-mapping\* \- future started simulated devices will me mapped on the host's IP address and port based on \*base\-port\*
226 * **docker-instance-name** - the prefix for future simulated devices (to this name a dash and an increasing number is added)
228 * **docker-version-tag** - a specific version tag for the Docker container to be ran. if empty, the latest version is ran
230 * **docker-repository** - the prefix for containing the Docker repository information. if local repository is used, value can be either blank or *local*
232 * **fault-generation** - container which groups the fault generation features, explained later
234 * **netconf** - container with settings for enabling or disabling netconf features
236 \* \*\*faults\-enabled\*\* \- enable or disable faults over netconf
238 \* \*\*call\-home\*\* \- enable the NETCONF Call Home feature. If set to 'true', each simulated device, when booting up, will try to Call Home to the SDN Controller.
240 * **ves** - container with settings for enabling or disabling VES features
242 \* \*\*faults\-enabled\*\* \- enable or disable faults over VES
244 \* \*\*pnf\-registration\*\* \- enable PNF registration on start
246 \* \*\*heartbeat\-period\*\* \- the number of seconds between VES heartbeat messages
248 ### Manager datastore changes mode of operation
249 ===============================================
251 Changing any value from **sdn-controller** or **ves-endpoint** containers will be propagated to all running simulated network functions, and all new ones will use the values here. In the same manner, triggering any changes to the **fault-generation**, **netconf** and **ves** settings in a network function element from the *network-function* list will automatically propagate to all running network functions of the same *function-type*. However, changing the *docker-\** leafs of the *network-function* won't propagate, as they're only used as settings for starting new network functions.
253 ## NTS network function
254 =======================
256 The NTS network function represents the actual simulated device.
259 module: nts-network-function
263 +\-\-rw network\-function
265 | +\-\-rw mount\-point\-addressing\-method? enumeration
267 | +\-\-rw fault\-generation
269 | | +\-\-rw fault\-delay\-list\* [index]
271 | | | +\-\-rw index uint16
273 | | | +\-\-rw delay\-period? uint16
275 | | +\-\-ro fault\-count {faults\-status}?
277 | | +\-\-ro normal? uint32
279 | | +\-\-ro warning? uint32
281 | | +\-\-ro minor? uint32
283 | | +\-\-ro major? uint32
285 | | +\-\-ro critical? uint32
289 | | +\-\-rw faults\-enabled? boolean
291 | | +\-\-rw call\-home? boolean
295 | +\-\-rw faults\-enabled? boolean
297 | +\-\-rw pnf\-registration? boolean
299 | +\-\-rw heartbeat\-period? uint16
301 +\-\-rw sdn\-controller
303 | +\-\-rw controller\-ip? inet:ip\-address
305 | +\-\-rw controller\-port? inet:port\-number
307 | +\-\-rw controller\-netconf\-call\-home\-port? inet:port\-number
309 | +\-\-rw controller\-username? string
311 | +\-\-rw controller\-password? string
313 +\-\-rw ves\-endpoint
315 +\-\-rw ves\-endpoint\-protocol? enumeration
317 +\-\-rw ves\-endpoint\-ip? inet:ip\-address
319 +\-\-rw ves\-endpoint\-port? inet:port\-number
321 +\-\-rw ves\-endpoint\-auth\-method? authentication\-method\-type
323 +\-\-rw ves\-endpoint\-username? string
325 +\-\-rw ves\-endpoint\-password? string
327 +\-\-rw ves\-endpoint\-certificate? string
331 +\-\-\-x datastore\-random\-populate
335 | +\-\-ro status enumeration
337 +\-\-\-x feature\-control
341 | | +\-\-\-w features ntsc:feature\-type
345 | +\-\-ro status enumeration
347 +\-\-\-x invoke\-notification
351 | | +\-\-\-w notification\-format enumeration
353 | | +\-\-\-w notification\-object string
357 | +\-\-ro status enumeration
359 +\-\-\-x invoke\-ves\-pm\-file\-ready
363 | | +\-\-\-w file\-location string
367 | +\-\-ro status enumeration
369 +\-\-\-x clear\-fault\-counters
373 +\-\-ro status enumeration
376 ### Detailed information about the YANG attributes
377 ==================================================
379 All de details and mechanisms of the **network-function** container are explained in the **NTS Manager** section. Besides this container, there are also a couple of RPCs defined:
381 * **datastore-random-populate** - calling this will trigger the network function to populate all its datastore with random data, and based on the *config.json* defined rules
383 * **feature-control** - calling this will enable selected features. currently available features are:
385 \* \*\*ves\-file\-ready\*\* \- enables VES file ready, and stats a FTP and a SFTP server on the network function
387 \* \*\*ves\-heartbeat\*\* \- enabled VES heartbeat feature
389 \* \*\*ves\-pnf\-registration\*\* \- enables VES PNF registration
391 \* \*\*manual\-notification\-generation\*\* \- enables the manual notification generation feature
393 \* \*\*netconf\-call\-home\*\* \- enables NETCONF's Call Home feature
395 \* \*\*web\-cut\-through\*\* \- enables web cut through, adding the info to the ietf\-system module
397 * **invoke-notification** - this RPC is used for forcing a simulated device to send a NETCONF notification, as defined by the user.
399 \- The \*\*input\*\* needed by the RPC:
401 \- \*\*notification\-format\*\* \- can be either \*json\* or \*xml\*
403 \- \*\*notification\-object\*\* \- this is a string containing the notification object that we are trying to send from the simulated device, in JSON format. \*\*Please note that the user has the responsibility to ensure that the JSON object is valid, according to the definition of the notification in the YANG module.\*\* There is no possibility to see what was wrong when trying to send an incorrect notification. The RPC will only respond with an "ERROR" status in that case, without further information. E.g. of a JSON containing a notification object of type \*\*\*otdr\-scan\-result\*\*\* defined in the \*\*\*org\-openroadm\-device\*\*\* YANG module: \*\*\*{"org\-openroadm\-device:otdr\-scan\-result":{"status":"Successful","status\-message":"Scan result was successful","result\-file":"/home/result\-file.txt"}}\*\*\*. \*\*Please note that the notification object contains also the name of the YANG model defning it, as a namespace, as seen in the example.\*\*
405 \- The \*\*output\*\* returned by the RPC:
407 \- \*\*status\*\* \- if the notification was send successfully by the simulated device, the RPC will return a \*\*SUCCESS\*\* value. Else, the RPC will return a \*\*ERROR\*\* value.
409 * **invoke-ves-pm-file-ready** - as name impiles, it invokes a file ready VES request, with a specified *file-location*
411 * **clear-fault-counters** - clears all counters for the fault generation system. see **Fault generation** below.
413 ### Network function operation
414 ==============================
416 Under usual operation, the network functions are managed by the manager which will perform the operations listed below. However, if a user chooses to, it can manually start up a network function, and manage it via NETCONF (datastore and RPCs).
418 1. Create and start Docker container
420 2. Set the VES and SDN controller data via NETCONF
422 3. Invoke **datastore-random-populate** RPC to populate the datastore
424 4. Invoke **feature-control**, enabling **ALL** the features.
426 ### Datastore random population
427 ===============================
429 The datastore will be populated with random values on each of its leafs. However, certain there is some control on the population itself, which can be found in *config.json*, which is commented. Please note that the nodes below should be main nodes in *config.json*:
432 "debug-max-string-size" : 50, //max size of string. if not set, default is 255
436 "excluded\-modules": [ //modules to be excluded from populating
440 "sysrepo\-monitoring",
442 "ietf\-yang\-library",
444 "ietf\-netconf\-acm",
446 "ietf\-netconf\-monitoring",
456 "ietf\-netconf\-server"
460 "default\-list\-instances": 1, //default number of instances a list or a leaflist should be populated with
462 "custom\-list\-instances" : [ //custom number of list instances. instance is schema name, and should reflect a list or a leaflist
464 {"/ietf\-interfaces:interfaces/interface": 2}, //2 instances of this. if 0, list will be excluded from populating
468 "restrict\-schema" : [ //restrictions to certain schema nodes to a set of values (so no random here)
470 {"/ietf\-interfaces:interfaces/interface/type" : ["iana\-if\-type:ethernetCsmacd", "other\-value"]},
472 {"/ietf\-interfaces:interfaces/interface/name" : ["name1", "name2"]}
482 Fault generation is controlled using a combination of JSON and YANG settings.
484 From the JSON perspective, the settings are as below:
489 "yang\-notif\-template" : "<xml ... %%severity%% $$time$$ %%custom1%%>",
491 "choosing\-method" : "random | linear",
497 //ves mandatory fields
505 "date\-time" : "$$time$$",
507 "specific\-problem" : "",
509 //template custom fileds
530 * **alarm-rules** node should be a main node in *config.json* for the respective network function in order for the fault generation to be enabled
532 \* \*\*yang\-notif\-template\*\* \- template of the yang notification model in current network function. can be "" to disable notifications. must always be present
534 \* \*\*choosing\-method\*\* \- method to choose the alarm. can be either \*linear\* or \*random\*, and must always be present
536 \* \*\*alarms\*\* list of alarms to choose from by "choosing\-method". it can contain any number of fields, custom ones, along with the mandatory VES fields presented below:
542 \* \*\*severity\*\* \- should correspond to VES defined: NORMAL, WARNING, MINOR, MAJOR, CRITICAL (case sensitive)
544 \* \*\*date\-time\*\*
546 \* \*\*specific\-problem\*\*
548 On the **yang-notif-template** and on any of the fields, there are two options for creating "dynamic" content (also see example above):
550 * **variables** - any field put in between %% will be replaced with the field's value
552 * **functions** - function names are put in between $$. Available functions are:
554 \* \*\*time\*\* \- returns current timestamp in a YANG date\-time format
556 \* \*\*uint8\_counter\*\* \- a unique 8\-bit counter, starting from 0, each time this function is found, the counter is automatically increased; when going above the max value, it will reset from 0
558 \* \*\*uint16\_counter\*\* \- a unique 16\-bit counter, starting from 0, each time this function is found, the counter is automatically increased; when going above the max value, it will reset from 0
560 \* \*\*uint32\_counter\*\* \- a unique 32\-bit counter, starting from 0, each time this function is found, the counter is automatically increased; when going above the max value, it will reset from 0
562 It is worth to mention that the replacement is done within any field, of any field. This means that it is possible to have nested fields and functions. See example for better understanding.
564 From the YANG perspective, one can control whether faults are enabled or disabled independently via NETCONF and/or VES, through their respective containers described in the sections above. The YANG **fault-generation** container contains:
566 * **fault-delay-list** - a list with elements which consists of *index* (unimportant, but needs to be unique) and *delay-period* which represents the number of seconds in between the current fault and the next fault. Please note that the fault is chosen from and based on the settings esablished in *config.json*
568 * **fault-count** - the status of the faults encountered by the network function; it is not present in the manager's schema
570 In order to clear the **fault-count** counters, on the **network-function** module there is a **clear-fault-counters** RPC which can be called via NETCONF.
575 Either of the two main functionalities (*manager* and *network-function*) are implemented by the same binary application. Besides this functionality, the application can also do some utility functions, which can be used if the application is ran from the CLI (command line interface), along with some parameters.
580 The paramers are described below:
581 - --help - shows the help (also described here)
582 - --docker-init - is automatically used by Docker when building the images to install modules and enable features. Described in the next chapter. **Do not run manually**
583 - the two main modes:
585 \- \-\-manager \- runs in manager mode
587 \- \-\-network\-function \- runs in network function mode
589 - global settings, which can be used with **ANY** of the other operating modes:
591 \- \-\-operational\-only \- used in testing. do not use the RUNNING datastore, only do the population on OPERATIONAL datastore
593 \- \-\-fixed\-rand \- used in testing. specify a fixed value seed for the randomness
595 \- \-\-verbose \- set the verbose level. can range from 0 to 2, default is 1
597 \- \-\-workspace \- set the current working workspace. the workspace must contain the \*config\* and \*log\* folders
599 - test modes - do not use
601 - utilitary functions:
603 \- \-\-ls \- list all modules in the datastore with their attributes
605 \- \-\-schema \- list the schema of an xpath given as parameter
607 \- \-\-populate \- populate the datastore upon starting
609 \- \-\-enable\-features \- enable all features upon starting, after (if requested) the populating was done
611 \- \-\-nc\-server\-init \- initialize netconf server
613 \- \-\-loop \- after everything is done, run an endless loop
615 ### Docker container initialization
616 ===================================
618 The NTS app is responsible for initializing the Docker container upon build. What it actually does is described below:
620 1. Install modules located in the *deploy/yang/* folder recusively
622 \- note that if a module requires startup data (mandatory data), this can be acheived by having an \*\*XML\*\* file with this data along the YANG file. For example, if, let's say \*ietf\-interfaces.yang\* would require startup date, there must be a \*ietf\-interfaces.xml\* located in the same folder.
624 2. Enable all YANG features of the modules, unless specifically excluded
626 If the initialization failes, the result is returned to the Docker builder, so the build will fail, and user can see the output. Docker initialization can be customized from the *config.json* file, as described below. The example is self-expainatory, and the *docker-rules* node needs to be a main node of *config.json*:
631 "excluded\-modules": [ //excluded modules from installing
639 "excluded\-features": [ //excluded features from installing
653 The NTS Manager can be used to start any type of simulated network function.
655 ## Building the images
656 ======================
658 The `nts_build.sh` script should be used for building the docker images needed by the NTS to the local machine. This will create docker images for the Manager and for each type of simulated network function.
660 The user can also directly use the already built docker images, that are pushed to the highstreet docker repository. This can be done by using the `nts*pull*highstreet_repo.sh` script, which will pull all the images locally.
662 ## Starting the NTS Manager
663 ===========================
665 The **nts-manager-ng** can be started using the docker-compose file in this repo. The file assumes that the docker images were pulled from the highstreet docker repository.
671 Before starting, the user should set the environment variables defined in the docker-compose file according to his needs:
673 * **NETCONF*NTS*HOST_IP**: an IP address from the host, which should be used by systems outside the local machine to address the simulators;
675 * **NETCONF*NTS*HOST*BASE*PORT**: the port from where the allocation for the simulated network functions should start;
677 * **IPv6Enabled**: should be set to `true` if IPv6 is enabled in the docker daemon and the user wants to use IPv6 to address the simulated network functions.
683 - [fixed] fixed issues where ODL could not parse the correct versions for yang files
687 - [fixed] bug that occured when trying to start a wrong instance (bad docker-repository or docker-tag)
688 - [fixed] when populating the fault-delay-list, if the sum of all the faults was 0, the network funciton kept on generating faults and crashed
692 - [feature-add] added web-cut-through feature
693 - [fixed] mount-point-addressing-method was mistakenly changing after starting