fix(docs): File placements

Signed-off-by: pmikus <peter.mikus@protonmail.ch>
Change-Id: I64e8e7f545acbd7faa96438f93a3cf2139221a06

1 files changed, 326 insertions, 0 deletions

diff --git a/docs/toi/vagrant.md b/docs/toi/vagrant.md
new file mode 100644
index 0000000000..21890f86eb
--- /dev/null
+++ b/docs/toi/vagrant.md
@@ -0,0 +1,326 @@
+# FD.io CSIT Development Environment
+
+The intent of this document is to give you a quick start guide for setting up a CSIT development and testing environment inside a Vagrant VM.
+
+## Pulling CSIT code
+
+The first step is to pull the FD.io CSIT code. Eventhough the fastest way is to pull the code anonymously using https by typing the below command, the recommended way is to pull code via ssh if you intend to develop and commit changes upstream.
+```
+git clone https://gerrit.fd.io/r/csit
+```
+To pull the code via ssh, you'll first need to setup a Linux Foundation (LF) account as fd.io uses the Linux Foundations identity system. If you do not have an LF account, proceed to [Linux_Foundations_Identity_Setup](https://identity.linuxfoundation.org) to setup one. Once you have setup your Linux Foundation username and password, you can use if for all fd.io logins.
+
+After you've setup your account, make sure you have registered your [ssh key with
+gerrit](https://wiki.fd.io/view/DEV/Setting_up_Gerrit). Then pull the code by typing the below command. Replace USERNAME with your Linux Foundation username.
+
+```
+git clone ssh://USERNAME@gerrit.fd.io:29418/csit.git
+```
+
+## Standing up Linux VM
+
+To setup your dev environment, you'll want to stand up a Linux VM. The CSIT repo provides a
+Vagrantfile to help you quickly setup an Ubuntu Jammy VM. This file is located in the csit.infra.vagrant folder.
+
+If you haven't already installed Vagrant, install it by following the instructions [here](https://developer.hashicorp.com/vagrant/docs/installation).
+
+Vagrant works well with the VirtualBox provider. We have only tested Vagrant with the VirtualBox provider for setting up a CSIT dev/test environment. Install the VirtualBox hypervisor on your
+host machine by following the instructions for [Installing VirtualBox](https://www.virtualbox.org/wiki/Downloads).
+
+If you've more than one hypervisor in use on the host machine, you'll most likely encounter an error when bringing up the VM. You must ensure that other hyperviors such as Hyper-V or KVM are disabled.
+
+### Ensure KVM and Hyper-V are disabled on the host
+
+If you have a Linux machine, ensure KVM is disabled:
+```
+lsmod | grep kvm
+```
+If you see kvm or kvm_intel in the output, you'll need to use the blacklist command to add it to the deny list.
+```
+echo 'blacklist kvm-intel' | sudo tee -a /etc/modprobe.d/blacklist.conf
+```
+
+If you have a Windows machine, ensure Hyper-V is disabled in system settings.
+
+ - Right click on the Windows button and select 'Apps and Features'.
+ - Select Turn Windows Features on or off.
+ - Unselect Hyper-V and click OK.
+
+ Reboot your host machine for the changes to take effect.
+
+### Starting the Vagrant VM
+
+The CSIT Vagrantfile: csit/csit.infra.vagrant/Vagrantfile is used to start up the Ubuntu
+jammy VM with 8GB of RAM and 4 VCPUs. Vagrant boots up the VM and provisions software in it
+using ansible local. Ansible installation is not required on the host.
+
+The inventory path for ansible provisioning on the vagrant VM is located at:
+csit/fdio.infra.ansible/inventories/vagrant_inventory/hosts.
+
+The ansible playbook used for the vagrant host is located at:
+/home/vagrant/csit/fdio.infra.ansible/vagrant.yaml
+
+If your host OS is Linux, you may have to increase the maximum map count to a high value to
+ensure that the Linux Kernel allows the VirtualBox hypervisor to allocate the required memory
+maps. You can do this by typing the below command:
+```
+sudo sysctl -w vm.max_map_count=262144
+```
+
+If you're using a proxy, you'll need to export your proxy settings to facilitate software provisioning within the Vagrant VM.
+```
+export VAGRANT_APT_HTTP_PROXY=http://{Your_Proxy_URL}:{Proxy_Port}
+export VAGRANT_APT_HTTPS_PROXY=http://{Your_Proxy_URL}:{Proxy_Port}
+export VAGRANT_HTTPS_PROXY=http://{Your_Proxy_URL}:{Proxy_Port}
+export VAGRANT_HTTP_PROXY=http://{Your_Proxy_URL}:{Proxy_Port}
+```
+
+Ansible downloads stable VPP packages from Packagecloud. The VPP version used for testing
+can be set by updating the file: csit/VPP_STABLE_VER_UBUNTU_JAMMY.
+
+To bring up the Ubuntu jammy VM with virtualbox provider and provision software, type the command
+```
+vagrant up
+```
+
+If everything goes well, vagrant will boot up the VM, mount shared folders and provision all the required software for running CSIT tests. The csit repository on the host will be mounted at /home/vagrant/csit on the VM.
+
+### Running Device Tests
+
+After your VM is provisioned, start by running VPP device tests. To do this type the
+following commands:
+```
+vagrant ssh   # login to the VM
+cd /home/vagrant/csit/resources/libraries/bash/entry
+./bootstrap_vpp_device.sh csit-vpp-device-master-ubuntu2004-1n-vbox
+```
+
+The script will pack and copy the test framework into the docker containers named csit-tg-* and csit-dut1-* via ssh. The copied tarball will be extracted in the docker container.
+Once the nodes are ready, you'll see device tests being executed in the docker container and the test results.
+
+### Your questions answered
+
+1) Where are the tests located and how are they written?
+
+    CSIT tests are written using an open source automation framework called the [Robot Framework](https://robotframework.org/). The tests are present in the /tests folder. Infact these tests are used as templates to generate new robot tests for testing various interface types. The new interface tests are generated at runtime and stored in the /generated/tests folder. For VM based testing of interfaces, you should see robot tests generated for 1GE interfaces in this folder.
+
+2) I am getting a robot error, [ ERROR ] Suite 'Tests' contains no tests matching tag '2 node single link topo', not matching tags 'avf', 'vhost', 'flow', 'NIC "HW 4xxx"', 'NIC "HW C4xxx"', 'NIC Amazon-Nitro-100G', 'NIC Amazon-Nitro-200G', 'NIC Amazon-Nitro-50G', 'NIC Intel-DSA', 'NIC Intel-E810CQ', 'NIC Intel-E810XXV', 'NIC Intel-E822CQ', 'NIC Intel-X520-DA2', 'NIC Intel-X553', 'NIC Intel-X710', 'NIC Intel-XL710', 'NIC Intel-XXV710', 'NIC Mellanox-CX556A', 'NIC Mellanox-CX6DX', 'NIC Mellanox-CX7VEAT' or 'NIC azure-mlx-40g' and matching name 'devicetest' in suite 'tests.vpp.device'. How do I resolve this?
+
+    This error means that the robot framework is missing the virtual interface specification in its configuration. To resolve this issue, update the file: resources/library/python/Constants.py by adding a mapping for the nic named virtual. For instance, create two mappings such as:
+    ```
+    "virtual": "1ge1p82540em"
+    "virtual": ["vfio-pci"]
+    ```
+    Add the appropriate mapping into,
+     -  NIC_NAME_TO_CODE
+     -  NIC_CODE_TO_SHORT_NAME
+     -  NIC_NAME_TO_DRIVER
+     -  NIC_DRIVER_TO_PLUGINS
+     -  NIC_DRIVER_TO_TAG
+     -  NIC_DRIVER_TO_SUITE_PREFIX
+     -  NIC_DRIVER_TO_VFS
+     -  DPDK_NIC_NAME_TO_DRIVER
+
+    After this, delete the /generated/tests folder. We are using job_spec files for test definition. See /resources/job_specs/vpp_device. If a job spec is missing for vbox, create a new job spec by just copying and pasting the existing vpp-1n-spr.md to vpp-1n-vbox.md. However, change the NIC to virtual!
+
+    Next, in the file: resources/libraries/bash/function/common.sh add the below line to create a substitution for the virtual NIC,
+    ```
+    awk_nics_sub_cmd+='gsub("virtual","1ge1p82540em");'
+    ```
+    Also, keep the “virtual” in vpp-1n-vbox.md (column 4).
+    Now re-run the tests and in robot command line (log) you should start seeing --test <name> --test <name> etc.
+
+3) Where can I find test run logs?
+
+    Test run logs are present in the /archives folder. You should find a file named log.hml in this folder.
+
+4) I am seeing a Docker image not found error when running tests.
+   How do I build the required docker images?
+
+    You should have two docker images inside the VM named,
+    - base-ubuntu2204:local
+    - csit_sut-ubuntu2204:local.
+
+    If these images are missing, you can create them by typing the below commands:
+    ```
+    cd /opt/csit-docker-images/base
+    docker build -t base-ubuntu2204:local .
+
+    cd /opt/csit-docker-images/csit-sut
+    docker build -t csit_sut-ubuntu2204:local .
+    ```
+
+5) VPP is failing to start inside the docker container. How do I fix this?
+
+    First start by looking at the log.html file. You should find the startup configuration used to start VPP. For instance, your startup.conf file could look like the below,
+    ```
+    {
+        log /var/log/vpp/vpp.log
+        cli-listen /run/vpp/cli.sock
+        cli-no-pager
+        gid vpp
+        full-coredump
+    }
+    socksvr
+    {
+        socket-name /run/vpp/api.sock
+    }
+    memory
+    {
+        main-heap-size 2G
+        main-heap-page-size 2M
+        default-hugepage-size 2M
+    }
+    statseg
+    {
+        size 2G
+        page-size 2M
+        per-node-counters on
+    }
+    plugins
+    {
+        plugin default
+        {
+            disable
+        }
+        plugin dpdk_plugin.so
+        {
+            enable
+        }
+    }
+    dpdk
+    {
+        dev 0000:00:10.0
+        dev 0000:00:11.0
+    }
+    ip6
+    {
+        hash-buckets 2000000
+        heap-size 4G
+    }
+    ```
+    One common reason for VPP not starting up is not allocating enough hugepages for VPP inside the VM. Increase the number of hugepages to 2560 by typing the below command and try running the tests again.
+
+    ```
+    sudo sysctl -w vm.nr_hugepages=2650
+    ```
+
+6) How do I check if the robot test cases for virtual interfaces have been successfully generated?
+
+    Check the /generated/tests folder for all the generated tests. If you're running VPP device tests, generated tests will be found in the sub-folder named vpp/device. If you've named your virtual interface  "1ge1p82540em", you will find robot test files with names 2n1l-1ge1p82540em-*
+
+7) For debugging, how do I prevent the test environment from being torn down after a test run?
+
+    You can disable the CSIT framework from cleaning up the test environment by setting the environment variable CSIT_NO_CLEANUP=1.
+
+    To reset the environment back for regular test runs, reboot the VM by typing the command,
+
+    ```
+    vagrant reload
+    ```
+
+    This will terminate all docker containers and free up all pci interfaces grabbed by dpdk.
+
+    ```
+    cd /home/vagrant/csit/resources/libraries/bash/entry
+    CSIT_NO_CLEANUP=1 ./bootstrap_vpp_device.sh csit-vpp-device-master-ubuntu2004-1n-vbox
+    ```
+
+8) How do I ssh into the docker container for further troubleshooting?
+
+    First disable test environment cleanups by following the instructions above. This will leave the TG and DUT1 docker containers running. You can now ssh into the csit-dut1-* docker container for further troubleshooting, such as running VPP or robot tests by hand. To do so, find the port published by the DUT1 docker container by typing the below command and then ssh into the container as root. The default root password is Csit1234.
+    ```
+    docker ps  # list all running containers and get the csit-dut1-* container ID
+    docker port ${DUT1_CONTAINER_ID}   # get the published docker container port
+    ssh root@{HOST_IP_ADDRESS} -p {DOCKER_PORT}  # ssh into the container
+    ```
+
+9) What's the CSIT test topology used for VM tests and where's the topology file?
+
+    CSIT generates a 2 node topology with a TG docker node connected to a DUT1 docker node.
+    The topology file is located at topologies/available/vpp_device.yaml
+    For instance, here's a sample topology file generated by CSIT -
+    ```
+    metadata:
+    version: 0.1
+    schema:
+        - resources/topology_schemas/2_node_topology.sch.yaml
+        - resources/topology_schemas/topology.sch.yaml
+    tags: [dcr, 2-node]
+
+    nodes:
+    TG:
+        type: "TG"
+        host: "10.0.2.15"
+        arch: "x86_64"
+        port: 32768
+        username: "root"
+        interfaces:
+            port0:
+                mac_address: "08:00:27:0f:e0:4d"
+                pci_address: "0000:00:08.0"
+                link: "link0"
+                model: virtual
+                driver: "e1000"
+                vlan: 0
+            port1:
+                mac_address: "08:00:27:61:f7:ad"
+                pci_address: "0000:00:09.0"
+                link: "link1"
+                model: virtual
+                driver: "e1000"
+                vlan: 0
+
+    DUT1:
+        type: "DUT"
+        host: "10.0.2.15"
+        arch: "x86_64"
+        port: 32769
+        username: "root"
+        interfaces:
+            port0:
+                mac_address: "08:00:27:38:5e:58"
+                pci_address: "0000:00:10.0"
+                link: "link0"
+                model: virtual
+                driver: "e1000"
+                vlan: 0
+            port1:
+                mac_address: "08:00:27:e3:f5:42"
+                pci_address: "0000:00:11.0"
+                link: "link1"
+                model: virtual
+                driver: "e1000"
+                vlan: 0
+    ```
+
+10) How do I run an ansible task after the VM is provisioned?
+
+    You can run a specific ansible task after the VM has been provisioned using ansible tags.
+    For instance, you can run the tasks that has been tagged docker_images, by typing the below ansible command,
+
+    ```
+    cd ~/csit/fdio.infra.ansible
+    ansible-playbook vagrant.yaml --tags "docker_images" -i inventories/vagrant_inventory/hosts
+    ```
+
+11) Docker image build is failing due to a network error. Where do I set proxy settings for Docker?
+
+    You can set proxy settings for Docker in the file ~/.docker/config.json. Update this file with your environment's proxy info -
+    ```
+    {
+        "proxies":
+        {
+            "default":
+            {
+            "httpProxy": "http://{Proxy_IP_Address}:{Proxy_Port}",
+            "httpsProxy": "http://{Proxy_IP_Address}:{Proxy_Port}",
+            "noProxy": "localhost,127.0.0.1"
+            }
+        }
+    }
+    ```
+
+12) Where should I set the proxy vars for Ansible?
+
+    Set Ansible proxy variables in the file - fdio.infra.ansible/roles/common/defaults/main.yaml. Uncomment the proxy_env: section and fill the correct proxy values for your dev/test environment.