Load Balancer Tutorial Update

docs/loadbalancer/index.rst

@@ -7,37 +7,43 @@ Getting Started
 
 Overview
 -----------------
-- In the following tutorial, we will explore a means of deploying and testing ONVM’s example Layer-3 round-robin load balancer. To do this, we will instantiate a Cloudlab experiment using the :code:`ONVM_LoadBalancer` profile; this topology (shown below) includes two backend servers and a single client, in addition to the ONVM load balancer.
+- In the following tutorial, we will explore a means of deploying and testing ONVM’s load balancer. To do this, we will instantiate a Cloudlab experiment using the :code:`ONVM_LoadBalancer` profile; this topology (shown below) includes two backend servers and a single client, in addition to the ONVM load balancer.
 
   .. image:: ../images/lb-1.png
 
 - After completion of the step-by-step guide below, you may use a number of packet generation tools to test the successful distribution of packets across multiple servers. The tools covered in this tutorial include iPerf and Pktgen, the latter being further described in the previous tutorial. 
 
 Cloudlab Node Setup
 -----------------
-- Open Cloudlab and start a new experiment. When prompted to choose a profile, select :code:`ONVM_LoadBalancer`. For this tutorial, set the number of backend servers to 2, and set the OS Image to :code:`ONVM UBUNTU20.04`. With regards to defining the physical node type, we will leave this blank and expect the default c220g2 nodes. In the following section (under "Finalize"), select the :code:`Cloudlab Wisconsin` cluster, and all remaining inputs are discretionary.
+- Open Cloudlab and start a new experiment. When prompted to choose a profile, select :code:`ONVM_LoadBalancer`. For this tutorial, set the number of backend servers to 2, and set the OS Image to :code:`ONVM & Sledge UBUNTU20.04`. With regards to defining the physical node type, we will leave this blank and expect the default c220g2 nodes. In the following section (under "Finalize"), select the :code:`Cloudlab Wisconsin` cluster, and all remaining inputs are discretionary.
 - Begin by SSHing into each node within the experiment, and download the **Load Balancer Topology Template** `here <ONVM_LB_TopologyDoc.pdf>`_. If you are using any Apple product to complete this tutorial, avoid using Preview as your PDF editor; autofill scripts will not apply. Google Chrome or Adobe Acrobat are viable alternatives.
-- For every node, use :code:`ifconfig` to view all available network interfaces. Record the appropriate name, IPv4 (inet), and MAC address (ether) for each network interface in the Topology Template, as shown below. Note that the client side and server side nodes should be on a different IP subnets. The ONVM_LB node requires the use of two ports: one for connection to the client and one for connecting to the servers. It is recommended that you use the 10-Gigabit SFI/SFP+ network connections. Port IDs will be handled later.
+- For every node, use :code:`ifconfig` to view all available network interfaces. Record the appropriate name, IPv4 (inet), and MAC address (ether) for each network interface in the Topology Template, as shown below. Note that the client side and server side nodes should be on a different IP subnets and the first 3 values of the client ip must match it's serverside onvm port. The first 3 values of the servers and their onvm port must also match.  The ONVM_LB node requires the use of two ports: one for connection to the client and one for connecting to the servers. It is recommended that you use the 10-Gigabit SFI/SFP+ network connections. Port IDs will be handled later.
 
   .. image:: ../images/lb-2.png
 
-- In the ONVM LB node, set up the environment using :code:`setup_cloudlab.sh` in the scripts directory. Once the ports have been successfully bound to the DPDK-compatible driver, start the manager with at least two available ports. Listed below are the abbreviated steps for binding available ports to the DPDK-bound driver. To start the manager, you may use :code:`./onvm/go.sh -k 3 -n 0xFF -s stdout`.
-
-  #. Unbind the connected NICs: :code:`sudo ifconfig <IFACE> down` where <IFACE> represents the interface name (eg. :code:`enp6s0f0`)
+Running ONVM Manager
+-----------------
+
+- In the ONVM LB node
+
+  #. Unbind both of the connected NICs: :code:`sudo ifconfig <IFACE> down` where <IFACE> represents the interface name (eg. :code:`enp6s0f0`)
   #. Navigate to the :code:`/local/onvm/openNetVM/scripts` directory and bind the NICs to DPDK using the command :code:`source ./setup_cloudlab.sh`
   #. Ensure that you see the two NICs in the section defining “Network devices using DPDK-compatible driver.” If you only see one NIC, it’s possible that you did not unbind the other NIC from the kernel driver using :code:`sudo ifconfig <IFACE> down`. Repeat step (i).
-  #. Navigate back to the openNetVM folder (:code:`cd ..`) and compile the Manager using :code:`cd onvm && make && cd ..`
+  #. Navigate back to the openNetVM folder (:code:`cd ..`), and compile the Manager using :code:`cd onvm && make && cd ..`
+  #. Navigate to examples folder :code:`cd examples && make && cd ..`
+  #. Run the manager :code:`./onvm/go.sh -k 3 -n 0xFF -s stdout`
 
 - At the top of the manager display (pictured below), you can observe two (or more) port IDs and their associated MAC addresses. Use these ID mappings to complete the Port ID sections of the **Topology Template**.
 
   .. image:: ../images/lb-3.png
 
 - Now that the **Topology Template** is complete, all commands within the PDF document should be populated. To complete our LB configuration, we must:
 
-  #. Specify the backend servers’ port information in **server.conf**
+  #. Specify the backend servers’ port information in **server.json**
   #. Define a static route in each of the backend servers to specify the correct gateway for which traffic will enter. 
 
