ntsimulator/README.md

   1 # Network Topology Simulator (NTS)
   2
   3 The Network Topology Simulator is a framework that allows simulating devices that expose a management interface through a NETCONF/YANG interface.
   4
   5 ## Description
   6
   7 ### Overview
   8
   9 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.
  10
  11 The NTS Manager can be used to specify the simulation details and to manage the simulation environment at runtime.
  12
  13 The NTS framework is based on several open-source projects:
  14 * [Netopeer2](https://github.com/CESNET/Netopeer2)
  15 * [libnetconf2](https://github.com/CESNET/libnetconf2)
  16 * [libyang](https://github.com/CESNET/libyang)
  17 * [sysrepo](https://github.com/sysrepo/sysrepo) - all of these are used for the implementation of the NETCONF Server, both in the NTS Manager and in each simulated device
  18 * [cJSON](https://github.com/DaveGamble/cJSON) - used to create the JSON payloads for talking with the simulation framework
  19 * [pyang](https://github.com/mbj4668/pyang) - used to create random data from the YANG models that are exposed
  20
  21 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.
  22
  23 ### NTS Manager
  24
  25 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.
  26
  27 ```
  28 module: network-topology-simulator
  29   +--rw simulator-config
  30   |  +--rw simulated-devices?      uint32
  31   |  +--rw mounted-devices?        uint32
  32   |  +--rw ssh-connections?        uint32
  33   |  +--rw tls-connections?        uint32
  34   |  +--rw notification-config
  35   |  |  +--rw fault-notification-delay-period*   uint32
  36   |  |  +--rw ves-heartbeat-period?              uint32
  37   |  |  +--rw is-netconf-available?              boolean
  38   |  |  +--rw is-ves-available?                  boolean
  39   |  +--rw controller-details
  40   |  |  +--rw controller-ip?         inet:ip-address
  41   |  |  +--rw controller-port?       inet:port-number
  42   |  |  +--rw controller-username?   string
  43   |  |  +--rw controller-password?   string
  44   |  +--rw ves-endpoint-details
  45   |     +--rw ves-endpoint-ip?            inet:ip-address
  46   |     +--rw ves-endpoint-port?          inet:port-number
  47   |     +--rw ves-endpoint-auth-method?   authentication-method-type
  48   |     +--rw ves-endpoint-username?      string
  49   |     +--rw ves-endpoint-password?      string
  50   |     +--rw ves-endpoint-certificate?   string
  51   |     +--rw ves-registration?           boolean
  52   +--ro simulator-status
  53      +--ro simulation-usage-details
  54      |  +--ro running-simulated-devices?   uint32
  55      |  +--ro running-mounted-devices?     uint32
  56      |  +--ro base-netconf-port?           uint32
  57      |  +--ro cpu-usage?                   percent
  58      |  +--ro mem-usage?                   uint32
  59      +--ro notification-count
  60      |  +--ro total-ves-notifications
  61      |  |  +--ro normal?     uint32
  62      |  |  +--ro warning?    uint32
  63      |  |  +--ro minor?      uint32
  64      |  |  +--ro major?      uint32
  65      |  |  +--ro critical?   uint32
  66      |  +--ro total-netconf-notifications
  67      |     +--ro normal?     uint32
  68      |     +--ro warning?    uint32
  69      |     +--ro minor?      uint32
  70      |     +--ro major?      uint32
  71      |     +--ro critical?   uint32
  72      +--ro simulated-devices-list* [uuid]
  73         +--ro uuid                  string
  74         +--ro device-ip?            string
  75         +--ro device-port*          uint32
  76         +--ro is-mounted?           boolean
  77         +--ro operational-state?    operational-state-type
  78         +--ro notification-count
  79            +--ro ves-notifications
  80            |  +--ro normal?     uint32
  81            |  +--ro warning?    uint32
  82            |  +--ro minor?      uint32
  83            |  +--ro major?      uint32
  84            |  +--ro critical?   uint32
  85            +--ro netconf-notifications
  86               +--ro normal?     uint32
  87               +--ro warning?    uint32
  88               +--ro minor?      uint32
  89               +--ro major?      uint32
  90               +--ro critical?   uint32
  91
  92   rpcs:
  93     +---x restart-simulation
  94     +---x add-key-pair-to-odl
  95 ```
  96
  97 #### Detailed information about the YANG attributes
  98
  99 ##### Configuration
 100
 101 * **simulated-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, until the number of simulated devices reaches **k**;
 102 * **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 simulated devices. The details about the ODL controller where to mount/unmount are given by the **controller-details** container; **Please note that this cannot be set to a value > 0 if the *ves-registration* leaf is set to 'True'**; For each simulated device, a number of NETCONF endpoints will be mounted, according to the **ssh-connections** and **tls-connections** leafs. See **NETCONF Endpoints** section for more details;
 103 * **ssh-connections** - represents the number of SSH endpoints to be exposed by each of the simulated devices. **Please note that the total number of SSH and TLS connections cannot exceed 100.** The default value is 1. **The value can only be changed when simulated-devices is 0**.
 104 * **tls-connectioons** - represents the number of TLS endpoints to be exposed by each of the simulated devices. **Please note that the total number of SSH and TLS connections cannot exceed 100.** The default value is 0. **The value can only be changed when simulated-devices is 0**.
 105 *  **notification-config** - this container groups the configuration about fault notification generation of each simulated device;
 106 * **fault-notification-delay-period** - the amount of seconds between two generated fault notifications. For example, if this has a value of *10*, each simulated device will generate a **random** fault notification every *10* seconds; **when this is set to 0, it will reset the notification counters for the VES and NETCONF notifications, which are exposed in the simulator-status**;
 107 * **ves-heartbeat-period** - the amount of seconds between VES heartbeat messages that can be generated by each simulated device. The details about the VES connection endpoint are given in the **ves-endpoint-details** container;
 108 * **is-netconf-available** - if set to 'True', NETCONF notifications will be sent when a random fault notification is generated, The NETCONF notification that is being sent is currently *o-ran-fm:alarm-notif*; if set to 'False', NETCONF notifications are not being sent out;
 109 * **is-ves-available** - if set to 'True', VES *faultNotification* messages will be sent when a random fault notification is generated; if set to 'False', VES *faultNotification* messages are not generated;
 110 * **controller-details** - this container groups the configuration related to the ODL based SDN controller that the simulated devices can connect to;
 111 * **controller-ip** - the IP address of the ODL based SDN controller where the simulated devices can be mounted. Only IPv4 is supported currently;
 112 * **controller-port** - the port of the ODL based SDN controller;
 113 * **controller-username** - the username to be used when connecting to the ODL based SDN controller;
 114 * **controller-password** - the password to be used when connecting to the ODL based SDN controller;
 115 * **ves-endpoint-details** - this container groups the configuration related to the VES endpoint where the VES messages are targeted;
 116 * **ves-endpoint-ip** - the IP address of the VES endpoint where VES messages are targeted;
 117 * **ves-endpoint-port** - the port address of the VES endpoint where VES messages are targeted;
 118 * **ves-endpoint-auth-method** - the authentication method to be used when sending the VES message to the VES endpoint. Possible values are:
 119   + *no-auth* - no authentication;
 120   + *cert-only* - certificate only authentication; in this case the certificate to be used for the communication must be configured;
 121   + *basic-auth* - classic username/password authentication; in this case both the username and password need to be configured;
 122   + *cert-basic-auth* - authentication that uses both username/password and a certificate; all three values need to be configured in this case;
 123 * **ves-endpoint-username** - the username to be used when authenticating to the VES endpoint;
 124 * **ves-endpoint-password** - the password to be used when authenticating to the VES endpoint;
 125 * **ves-endpoint-certificate** - the certificate to be used when authenticating to the VES endpoint;
 126 * **ves-registration** - if this is set to 'True' **when simulated devices are starting**, each simulated device will send out *pnfRegistration* VES messages to the configured VES endpoint; if this is set to 'False', *pnfRegistration* VES messages will not be sent out. **Please note that this cannot be set to 'True' is simulated devices are already mounted to ODL based SDN controller (mounted-devices leaf > 0)**; For each simulated device, **ssh-connections + tls-connections** pnfRegistration VES messages will be sent out. See **NETCONF Endpoints** section for more details.
 127
 128 ##### Status
 129
 130 * **simulation-usage-details** - this container groups the information about the current simulator status;
 131 * **running-simulated-devices** - the current number of running simulated devices;
 132 * **running-mounted-devices** - the current number of running simulated devices that have been mounted to the ODL based SDN controller; For each simulated device, 10 NETCONF endpoints will be mounted (7 SSH + 3 TLS). See **NETCONF Endpoints** section for more details.
 133 * **base-netconf-port** - the port that was used as a base when craeting simulated devices;
 134 * **cpu-usage** - the percentage of the CPU used currently by the simulation framework;
 135 * **mem-usage** - the amount of RAM used (in MB) currently by the simulation framework;
 136 * **notification-count** - this container groups the details about the total number of notifications that were generated by the simulated devices;
 137 * **total-ves-notifications** - this container groups the details about the total number of VES notifications that were generated by the simulated devices, grouped by severity;
 138 * **total-netcnof-notifications** - this container groups the details about the total number of NETCONF notifications that were generated by the simulated devices - grouped by severity;
 139 * **simulated-devices-list** - this list contains the details about each simulated devices that is currently running;
 140 * **uuid** - the Universally Unique ID of the simulated device;
 141 * **device-ip** - the IP address of the simulated device;
 142 * **device-port** - the port of the simulated device, where the NETCONF connection is exposed;
 143 * **is-mounted** - boolean to show whether the device is currently mounted to an ODL based SDN controller;
 144 * **operational-state** - the operational state of the current simulated device; it can be either *not-specified*, *created*, *running* or *exited*;
 145 * **notification-count** - this container groups the details about the number of notifications that were generated by this particular simulated device;
 146 * **ves-notifications** - this container groups the details about the number of VES notifications that were generated by this simulated device, grouped by severity;
 147 * **netconf-notifications** - this container groups the details about the number of NETCONF notifications that were generated by this simulated device - grouped by severity.
 148
 149 ##### RPCs
 150
 151 * **add-key-pair-to-odl** - this RPC can be used to trigger the loading of a *keystore* entry in an ODL based SDN controller such that the controller can connect to the simulated devices via **TLS**. A private key, an associated certificate and a trusted certificate are loaded in the *keystore* entry in ODL. The certificate associated with the private key to be used by ODL in the TLS communication is signed by the same CA as the certificates used by the simulated devices, easing the TLS configuration in both the NETCONF Server and the ODL.
 152 * **restart-simulation** - this RPC is not yet implemented.
 153
 154 ### Simulated Device
 155
 156 Each simulated device is represented as a docker container, inside which the NETCONF Server runs. The simulated device exposes the YANG models which are found inside the **yang** folder. A custom version of the *pyang* utility is used to generate random data for each of the YANG modules found inside the **yang** folder.
 157
 158 #### NETCONF Endpoints
 159
 160 Each simulated device exposes a number of NETCONF endpoints which represented by the sum of the **ssh-connections** and **tls-connections** leafs, on consecutive ports. The first simulated device uses the ports starting from the **NETCONF_BASE** environment variable used when starting the NTS Manager, while the next one uses the next ports and so on and so forth. E.g. if the **NETCONF_BASE=50000** and **ssh-connections=5** and **tls-connections=3**, the first simulated device will expose ports from *50000* to *50007*, the second simulated device will expose ports from *5008* to *50015* etc.
 161
 162 The first **ssh-connections** ports exposed by a simulated device are **SSH** based. A NETCONF client can connect to the exposed endpoint using one of the SSH ports (e.g. 50000 to 50007, considering the previous example) and the **username/password**: *netconf/netconf*.
 163
 164 The last **tls-connections** ports exposed by a simulated device are **TLS** based. A NETCONF client can connect to the exposed endpoint using one of the TLS ports (e.g. 50006 to 50008, considering the previous example), using a valid certificate and the **username**: *netconf*.
 165
 166 ## Usage
 167
 168 ### Building the images
 169
 170 The `docker-build-nts-manager.sh` script can be used to built the docker image associated with the NTS Manager. This will create a docker image named *ntsim_manager_light*, which will be used to start the simulation framework. Inside the docker image, port 830 will wait for connections for the NETCONF/YANG management interface.
 171
 172 The `docker-build-onf-core-model-1-2.sh` script can be used to build the docker image associated with a simulated device, exposing the ONF CoreModel version 1.2.
 173
 174 The `docker-build-onf-core-model-1-4.sh` script can be used to build the docker image associated with a simulated device, exposing the ONF CoreModel version 1.4.
 175
 176 The `docker-build-openroadm.sh` script can be used to build the docker image associated with a simulated device, exposing the OpenROADM models.
 177
 178 The `docker-build-o-ran-device.sh` script can be used to build the docker image associated with a simulated device, exposing the O-RAN models.
 179
 180 The `docker-build-o-ran-sc-o-ran-ru.sh` script can be used to build the docker image associated with a simulated device, exposing the O-RAN-SC models.
 181
 182 The `docker-build-x-ran-device.sh*` script can be used to build the docker image associated with a simulated device, exposing the X-RAN models.
 183
 184 ### Starting the NTS Manager
 185
 186 The NTS Manager can be started using the `docker-compose.yml` file that is provided inside tthe **scripts** folder. Further, the parameters present in this file are explained.
 187
 188 ```yaml
 189 version: '3'
 190 services:
 191   ntsimulator:
 192     image: "ntsim_manager:latest"
 193     container_name: NTS_Manager
 194     ports:
 195      - "8300:830"
 196     volumes:
 197      - "/var/run/docker.sock:/var/run/docker.sock"
 198      - "/var/tmp/NTS_Manager:/opt/dev/scripts"
 199      - "/usr/bin/docker:/usr/bin/docker"
 200     labels:
 201       "NTS-manager": ""
 202     environment:
 203       NTS_IP: "172.17.0.1"
 204       NETCONF_BASE: 50000
 205       DOCKER_ENGINE_VERSION: "1.40"
 206       MODELS_IMAGE: "ntsim_oran"
 207       VesHeartbeatPeriod: 0
 208       IsVesAvailable: "true"
 209       IsNetconfAvailable: "true"
 210       VesRegistration: "false"
 211       VesEndpointPort: 8080
 212       VesEndpointIp: "172.17.0.1"
 213       SshConnections: 1
 214       TlsConnections: 0
 215       K8S_DEPLOYMENT: "false"
 216 ```
 217
 218
 219 * Port mapping:
 220     * `"8300:830"` - this maps the *830* port from inside the docker container of the NTS Manager to the port *8300* from the host, and binds it to any IP address on the host:
 221
 222 * Volumes - these map 3 important things:
 223     * the docker socket from the host is mapped inside the docker container:
 224         `/var/run/docker.sock:/var/run/docker.sock` - **please do not modify the path inside the container!**;
 225     * any folder from the host can be mapped to inside the docker container into othe **/opt/dev/scripts** folder:
 226         `/var/tmp/NTS_Manager:/opt/dev/scripts` - **please do not modify the path inside the container!**;
 227     * the path to the docker executable needs to be mapped inside the container:
 228         `/usr/bin/docker:/usr/bin/docker` - **please do not modify the path inside the container!**;
 229
 230 * Labels - this associates the *NTS-manager* label to the docker container where the NTS runs;
 231 * Environment variables:
 232     * **NTS_IP** - this should point to an IP address **from the host**, through which the simulated devices will be accessed;
 233     * **NETCONF_BASE** - this is the starting port used to expose NETCONF endpoints. Starting from this, each device will use 10 consecutive ports for its endpoints;
 234     * **DOCKER_ENGINE_VERSION** - this is the version of the *docker engine* installed currently on the host. This can be verified using `docker version` command in the host, and looking to the `API version:      #.##` variable from the Server details.
 235     * **MODELS_IMAGE** - this represents the name of the docker image that represents the simulated device. The NTS Manager will start containers using this image, when starting simulated devices.
 236     * **VesHeartbeatPeriod** - this can change the default value of the **ves-heartbeat-period** leaf used by the NTS Manager.
 237     * **IsVesAvailable** - this can change the default value of the **is-ves-available** leaf used by the NTS Manager.
 238     * **IsNetconfAvailable** - this can change the default value of the **is-netconf-available** leaf used by the NTS Manager.
 239     * **VesRegistration** - this can change the default value of the **ves-registration** leaf used by the NTS Manager.
 240     * **VesEndpointPort** - this can change the default value of the **ves-endpoint-port** leaf used by the NTS Manager.
 241     * **VesEndpointIp** - this can change the default value of the **ves-endpoint-ip** leaf used by the NTS Manager.
 242     * **SshConnections** - this can change the default value of the **ssh-connections** leaf used by the NTS Manager.
 243     * **TlsConnections** - this can change the default value of the **tls-connections** leaf used by the NTS Manager.
 244     * **K8S_DEPLOYMENT** - this value can be set to `true` when the user wants to the NTS Framework in a Kubernetes deployment. The default is `false`.
 245
 246 After modifying the `docker-compose.yml` file with values specific to your host, the NTS Manager can be started by running the command `docker-compose up` from the **scripts** folder.
 247
 248 After the NTS Manager is started, it will wait for connections on its NETCONF/YANG management interface. One can connect to this using a NETCONF Client. The **username/password** for connecting are: *netconf/netconf*.
 249
 250 Example of `docker ps` command result, after the NTS Manager was started:
 251
 252 ```
 253 7ff723b7f794        ntsim_manager:latest   "sh -c '/usr/bin/sup…"   5 days ago          Up 5 days           0.0.0.0:8300->830/tcp       NTS_Manager
 254 ```
 255
 256 ### Using the NTS Manager
 257
 258 When the NTS Manager is started, its default configuration looks like this:
 259
 260 ```xml
 261 <simulator-config xmlns="urn:onf:params:xml:ns:yang:network-topology-simulator">
 262         <simulated-devices>0</simulated-devices>
 263         <mounted-devices>0</mounted-devices>
 264     <ssh-connections>1</ssh-connections>
 265     <tls-connections>0</tls-connections>
 266         <notification-config>
 267                 <fault-notification-delay-period>0</fault-notification-delay-period>
 268                 <ves-heartbeat-period>0</ves-heartbeat-period>
 269                 <is-netconf-available>true</is-netconf-available>
 270                 <is-ves-available>true</is-ves-available>
 271         </notification-config>
 272         <controller-details>
 273                 <controller-ip>172.17.0.1</controller-ip>
 274                 <controller-port>8181</controller-port>
 275                 <controller-username>admin</controller-username>
 276                 <controller-password>admin</controller-password>
 277         </controller-details>
 278         <ves-endpoint-details>
 279                 <ves-endpoint-ip>172.17.0.1</ves-endpoint-ip>
 280                 <ves-endpoint-port>30007</ves-endpoint-port>
 281                 <ves-endpoint-auth-method>no-auth</ves-endpoint-auth-method>
 282                 <ves-registration>false</ves-registration>
 283         </ves-endpoint-details>
 284 </simulator-config>
 285 ```
 286
 287 This configuration can be altered by connecting to the NTS Manager with a NETCONF Client.
 288
 289 ### Starting a simulated device
 290
 291 Example RPC for starting **one** simulated device:
 292
 293 ```xml
 294 <?xml version="1.0" encoding="utf-8"?>
 295 <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="">
 296   <edit-config>
 297     <target>
 298       <running/>
 299     </target>
 300     <config>
 301       <simulator-config xmlns="urn:onf:params:xml:ns:yang:network-topology-simulator">
 302         <simulated-devices>1</simulated-devices>
 303         <!--We need to delete the ssh-connections and tls-connections leafs when configuring simulated-devices > 0 -->
 304         <ssh-connections xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0" xc:operation="delete"/>
 305         <tls-connections xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0" xc:operation="delete"/>
 306       </simulator-config>
 307     </config>
 308   </edit-config>
 309 </rpc>
 310 ```
 311
 312
 313 If the leaf `<simulated-devices>1</simulated-devices>` will be set to a value of **1**, the NTS Manager will start a new docker container. We can verify that this was successfull by running the `docker ps` command. The results will look like this:
 314
 315 ```
 316 c18eb7a362f5        ntsim_oran             "sh -c '/usr/bin/sup…"   4 days ago          Up 4 days           172.17.0.1:50000->830/tcp, 172.17.0.1:50001->831/tcp, 172.17.0.1:50002->832/tcp, 172.17.0.1:50003->833/tcp, 172.17.0.1:50004->834/tcp, 172.17.0.1:50005->835/tcp, 172.17.0.1:50006->836/tcp, 172.17.0.1:50007->837/tcp, 172.17.0.1:50008->838/tcp, 172.17.0.1:50009->839/tcp   reverent_bhabha
 317 ```
 318
 319
 320 ## Troubleshooting
 321
 322 ### No simulated devices are starting
 323
 324 If, after setting the leaf `<simulated-devices>1</simulated-devices>` to a value greater that 0, no new containers are created, please make sure that the image name specified in the **MODELS_IMAGE** environment variable when starting the NTS Manager is present in the host. You can verify that using the `docker images` command.
 325
 326 Example of a result of such a command:
 327
 328 ```
 329 ntsim_oran_light       latest           57b065de4458     4 days ago     186MB
 330 ```
 331
 332 This means that `MODELS_IMAGE: "ntsim_oran_light:latest"` can be used as an environment variable when starting the NTS Manager.