# ODTN LAB - 2023

###### tags: `unicamp`

This lab aims to create the foundation knowledge on using ONOS as an SDN controller for optical networks. To do so, ODTN-emulator is used to provide the necessary emulated equipment.

This lab is organized in 5 parts, as follows:

1. Platform - Running ONOS and ODTN-emulator
2. NETCONF - Exploring ONOS and ODTN-emulator message exchange
3. NETCONF - Using netconf-console for reading
4. NETCONF - Using netconf-console for changing configuration
5. YANG Models, OpenConfig and NETCONF

# System requirements:

- Virtualbox 7.x
- Download the ODTN/YANG lab VM from here (~18GB): [ODTN_RPP_BIOS.ova](https://drive.google.com/file/d/1MR00HfqrqXaB8H4qHjqOxZTW7IjIuvE2/view?usp=sharing)
[ODTN_RPP_BIOS.ova.sha512](https://drive.google.com/file/d/1IFFjb3VzVMf-loTLBL1kqEfEIeXS29s2/view?usp=sharing)
-- Uses 5GB of RAM and ~36GB of disk
-- Credentials:

    odtn
    rocks

## PART 1: Platform - Running ONOS and ODTN-emulator

By the end of PART 1, you will have the following running system:


In order to organize the data generated from executing commands, let's create a new directory. Open up a terminal and type:

$ mkdir -p ~/lab/odtn/inspect

:::warning
From now on, this directory will be refered to as `$INSPECT`.
:::

### Running ONOS

After compiling ONOS, it's time to run it. Open a terminal and type:

$ cd ~/git-repos/onos
$ export ONOS_APPS=odtn-service,roadm,gui2,optical-rest,org.onosproject.models.common,org.onosproject.yang-gui
$ bazel run onos-local -- clean

This terminal will keep showing ONOS log. So, don't type any other command here.

### Running ODTN-emulator

After generating the ODTN-emulator containers it's time to put them to run. Open a terminal, change to the ODTN-emulator directory, and run `docker-compose`:

$ cd ~/git-repos/ODTN-emulator
$ docker-compose up -d

Inspect running containers with the following command:

$ docker ps

You should see at least the following 3 containers:

CONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS                                      NAMES
e0cddf773b09        odtn-emulator_openconfig_cassini_1   "sh /root/script/pus…"   4 days ago          Up 4 days           22/tcp, 8080/tcp, 0.0.0.0:11002->830/tcp   odtn-emulator_openconfig_cassini_1_1
12bcb9a68531        odtn-emulator_openconfig_cassini_2   "sh /root/script/pus…"   4 days ago          Up 4 days           22/tcp, 8080/tcp, 0.0.0.0:11003->830/tcp   odtn-emulator_openconfig_cassini_2_1
8ab6d4910815        odtn-emulator_tapi_ols               "sh /root/script/ent…"   4 days ago          Up 4 days           0.0.0.0:11000->1234/tcp                    odtn-emulator_tapi_ols_1

### Testing ODTN-emulator

Before informing ONOS about the ODTN devices, let's interact with ODTN-emulator using `netconf-console`. Open a terminal and type:

$ netconf-console --host localhost --port 11002 -u root -p root --hello

:::danger
If ODTN-emulator is working appropriately, you should see an XML message.

1. What is this message all about? Can you explain the message in detail?
:::

### Uploading configuration to ONOS

Up until now, ONOS and ODTN-emulator were strangers to each other. Let's introduce ODTN-emulator to ONOS by providing the configuration files to make it possible for **ONOS to connect to each emulated device**. Open a terminal and type:

$ onos-netcfg localhost ~/git-repos/ODTN-emulator/topo/with-rest-tapi/device.json
$ onos-netcfg localhost ~/git-repos/ODTN-emulator/topo/with-rest-tapi/link.json

> If the system PATH environment variable is not set correctly, `onos-netcfg` must be invoked providing the full script path: `~/git-repos/onos/tools/package/runtime/bin/onos-netcfg`

:::warning
Click on `Details` bellow to see the contents of files `device.json` and `link.json`
:::
:::spoiler
**Here's the contents of file `device.json`**

{
  "devices" : {
    "netconf:127.0.0.1:11002" : {
      "basic" : {
        "name":"cassini2",
        "driver":"cassini-openconfig"
      },
      "netconf" : {
        "ip" : "127.0.0.1",
        "port" : "11002",
        "username" : "root",
        "password" : "root",
        "idle-timeout" : "0"
      }
    },
    "rest:127.0.0.1:11000": {
      "rest": {
        "ip": "127.0.0.1",
        "port": 11000,
        "protocol": "http",
        "testUrl":"/restconf/data/tapi-common:context",
        "manufacturer": "tapi-swagger",
        "hwVersion": "0",
        "swVersion": "2.1"
      },
      "basic": {
        "driver": "ols"
      }
    },
    "netconf:127.0.0.1:11003" : {
      "basic" : {
        "name":"cassini1",
        "driver":"cassini-openconfig"
      },
      "netconf" : {
        "ip" : "127.0.0.1",
        "port" : "11003",
        "username" : "root",
        "password" : "root",
        "idle-timeout" : "0"
      }
    }
  }
}

>It basically provides the endpoints to enable ONOS to connect to. Also, the driver to be used, the communication protocol, and protocol dependent parameters, such as username and password.
If you observe the field name, this is how you give a friendly name to your device to appear at ONOS Web interface;
:::
:::spoiler
**Here's the contents of file `link.json`**

{
  "links": {
    "netconf:127.0.0.1:11002/201-rest:127.0.0.1:11000/100000035178": {
      "basic": {
        "type": "OPTICAL",
        "metric": 1,
        "durable": true,
        "bidirectional": true
      }
    },
    "rest:127.0.0.1:11000/100000035182-netconf:127.0.0.1:11003/201": {
      "basic": {
        "type": "OPTICAL",
        "metric": 1,
        "durable": true,
        "bidirectional": true
      }
    }
  }
}

:::

### See results

Now, open a web browser and type the following URL:

http://localhost:8181/onos/ui

> This URL should work as long as you are running a WEB Browser from the same system ONOS is running. If ONOS is running in another system you must replace `localhost` with the correct IP address.

If you succeeded in connecting to ONOS with a WEB Browser, you should see a login interface such as the one:


Type the following credentials:

USERNAME: onos
PASSWORD: rocks

After a succesful login, ONOS shows the optical network topology such as the one seen in the figure:


Now select the ONOS "devices view":


It's possible to see that ONOS inspected the devices and detected the number of ports and other features:


Select a device to see ports information:


That's it for the first part. Now let's proceed to the next part.

## PART 2: NETCONF - Exploring ONOS and ODTN-emulator message exchange

The following sequence diagram shows several messages exchanged between ONOS and an emulated Cassini device (provided by the ODTN-emulator). We will explore and inspect some of these messages. To do so, we will access ONOS cli, enable NETCONF logging, and capture NETCONF messages. ONOS Gui from the web browser will be used to generate some of these messages.


### Connect to ONOS cli

Let's **connect to ONOS cli**, **enable NETCONF log**, and, at the same time, **save all console messages** to a local file for further investigation.

1. Connect to ONOS cli. To do so, open a terminal and type:

$ ssh -p 8101 onos@localhost | tee $INSPECT/onos.netconf.output

> Password is rocks.
> Please note the meaning of $INSPECT, described at the very begining of PART 2.

> :exclamation: In particular cases, you can face the following error:
> <font size="-1">
>>\@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
>> \@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! \@
>> \@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
>> IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING >> NASTY!
>> Someone could be eavesdropping on you right now (man-in-the-middle attack)!
>> It is also possible that a host key has just been changed.
>> The fingerprint for the RSA key sent by the remote host is
>> SHA256:nsasa432rCwaWgpwZfVDxyzdghas5sldadsda.
>> Please contact your system administrator.
>> Add correct host key in /home/odtn/.ssh/known_hosts to get rid of this message.
>> Offending RSA key in /home/odtn/.ssh/known_hosts:43
>> Host key for [localhost]:8101 has changed and you have requested strict checking.
>> Host key verification failed.
></font>
>
> This happens when the ssh fingerprint of ONOS has changed. In a non-threatening security case, it can happen if ONOS is restarted and/or recompiled.
>
> In this case, you can just remove entry 43, as informed by line **Offending RSA key in /home/odtn/.ssh/known_hosts:43**, using sed:
> ```bash
> $ sed -i '43d' ~/.ssh/known_hosts
> ```
> After that just try the `ssh` command again.

After connecting to ONOS cli you should see a prompt like:

:::success
onos@root >
:::

2. Enable log output from NETCONF

:::success
onos@root > log:set TRACE org.onosproject.netconf
onos@root > log:set TRACE org.onosproject.drivers.netconf
onos@root > log:tail
:::

> As long as `log:tail` is executing, this shell will not be available to type other commands.

So, let's go ahead and open ONOS roadm-gui app.

### Open ONOS Web GUI - NETCONF get - reading values

1. Open a web browser and type the following URL:

http://localhost:8181/onos/ui/#/roadm-gui

2. Select **cassini1** and click the upper right PORT icon, just like the following image:


3. Observe the ONOS log output from the cli (ssh session) - it scrolls really fast, you would probably need to analyze the output offline (`onos.netconf.output`). This is how a *get* request for *input-power-range* should look like:

#374
<?xml version="1.0" encoding="UTF-8"?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="720">
  <get>
    <filter>
      <components xmlns="http://openconfig.net/yang/platform">
        <component>
          <name>xe6/1</name>
          <optical-channel xmlns="http://openconfig.net/yang/terminal-device">
            <state>
              <input-power-range/>
	    </state>
          </optical-channel>
        </component>
      </components>
    </filter>
  </get>
</rpc>
##

:::danger
2. Can you guess what `#374 ` and `##` are used for? If so, complement your response pointing out any other previous method to achieve the same purpose. Tip: It's related to framing.
:::

4. Stop `log:tail` at ONOS cli.
Access the ONOS cli, the one executing `onos@root > log:tail`, and type the keys `ctrl-c` simultaneously. It will stop `log:tail.` Now type `logout`. This should leave ONOS cli.

:::danger
3. Open file `onos.netconf.output` and try to find messages numbered 5 and 6 on the sequence diagram. Inform the element name and the value being returned.
:::

### Open ONOS Web GUI - NETCONF edit-config - changing configuration

Now it's time to explore NETCONF messages to change the device configuration. Let's start by repeating steps from [Connect to ONOS cli](https://hackmd.io/ZiuEJAsuTb6TbvKNj58KdA?both#Connect-to-ONOS-cli).

> IMPORTANT: If you don't want to overwrite the previous file, replace the filename `onos.netconf.output` with `onos.netconf.output2`.

Also, repeat steps 1 and 2 from [Open ONOS Web GUI - reading values](https://hackmd.io/ZiuEJAsuTb6TbvKNj58KdA?both#Open-ONOS-Web-GUI---NETCONF-get---reading-values).

After completing the previous steps, let's go ahead and observe what a NETCONF *edit-config* looks like:

1. Change the first port of **cassini1** Target Output Power to -5 dBm. To do so, fill in the indicated field (1) and press the Submit button (2), as indicated by the following figure:


> This action will take some time, so sit tight and wait for the action to take effect. After you see all other ports set to the same value, the action is complete.

2. Observe the ONOS log output from the cli (ssh session) - it scrolls really fast, you would probably need to analyze the output offline (`onos.netconf.output2`). This is how an *edit-config* request to change *target-output-power* should look like:

#447
<?xml version="1.0" encoding="UTF-8"?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1943">
  <edit-config>
    <target>
      <running/>
    </target>
    <config>
      <components xmlns="http://openconfig.net/yang/platform">
         <component>
            <name>oe8/2</name>
            <optical-channel xmlns="http://openconfig.net/yang/terminal-device">
            <config>
               <target-output-power>-5.0</target-output-power>
            </config></optical-channel>
         </component>
      </components>
    </config>
  </edit-config>
</rpc>
##

:::danger
Observe the strucure of this call. Instead of `<get>` you have `<edit-config>`. `<edit-config>` is a NETCONF message to change a device's configuration - message 23 at the sequence diagram above.

4. Open file `onos.netconf.output2`. Could you find the response to this message? Tip: observe the message-id (which is probably different from this example).
5. Elaborate the meaning of `<target>` and `<running/>`. Provide all other possible values for `<target>`.
6. Explain the meaning of `xmlns="http://openconfig.net/yang/terminal-device"` and `xmlns="http://openconfig.net/yang/platform"`.
:::

## PART 3: NETCONF - Using netconf-console for reading

Moving on to cli (command line interface). Instead of use ONOS to read (NETCONF `get` operation) information from cassin1 device, you'll learn how to do that from cli. By the end of this part you will be able to create your own NETCONF `get` calls. So, let's get started.

Open up a terminal and type:

$ cd ~/git-repos/ODTN-emulator

Let's execute the first NETCONF `get` call. Using the same terminal, type the following command to request information regarding all terminal-devices available on one of the **cassinis**:

$ netconf-console --host=127.0.0.1 --port=11002 -u root -p root --rpc=emulator-test/get-terminal-device.xml

> If you want to save the output to the disk just append `> $INSPECT/cassini-terminal-devices.xml` at the end of the previous command. It will create the file `cassini-terminal-devices.xml`. Please note the meaning of $INSPECT, described at the very begining of PART 1.
>
:::danger
7. Can you tell which cassini device is this? cassini1 or 2? Tip: look at file `topo/with-rest-tapi/device.json`.
:::

It generates a huge output, roughly 685 lines and 29764 bytes. So, here's just the first few lines:

<?xml version='1.0' encoding='UTF-8'?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="urn:uuid:34dd0290-8365-402d-b91e-2041f7b4d648">
  <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <terminal-device xmlns="http://openconfig.net/yang/terminal-device">
      <logical-channels>
        <channel>
          <index>10101</index>
          <config>
            <index>10101</index>
            <description>xe1/1</description>
            <admin-state>ENABLED</admin-state>
            <rate-class xmlns:oc-opt-types="http://openconfig.net/yang/transport-types">oc-opt-types:TRIB_RATE_100G</rate-class>
            <trib-protocol xmlns:oc-opt-types="http://openconfig.net/yang/transport-types">oc-opt-types:PROT_100GE</trib-protocol>
            <logical-channel-type xmlns:oc-opt-types="http://openconfig.net/yang/transport-types">oc-opt-types:PROT_ETHERNET</logical-channel-type>
          </config>
          <state>
            <loopback-mode>NONE</loopback-mode>
          </state>
          <ingress>
            <config>
              <transceiver>xe1</transceiver>
            </config>
          </ingress>
          <logical-channel-assignments>
            <assignment>
              <index>10101</index>
              <config>
                <index>10101</index>
                <assignment-type>LOGICAL_CHANNEL</assignment-type>
                <logical-channel>20101</logical-channel>
                <allocation>100.0</allocation>
              </config>
            </assignment>
          </logical-channel-assignments>
        </channel>
....        

Now let's take a look at file `emulator-test/get-terminal-device.xml`. This file provides a NETCONF `get` RPC call. Here's it's contents:

<?xml version="1.0"?>
<get xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <filter xmlns:td='http://openconfig.net/yang/terminal-device'>
    <td:terminal-device/>
  </filter>
</get>

:::danger
Now create your own file with the following call:

<?xml version="1.0"?>
<get xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <filter xmlns:td='http://openconfig.net/yang/terminal-device'>
    <td:terminal-device>
      <logical-channels>
	<channel>
	  <index>20101</index>
	</channel>
      </logical-channels>
    </td:terminal-device>
  </filter>
</get>

8. What's the resulting output?
9. Read the output and provide the following information:
- `//terminal-device/logical-channels/channel/config/description`
- `//terminal-device/logical-channels/channel/logical-channel-assignments/assignment/config/assignment-type`
TIP: This path representation is called xPath and can be used in place of the more verbose XML document. XML documents are structured hierarchically, so is an xPath. So, just follow the XML document hierarchy according to the xPath to obtain the requested information.
10. Can you create another NETCONF `get` call (XML file) that filters `//components/component[name=oe1]`? If so, execute the call and provide the output. TIP: `[name=oe1]` only means that the `<name>` XML tag has the text `oe1`, just like `<index>` above has the value `20101`.
11. EXTRA: Mimicking Steve Jobs, "*one last thing*": Can you filter out all the NETCONF `sessions` (connections) to cassini? If so, provide the call and the output. The output should be something like:

...
<sessions>
        <session>
          <session-id>160</session-id>
          <transport>netconf-ssh</transport>
          <username>root</username>
          <source-host>172.18.0.1</source-host>
          ...

:::

## Reading all available data

You have learned how to ask for small (not really) portions of information from a cassini device. What if you wanted all the available information? The next call does just that. So, open a terminal and type:

$ netconf-console --host=127.0.0.1 --port=11002 -u root -p root --get | less

> It's a 2743-line XML output (104241 bytes). It's huge. That's why we've used the `less` command. You can type `q` anytime to quit `less`. Another alternative is to write the output to a file. If it's your choice, just replace `less` with `$INSPECT/onos.netconf.output3`.

This is a really useful output. From that, you can learn:
- all aspects of the device;
- all installed modules;
- infer YANG models;
- learn what YANG modules are available, and so on.

:::success
**This kind of output is really important!**
As a side note, I used this kind of output to develop 3 ONOS NETCONF drivers for a research project in collaboration with an optical equipment vendor - Therefore, I can't emphasize enough the importance of this output. Dig in and try to learn something else!
:::

## PART 4: NETCONF - Using netconf-console for changing configuration

We have been using NETCONF with `netconf-console` for reading operations. This part will teach you how to change a cassini device configuration. To change configuration, you use NETCONF `edit-config` RPC calls. So, let's go ahead and start changing configurations.

Let's start observing what an `edit-config` call looks like:

<?xml version="1.0"?>
<edit-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <target><running/></target>
  <config>
    <components xmlns="http://openconfig.net/yang/platform">
      <component>
        <name>oe1/2</name>
        <optical-channel xmlns="http://openconfig.net/yang/terminal-device">
          <config>
            <target-output-power>0</target-output-power>
          </config>
        </optical-channel>
      </component>
    </components>
  </config>
</edit-config>

Observe that the second line now has the `edit-config` call. There is also another entry observed at line 3, `<target>`. We have stumbled upon `edit-config` and `<target>` in one of the sections in [PART 2](https://hackmd.io/ZiuEJAsuTb6TbvKNj58KdA?both#Open-ONOS-Web-GUI---NETCONF-edit-config---changing-configuration). Back there, we have used ONOS to change a configuration as well.
<!--Another peculiarity is that the `edit-config` is not wrapped by a tag `<rpc>` as it is the case with `<get>`. But -->
Observe the return we receive when `edit-config` runs succesfully:

<?xml version='1.0' encoding='UTF-8'?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="urn:uuid:beb279aa-a8d2-467f-b9b5-a4332fca4df5">
  <nc:ok/>
</nc:rpc-reply>

As you can see, it's an `rpc-reply` message. Also, observe the tag `<nc:ok/>`.

## Change target-output-power

We are going to modify the previous `edit-config` call to alter the component `oe1/2` `target-output-power` to $-4dBm$.

Open up a terminal and type:

$ cd ~/git-repos/ODTN-emulator
$ mkdir my-calls
$ cd my-calls

Create file `set-oe1-target-output-power.xml` with the following content:

<?xml version="1.0"?>
<edit-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <target><running/></target>
  <config>
    <components xmlns="http://openconfig.net/yang/platform">
      <component>
        <name>oe1/2</name>
        <optical-channel xmlns="http://openconfig.net/yang/terminal-device">
          <config>
            <target-output-power>-4</target-output-power>
          </config>
        </optical-channel>
      </component>
    </components>
  </config>
</edit-config>

Execute the following command to execute your `edit-config` call:

$ netconf-console --host=127.0.0.1 --port=11002 -u root -p root --rpc=set-oe1-target-output-power.xml

:::danger
12. In order to test your NETCONF `edit-config` call, create a NETCONF `get` call to observe the changing in value of `target-output-power`. Provide both the XML used for the call and the return message.
:::

## PART 5: YANG Models, OpenConfig and NETCONF

We haven't defined any YANG module by ourselves, but they are there in every call. We have been using YANG models (groups of modules) indirectly all along. At the very beginning of this lab we issued the following command:

$ netconf-console --host localhost --port 11002 -u root -p root --hello

Part of the resulting output lists the supported YANG modules.

There is another way to inspect the modules supported by our emulated devices. Create file `list-yang-models.xml` with the following content:

<?xml version="1.0"?>
<get xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <filter>
    <yang-library xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
      <module-set>
        <module/>
      </module-set>
    </yang-library>
  </filter>
</get>

Execute the following command to inspect all installed YANG modules:

$ netconf-console --host=127.0.0.1 --port=11002 -u root -p root --rpc=list-yang-models.xml

### What is OpenConfig?

From the [OpenConfig](https://www.openconfig.net/) website:

:::info
"OpenConfig defines and implements a common, vendor-independent software layer for managing network devices. OpenConfig operates as an open source project with contributions from network operators, equipment vendors, and the wider community. OpenConfig is led by an Operator Working Group consisting of network operators from multiple segments of the industry".
:::

The list of available OpenConfig YANG modules can be downloaded from https://github.com/openconfig/public/tree/master/release/models. For instance, the following image shows all files (modules) from the platform model:


:::danger
13. EXTRA: Can you relate the previous output with the filenames found in https://github.com/openconfig/public/tree/master/release/models/platform ? If so, inspect at least 2 files and correlate it's internal structure to the XML files used to transport NETCONF messages.
:::

## YANG GUI ONOS Application

ONOS offers an application that allows to visualize all loaded YANG models. Observe the ```export``` on the command used to initialize ONOS:

$ cd ~/git-repos/onos
$ export ONOS_APPS=odtn-service,roadm,gui2,optical-rest,org.onosproject.models.common,org.onosproject.yang-gui
$ bazel run onos-local -- clean

![YANG-GUI-00.png](https://hackmd.io/_uploads/HJdhCj57T.png)

![YANG-GUI-01.png](https://hackmd.io/_uploads/Hy6JJncXT.png)

Now select a model and see it's source code in YANG:

![YANG-GUI-02.png](https://hackmd.io/_uploads/Hk8P1n9mp.png)