-- To specify the server information for the load balancer, go to :code:`/examples/load_balancer/server.conf` and copy the information that is shown in the bottom left quadrant of your **Topology Template**. This includes the *"LIST_SIZE 2"* and the IP+MAC address of each port.
+- To specify the server information for the load balancer, go to :code:`/examples/load_balancer/server.json` and copy the json code that is shown in the bottom left quadrant of your **Topology Template**. This includes the *"list_size 2"*, the policy, and the IP + MAC address + weight of each port.
+- The Load Balancer currently supports random ("random"), weighted random ("weighted_random"), and round robin ("rrobin") packet distribution policies. The policy may be selected in the json using the strings provided in parenthesis. Weight fields are only required for weighted random policy.
 - To define the static routes, navigate to the two backend nodes (Server1 and Server2) and execute the respective commands shown on the bottom-center area of the **Topology Template**. This includes the :code:`sudo ip route add *` command for each server.
 
 Running The Load Balancer

examples/Makefile

@@ -40,7 +40,9 @@ $(error "Please define RTE_SDK environment variable")
 endif
 
 # To add new examples, append the directory name to this variable
-examples = bridge basic_monitor simple_forward speed_tester flow_table test_flow_dir aes_encrypt aes_decrypt flow_tracker load_balancer arp_response nf_router scaling_example load_generator payload_scan firewall simple_fwd_tb l2fwd test_messaging l3fwd fair_queue
+
+examples = bridge basic_monitor simple_forward speed_tester flow_table test_flow_dir aes_encrypt aes_decrypt flow_tracker load_balancer arp_response nf_router scaling_example load_generator payload_scan firewall simple_fwd_tb l2fwd test_messaging l3fwd fair_queue skeleton
+
 
 ifeq ($(NDPI_HOME),)
 $(warning "Skipping ndpi_stats NF as NDPI_HOME is not set")

examples/skeleton/Makefile

@@ -0,0 +1,67 @@
+#                    openNetVM
+#      https://github.com/sdnfv/openNetVM
+#
+# BSD LICENSE
+#
+# Copyright(c)
+#          2015-2017 George Washington University
+#          2015-2017 University of California Riverside
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in
+# the documentation and/or other materials provided with the
+# distribution.
+# The name of the author may not be used to endorse or promote
+# products derived from this software without specific prior
+# written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ifeq ($(RTE_SDK),)
+$(error "Please define RTE_SDK environment variable")
+endif
+
+
+# Default target, can be overriden by command line or environment
+include $(RTE_SDK)/mk/rte.vars.mk
+RTE_TARGET ?= x86_64-native-linuxapp-gcc
+
+# binary name			[EDIT & ADD NF TAG TO "examples" VARIABLE WITHIN MAKEFILE OF EXAMPLES DIRECTORY]
+APP = skeleton
+
+# all source are stored in SRCS-y
+SRCS-y := skeleton.c
+
+ONVM= $(SRCDIR)/../../onvm
+
+CFLAGS += $(WERROR_FLAGS) -O3 $(USER_FLAGS)
+
+CFLAGS += -I$(ONVM)/onvm_nflib
+CFLAGS += -I$(ONVM)/lib
+LDFLAGS += $(ONVM)/onvm_nflib/$(RTE_TARGET)/libonvm.a
+LDFLAGS += $(ONVM)/lib/$(RTE_TARGET)/lib/libonvmhelper.a -lm
+
+# workaround for a gcc bug with noreturn attribute
+# http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12603
+ifeq ($(CONFIG_RTE_TOOLCHAIN_GCC),y)
+CFLAGS_main.o += -Wno-return-type
+endif
+
+include $(RTE_SDK)/mk/rte.extapp.mk

examples/skeleton/README.md

@@ -0,0 +1,32 @@
+Skeleton
+==
+This is an example NF that acts as a basic skeleton NF.
+
+Compilation and Execution
+--
+```
+cd examples
+make
+cd skeleton
+./go.sh SERVICE_ID [-p TIME_PRINT_DELAY | -v PACKET_PRINT_DELAY]
+
+OR
+
+./go.sh -F CONFIG_FILE -- -- [-p PRINT_DELAY]
+
+OR
+
+sudo ./build/skeleton -l CORELIST -n 3 --proc-type=secondary -- -r SERVICE_ID -- [-p TIME_PRINT_DELAY | -v PACKET_PRINT_DELAY]
+```
+
+App Specific Arguments
+--
+  - `-p <time_print_delay>`: time between each print, e.g. `-p 1` prints after every second.
+  - `-v <packet_print_delay>`: number of packets between each print, e.g. `-v 1` prints after every packet.
+
+Config File Support
+--
+This NF supports the NF generating arguments from a config file. For
+additional reading, see [Examples.md](../../docs/Examples.md)
+
+See `../example_config.json` for all possible options that can be set.

examples/skeleton/go.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+#The go.sh script is a convinient way to run start_nf.sh without specifying NF_NAME
+
+NF_DIR=${PWD##*/}
+
+if [ ! -f ../start_nf.sh ]; then
+  echo "ERROR: The ./go.sh script can only be used from the NF folder"
+  echo "If running from other directory use examples/start_nf.sh"
+  exit 1
+fi
+
+# only check for running manager if not in Docker
+if [[ -z $(pgrep -u root -f "/onvm/onvm_mgr/.*/onvm_mgr") ]] && ! grep -q "docker" /proc/1/cgroup
+then
+    echo "NF cannot start without a running manager"
+    exit 1
+fi
+
+../start_nf.sh "$NF_DIR" "$@"