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 notification-config
  33   |  |  +--rw fault-notification-delay-period?   uint32
  34   |  |  +--rw ves-heartbeat-period?              uint32
  35   |  |  +--rw is-netconf-available?              boolean
  36   |  |  +--rw is-ves-available?                  boolean
  37   |  +--rw controller-details
  38   |  |  +--rw controller-ip?         inet:ip-address
  39   |  |  +--rw controller-port?       inet:port-number
  40   |  |  +--rw controller-username?   string
  41   |  |  +--rw controller-password?   string
  42   |  +--rw ves-endpoint-details
  43   |     +--rw ves-endpoint-ip?            inet:ip-address
  44   |     +--rw ves-endpoint-port?          inet:port-number
  45   |     +--rw ves-endpoint-auth-method?   authentication-method-type
  46   |     +--rw ves-endpoint-username?      string
  47   |     +--rw ves-endpoint-password?      string
  48   |     +--rw ves-endpoint-certificate?   string
  49   |     +--rw ves-registration?           boolean
  50   +--ro simulator-status
  51      +--ro simulation-usage-details
  52      |  +--ro running-simulated-devices?   uint32
  53      |  +--ro running-mounted-devices?     uint32
  54      |  +--ro base-netconf-port?           uint32
  55      |  +--ro cpu-usage?                   percent
  56      |  +--ro mem-usage?                   uint32
  57      +--ro simulated-devices-list* [uuid]
  58         +--ro uuid                 string
  59         +--ro device-ip?           string
  60         +--ro device-port*         uint32
  61         +--ro is-mounted?          boolean
  62         +--ro operational-state?   operational-state-type
  63
  64   rpcs:
  65     +---x restart-simulation
  66     +---x add-key-pair-to-odl
  67 ```
  68
  69 #### Detailed information about the YANG attributes
  70
  71 ##### Configuration
  72
  73 * **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**;
  74 * **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, 10 NETCONF endpoints will be mounted (7 SSH + 3 TLS). See **NETCONF Endpoints** section for more details.
  75 *  **notification-config** - this container groups the configuration about fault notification generation of each simulated device;
  76 * **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;
  77 * **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;
  78 * **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;
  79 * **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;
  80 * **controller-details** - this container groups the configuration related to the ODL based SDN controller that the simulated devices can connect to;
  81 * **controller-ip** - the IP address of the ODL based SDN controller where the simulated devices can be mounted. Only IPv4 is supported currently;
  82 * **controller-port** - the port of the ODL based SDN controller;
  83 * **controller-username** - the username to be used when connecting to the ODL based SDN controller;
  84 * **controller-password** - the password to be used when connecting to the ODL based SDN controller;
  85 * **ves-endpoint-details** - this container groups the configuration related to the VES endpoint where the VES messages are targeted;
  86 * **ves-endpoint-ip** - the IP address of the VES endpoint where VES messages are targeted;
  87 * **ves-endpoint-port** - the port address of the VES endpoint where VES messages are targeted;
  88 * **ves-endpoint-auth-method** - the authentication method to be used when sending the VES message to the VES endpoint. Possible values are:
  89   + *no-auth* - no authentication;
  90   + *cert-only* - certificate only authentication; in this case the certificate to be used for the communication must be configured;
  91   + *basic-auth* - classic username/password authentication; in this case both the username and password need to be configured;
  92   + *cert-basic-auth* - authentication that uses both username/password and a certificate; all three values need to be configured in this case;
  93 * **ves-endpoint-username** - the username to be used when authenticating to the VES endpoint;
  94 * **ves-endpoint-password** - the password to be used when authenticating to the VES endpoint;
  95 * **ves-endpoint-certificate** - the certificate to be used when authenticating to the VES endpoint;
  96 * **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, 10 pnfRegistration VES messages will be sent out (7 SSH + 3 TLS). See **NETCONF Endpoints** section for more details.
  97
  98 ##### Status
  99
 100 * **simulation-usage-details** - this container groups the information about the current simulator status;
 101 * **running-simulated-devices** - the current number of running simulated devices;
 102 * **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.
 103 * **base-netconf-port** - the port that was used as a base when craeting simulated devices;
 104 * **cpu-usage** - the percentage of the CPU used currently by the simulation framework;
 105 * **mem-usage** - the amount of RAM used (in MB) currently by the simulation framework;
 106 * **simulated-devices-list** - this list contains the details about each simulated devices that is currently running;
 107 * **uuid** - the Universally Unique ID of the simulated device;
 108 * **device-ip** - the IP address of the simulated device;
 109 * **device-port** - the port of the simulated device, where the NETCONF connection is exposed;
 110 * **is-mounted** - boolean to show whether the device is currently mounted to an ODL based SDN controller;
 111 * **operational-state** - the operational state of the current simulated device; it can be either *not-specified*, *created*, *running* or *exited*.
 112
 113 ##### RPCs
 114
 115 * **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.
 116 * **restart-simulation** - this RPC is not yet implemented.
 117
 118 ### Simulated Device
 119
 120 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.
 121
 122 #### NETCONF Endpoints
 123
 124 Each simulated device exposes **10 NETCONF endpoints**, on 10 consecutive ports. The first simulated device uses the 10 ports starting from the **NETCONF_BASE** environment variable used when starting the NTST Manager, while the nextt one uses the next 10 ports and so on and so forth. E.g. if the **NETCONF_BASE=50000** the first simulated device will expose ports from *50000* to *50009*, the second simulated device will expose ports from *50010* to *50019* etc.
 125
 126 The first 7 connections 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 50006) and the **username/password**: *netconf/netconf*.
 127
 128 The last 3 connections 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. 50007 to 50009), using a valid certificate and the **username**: *netconf*.
 129
 130 ## Usage
 131
 132 ### Building the images
 133
 134 The `docker-build-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*, 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.
 135
 136 The `docker-build-model.sh` script can be used to build the docker image associated with a simulated device. Currently, this will create a docker image named *ntsim_oran*, which will be used by the manager to start the docker containers for each simulated device.
 137
 138 ### Starting the NTS Manager
 139
 140 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.
 141
 142 ```yaml
 143 version: '3'
 144 services:
 145   ntsimulator:
 146     image: "ntsim_manager:latest"
 147     container_name: NTS_Manager
 148     ports:
 149      - "172.17.0.1:8300:830"
 150     volumes:
 151      - "/var/run/docker.sock:/var/run/docker.sock"
 152      - "/path/to/simulator/folder/ntsimulator/scripts:/opt/dev/scripts"
 153      - "/usr/bin/docker:/usr/bin/docker"
 154     labels:
 155       "NTS-manager": ""
 156     environment:
 157       NTS_IP: "172.17.0.1"
 158       NETCONF_BASE: 50000
 159       DOCKER_ENGINE_VERSION: "1.40"
 160       MODELS_IMAGE: "ntsim_oran"
 161 ```
 162
 163
 164 * Port mapping:
 165     * `"172.17.0.1: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 the docker IP address *172.17.0.1*:
 166
 167 * Volumes - these map 3 important things:
 168     * the docker socket from the host is mapped inside the docker container:
 169         `/var/run/docker.sock:/var/run/docker.sock` - **please do not modify the path inside the container!**;
 170     * the **scripts** folder from the cloned repository needs to be mapped inside the container:
 171         `/path/to/simulator/folder/ntsimulator/scripts:/opt/dev/scripts` - **please do not modify the path inside the container!**;
 172     * the path to the docker executable needs to be mapped inside the container:
 173         `/usr/bin/docker:/usr/bin/docker` - **please do not modify the path inside the container!**;
 174
 175 * Labels - this associates the *NTS-manager* label to the docker container where the NTS runs;
 176 * Environment variables:
 177     * **NTS_IP** - this should point to an IP address **from the host**, through which the simulated devices will be accessed;
 178     * **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;
 179     * **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.
 180     * **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.
 181
 182 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.
 183
 184 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*.
 185
 186 Example of `docker ps` command result, after the NTS Manager was started:
 187
 188 ```
 189 7ff723b7f794        ntsim_manager:latest   "sh -c '/usr/bin/sup…"   5 days ago          Up 5 days           172.17.0.1:8300->830/tcp       NTS_Manager
 190 ```
 191
 192 ### Using the NTST Manager
 193
 194 When the NTS Manager is started, its default configuration looks like this:
 195
 196 ```xml
 197 <simulator-config xmlns="urn:onf:params:xml:ns:yang:network-topology-simulator">
 198         <simulated-devices>0</simulated-devices>
 199         <mounted-devices>0</mounted-devices>
 200         <notification-config>
 201                 <fault-notification-delay-period>0</fault-notification-delay-period>
 202                 <ves-heartbeat-period>0</ves-heartbeat-period>
 203                 <is-netconf-available>true</is-netconf-available>
 204                 <is-ves-available>true</is-ves-available>
 205         </notification-config>
 206         <controller-details>
 207                 <controller-ip>172.17.0.1</controller-ip>
 208                 <controller-port>8181</controller-port>
 209                 <controller-username>admin</controller-username>
 210                 <controller-password>admin</controller-password>
 211         </controller-details>
 212         <ves-endpoint-details>
 213                 <ves-endpoint-ip>172.17.0.1</ves-endpoint-ip>
 214                 <ves-endpoint-port>30007</ves-endpoint-port>
 215                 <ves-endpoint-auth-method>no-auth</ves-endpoint-auth-method>
 216                 <ves-registration>false</ves-registration>
 217         </ves-endpoint-details>
 218 </simulator-config>
 219 ```
 220
 221 This configuration can be altered by connecting to the NTS Manager with a NETCONF Client.
 222
 223 ### Starting a simulated device
 224
 225 Example of starting **one** simulated device:
 226
 227 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:
 228
 229 ```
 230 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
 231 ```
 232
 233 We can see that the simulated device has 10 NETCONF Endpoints listening for connections. The first 7 (50000 to 50006) are SSH connections, while the last 3 (50007 to 50009) are TLS connections.
 234
 235
 236 ## Troubleshooting
 237
 238 ### No simulated devices are starting
 239
 240 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.
 241
 242 Example of a result of such a command:
 243
 244 ```
 245 ntsim_oran       latest           57b065de4458     4 days ago     785MB
 246 ```
 247
 248 This means that `MODELS_IMAGE: "ntsim_oran:latest"` can be used as an environment variable when starting the NTS Manager.