Use JSON Config Files to Launch NFs (#229)

ONVM now supports JSON config files, which can be loaded through the API provided in onvm_config_common.h. This allows various settings of either the ONVM manager or NFs to be set in a JSON config file and loaded into code, as opposed to needing to be passed in via the command line.

Usage:

* All example NFs now support passing DPDK and ONVM arguments in a config file by using the -F config.json flag when running an NF executable or a go.sh script. See docs/examples.md for more details.

API Changes:

* nflib.c was not changed from an NF-developer standpoint, but it was modified to include a check for the -F flag, which indicates that a config file should be read to launch an NF.

API Additions:

* `cJSON* onvm_config_parse_file(const char* filename)` - Reads a JSON config and stores the contents in a cJSON struct. For further reference on cJSON
`int onvm_config_create_nf_arg_list(cJSON* config, int* argc, char** argv[])` - Given a cJSON struct and pointers to the original command line arguments, generate a new argc and argv using the config file values.

Commit log:

* Updated example Makefiles to include JSON.

* Created config parsing files.

* Added function definitions for config helpers.

* Updated bridge Makefile to fix compile error.

Also added helper functions to onvm_config_common.c

* Updated license information.

* Added documentation for config file API

* Modified API to return status codes instead of values

- Returns 0 or -1 depending on success
- Functions take a pointer to hold result

* Modified API to reflect new config structure

* *DOES NOT RUN* Added function to create DPDK arg list from config file

- Currently has a buffer overflow error
- No support for overriding arguments

* Added functions to build a full command-line string from config file

- Separate functions to build each piece
- NOTE: more testing is required, does not run as expected

* CURRENTLY CRASHES: Finished arg parsing for dpdk, onvm, and the nf

* Fixed segfaulting problem, triple pointer was not correctly dereferenced

* Finished initial NF config loading system

* Modified config library to accept file name for NF-specific args

* Fixed Makefile and NF args not being loaded from config file

* Previous merge conflict resolution broke Makefiles. This resolves that

* Reverted config API back and fixed retval in nflib

* Removed new code from speed tester

* Fixed function protoype

* Added new functions for requested config settings and removed commented code

* Renamed config file and fixed crashing problem

* Fixed check for setting instance id

* Renamed config file

* Style changes

* Added go script support for launching

* Added go script support for basic monitor and speed tester

* Updated go scripts and READMEs for first half of NFs

* Finished go scripts and documentation for second half of NFs and docs folder

* Updated NF_dev docs to include sample JSON file

* Made requested changes to Neel's comments

* Replaced strings with macros and changed error messages

* Adde call to cJSON_Delete(), should fix memory leak

* Added ability to replace config settings with command line options

* Fixed bug with arg replacement, style changes are in progress

* Added additional comments and removed unnecessary API functions

* Fixed go scripts to support command-line replacement

* Updated config documentation

* Updated description of file

* Fixed NF_dev typos

* Moved example_config to outer examples folder and deleted all others

* Updated all READMEs to include more accurate config section

* Added info about launching NFs with config files

* Added info to releases.md

Author: AaronCoplan

docs/Examples.md

@@ -1,6 +1,20 @@
 openNetVM Examples
 ==
 
+NF Config Files
+--
+Due to a feature in NFLib, all network functions support launching from a JSON config file that
+contains ONVM and DPDK arguments. An example of this can be seen
+[here](../examples/example_config.json). In addition, the values
+specified in the config file can be overwritten by passing them at the
+command line. The general structure for launching an NF from a config file is
+`./go -F <CONFIG_FILE.json> <DPDK ARGS> -- <ONVM ARGS> -- <NF ARGS>`.
+Any args specified in `<DPDK args>` or `<ONVM ARGS>` will replace the
+corresponding args in the config file. **An important note:** If no DPDK
+or ONVM args are passed, **but** NF args are required, the `-- --` is
+still required. For documentation on developing with config files, see
+[NF_Dev](NF_Dev.md)
+
 Linear NF Chain
 --
 In this example, we will be setting up a chain of NFs.  The length of the chain is determined by our system's CPU architecture.  Some of the commands used in this example are specific to our system; in the cases where we refer to core lists or number of NFs, please run the [Core Helper Script][cores] to get your numbers.
@@ -102,7 +116,16 @@ In this example, we can set up a circular chain of NFs.  Here, traffic does not
     - Second, start up 1 speed_tester NF and have it forward to service ID 2.
       - `# ./examples/speed_tester/go.sh 14 1 2 -c 16000`
   4. We now have a speed_tester sending packets to service ID 2 who then forwards packets back to service ID 1, the speed_tester.  This is a circular chain of NFs.
-  
+
+
+NF Config Files
+--
+All NFs support launching from a JSON config file. By specifying `-F`
+and then a JSON file in either `go.sh` or the NF binary file directly,
+the NF will pull all ONVM and DPDK settings from the file instead of the
+command line. See the `example_config.json` file in each NF directory
+for an example on how to structure the file and all options that can be
+set.
 
 
 [cores]: ../scripts/corehelper.py

docs/NF_Dev.md

@@ -52,13 +52,48 @@ The openNetVM Packet Helper Library provides an abstraction to support developme
   - Print the whole packet or individual headers of the packet.  These functions can be found [here][onvm_pkt_helper.h:L86].
 
 
+Config File Library
+--
+
+The openNetVM Config File Library provides an abstraction that allows
+NFs to load values from a JSON config file. While NFLib automatically
+loads all DPDK and ONVM arguments when `-F` is passed, a developer can
+add config support directly within the NF to support passing additional
+values.
+
+- NOTE: unless otherwise specified, all DPDK and ONVM arguments are **required**
+- `onvm_config_parse_file(const char* filename)`: Load a JSON config file, and return a pointer to the cJSON struct.
+- This is utilized to launch NFs using values specified in a config
+  file. 
+  `onvm_config_parse_file` can be found [here][onvm_config_common.h:L51]
+- Additional config options can be loaded from within the NF, using cJSON. For further reference on how to access the values from the cJSON object, see the [cJSON docs](https://github.com/DaveGamble/cJSON)
+
+### Sample Config File
+```
+{
+  "dpdk": {
+    "corelist": [STRING: corelist],
+    "memory_channels": [INT: number of memory channels],
+    "portmask": [INT: portmask]
+  },
+
+  "onvm": {
+    "output": [STRING: output loc, either stdout or web],
+    "serviceid": [INT: service ID for NF],
+    "instanceid": [OPTIONAL, INT: this optional arg sets the instance ID of the NF]
+  }
+}
+```
+
 [onvm_mgr]: ../onvm/onvm_mgr
 [onvm_nflib]: ../onvm/onvm_nflib
 [onvm_nflib.h]: ../onvm/onvm_nflib/onvm_nflib.h
 [onvm_pkt_helper.h:L56]: ../onvm/onvm_nflib/onvm_pkt_helper.h#L56
 [onvm_pkt_helper.h:L59]: ../onvm/onvm_nflib/onvm_pkt_helper.h#L59
 [onvm_pkt_helper.h:L74]: ../onvm/onvm_nflib/onvm_pkt_helper.h#L74
 [onvm_pkt_helper.h:L86]: ../onvm/onvm_nflib/onvm_pkt_helper.h#L86
+[onvm_config_common.h:L51]: ../onvm/onvm_nflib/onvm_config_common.h#L51
+[onvm_config_common.h:L108]: ../onvm/onvm_nflib/onvm_config_common.h#L108
 [onvm_common.h:L51]: ../onvm/onvm_nflib/onvm_common.h#L51
 [onvm_common.h:L55]: ../onvm/onvm_nflib/onvm_common.h#L55
 [forward]: ../examples/simple_forward/forward.c#L82

docs/Releases.md

@@ -37,8 +37,8 @@ The prior code relied on global data structures that do not work in a multi-thre
 `int onvm_nflib_return_pkt(struct onvm_nf_info *nf_info, struct rte_mbuf* pkt)`
 - `int pkt_handler_func(struct rte_mbuf* pkt, struct onvm_pkt_meta* action)` -> 
 `int pkt_handler_func(struct rte_mbuf *pkt, struct onvm_pkt_meta *meta, __attribute__ ((unused)) struct onvm_nf_info *nf_info)`
-- `int callback_handler_func(void)` -> `int callback_handler_func(__attribute__ ((unused)) struct onvm_nf_info *nf_info)`   
-  
+- `int callback_handler_func(void)` -> `int callback_handler_func(__attribute__ ((unused)) struct onvm_nf_info *nf_info)`
+
 **API Additions:**
  - `int onvm_nflib_scale(struct onvm_nf_scale_info *scale_info)` launches another NF based on the provided config
  - `struct onvm_nf_scale_info * onvm_nflib_get_empty_scaling_config(struct onvm_nf_info *parent_info)` for getting a basic empty scaling config
@@ -53,6 +53,19 @@ The console stats display has been improved to aggregate stats when running mult
 - For verbose mode run the manager with `-v` flag  
 - For raw stats dump use the `-vv` flag  
 
+### Config File Support:
+ONVM now supports JSON config files, which can be loaded through the API provided in `onvm_config_common.h`. This allows various settings of either the ONVM manager or NFs to be set in a JSON config file and loaded into code, as opposed to needing to be passed in via the command line.
+
+**Usage:**
+ - All example NFs now support passing DPDK and ONVM arguments in a config file by using the `-F config.json` flag when running an NF executable or a `go.sh` script.  See `docs/examples.md` for more details.
+
+**API Changes:**
+- `nflib.c` was not changed from an NF-developer standpoint, but it was modified to include a check for the `-F` flag, which indicates that a config file should be read to launch an NF.
+
+**API Additions:**
+- `cJSON* onvm_config_parse_file(const char* filename)` - Reads a JSON config and stores the contents in a cJSON struct. For further reference on cJSON, see its [documentation](https://github.com/DaveGamble/cJSON).
+- `int onvm_config_create_nf_arg_list(cJSON* config, int* argc, char** argv[])`: Given a cJSON struct and pointers to the original command line arguments, generate a new `argc` and `argv` using the config file values.
+
 ## v18.05 (5/31/18): Bug Fixes, Latency Measurements, and Docker Image
 This release adds a feature to the Speed Tester example NF to support latency measurements by using the `-l` flag. Latency is calculated by writing a timestamp into the packet body and comparing this value when the packet is returned to the Speed Tester NF. A sample use case is to run 3 speed tester NFs configured to send in a chain, with the last NF sending back to the first. The first NF can use the `-l` flag to measure latency for this chain. Note that only one NF in a chain should be using the flag since otherwise timestamp information written to the packet will conflict. 
 

examples/aes_decrypt/Makefile

@@ -56,7 +56,9 @@ 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

examples/aes_decrypt/README.md

@@ -34,3 +34,11 @@ Example
 ./examples/aes_encrypt/go.sh 5 1 2
 ./examples/aes_decrypt/go.sh 6 2 3
 ./examples/bridge/go.sh 7 3
+
+
+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/aes_decrypt/go.sh

@@ -2,14 +2,35 @@
 
 function usage {
         echo "$0 CPU-LIST SERVICE-ID DST [-p PRINT] [-n NF-ID]"
+        echo "$0 -F config.json [remaining NF args]"
+        echo ""
         echo "$0 3 0 1 --> core 3, Service ID 0, and forwards to service 1"
+        echo "$0 -F example_config.json -- -- -d 1 --> loads settings from example_config.json and forwards to Service ID 1"
         echo "$0 3,7,9 1 2 --> cores 3,7, and 9 with Service ID 1, and forwards to service id 2"
         echo "$0 -p 1000 -n 6 3,7,9 1 2 --> cores 3,7, and 9 with Service ID 1, Print Rate of 1000, instance ID 6, and forwards to service id 2"
         exit 1
 }
 
 SCRIPT=$(readlink -f "$0");
 SCRIPTPATH=$(dirname "$SCRIPT");
+
+if [ -z $1 ]
+then
+  usage
+fi
+
+if [ $1 = "-F" ]
+then
+  config=$2
+  shift 2
+  echo $config
+  echo "$@"
+  exec sudo $SCRIPTPATH/build/app/aesdecrypt -F $config "$@"
+elif [ $1 = "-F" ]
+then
+  usage
+fi
+
 cpu=$1
 service=$2
 dst=$3

examples/aes_encrypt/Makefile

@@ -56,7 +56,9 @@ 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

examples/aes_encrypt/README.md

@@ -21,6 +21,10 @@ cd aes_encrypt
 
 OR
 
+./go -F CONFIG_FILE -- -- -d DST [-p PRINT_DELAY]
+
+OR
+
 sudo ./build/aesencrypt -l CORELIST -n 3 --proc-type=secondary -- -r SERVICE_ID -- -d DST [-p PRINT_DELAY]
 ```
 
@@ -34,3 +38,10 @@ Example
 ./examples/aes_encrypt/go.sh 5 1 2
 ./examples/aes_decrypt/go.sh 6 2 3
 ./examples/bridge/go.sh 7 3
+
+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/aes_encrypt/go.sh

@@ -2,14 +2,35 @@
 
 function usage {
         echo "$0 CPU-LIST SERVICE-ID DST [-p PRINT] [-n NF-ID]"
+        echo "$0 -F CONFIG [remaining NF args]"
+        echo ""
         echo "$0 3 0 1 --> core 3, Service ID 0, and forwards to service 1"
+        echo "$0 -F example_config.json -- -- -d 1 --> loads settings from example_config.json, forwards to service ID 1"
         echo "$0 3,7,9 1 2 --> cores 3,7, and 9 with Service ID 1, and forwards to service id 2"
         echo "$0 -p 1000 -n 6 3,7,9 1 2 --> cores 3,7, and 9 with Service ID 1, Print Rate of 1000, instance ID 6, and forwards to service id 2"
         exit 1
 }
 
 SCRIPT=$(readlink -f "$0");
 SCRIPTPATH=$(dirname "$SCRIPT");
+
+if [ -z $1 ]
+then
+  usage
+fi
+
+if [ $1 = "-F" ]
+then
+  config=$2
+  shift 2
+  echo $config
+  echo "$@"
+  exec sudo $SCRIPTPATH/build/app/aesencrypt -F $config "$@"
+elif [ $1 = "-F" ]
+then
+  usage
+fi
+
 cpu=$1
 service=$2
 dst=$3
@@ -18,7 +39,7 @@ shift 3
 
 if [ -z $dst ]
 then
-	usage
+  usage
 fi
 
 while getopts ":p:n:" opt; do

examples/arp_response/Makefile

@@ -55,6 +55,8 @@ 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
 
 include $(RTE_SDK)/mk/rte.extapp.mk

examples/arp_response/README.md

@@ -11,6 +11,10 @@ print]
 
 OR
 
+./go -F CONFIG_FILE -- -- -d DESTINATION_ID -s SOURCE_IP_LIST [-p enable print]
+
+OR
+
 sudo ./build/monitor -l CORELIST -n NUM_MEMORY_CHANNELS --proc-type=secondary -- -r SERVICE_ID -- -d DESTINATION_ID -s SOURCE_IP_LIST [-p ENABLE PRINT]
 ```
 
@@ -19,3 +23,10 @@ App Specific Arguments
   - `-d <destination_id>`: the NF will send non-ARP packets to the NF at this service ID, e.g. `-d 2` sends packets to service ID 2
   - `-s <source_ip_list>`: the NF will map each comma separated IP (no spaces) to the corresponding port. Example: `-s 10.0.0.31,11.0.0.31` maps port 0 to 10.0.0.31, and port 1 to 11.0.0.31. If 0.0.0.0 is inputted, the IP will be 0. If too few IPs are inputted, the remaining ports will be ignored.
   - `-p`: Enables printing of log information
+
+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/arp_response/go.sh

@@ -2,12 +2,31 @@
 
 function usage {
         echo "$0 CPU-LIST SERVICE-ID DST-SERVICE-ID -s SOURCE-IP"
+        echo "$0 -F CONFIG-FILE -- -- -d DST -s SOURCE-IP"
+        echo ""
         echo "$0 4 1 2 -s 10.0.0.31,11.0.0.31 --> core 4, Service ID 1, Destination ID 2, Port 0: 10.0.0.31, Port 1: 11.0.0.31"
+        echo "$0 -F example_config.json 1 -s 10.0.0.31,11.0.0.31 --> loads settings from example_config.json, destination ID 1, Port 0: 10.0.0.31, Port 1: 11.0.0.31"
         exit 1
 }
 
 SCRIPT=$(readlink -f "$0")
 SCRIPTPATH=$(dirname "$SCRIPT")
+
+if [ -z $1 ]
+then
+  usage
+fi
+
+if [ $1 = "-F" ]
+then
+  config=$2
+  shift 2
+  exec sudo $SCRIPTPATH/build/app/arp_response -F $config "$@"
+elif [ $1 = "-F" ]
+then
+  usage
+fi
+
 cpu=$1
 service=$2
 dst=$3

examples/basic_monitor/Makefile

@@ -52,9 +52,11 @@ SRCS-y := monitor.c
 # OpenNetVM path
 ONVM= $(SRCDIR)/../../onvm
 
-CFLAGS += $(WERROR_FLAGS) -O3
+CFLAGS += $(WERROR_FLAGS) -O3 -g
 
 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
 
 include $(RTE_SDK)/mk/rte.extapp.mk

examples/basic_monitor/README.md

@@ -12,9 +12,20 @@ cd basic_monitor
 
 OR
 
+./go.sh -F CONFIG_FILE -- -- [-p PRINT_DELAY]
+
+OR
+
 sudo ./build/monitor -l CORELIST -n NUM_MEMORY_CHANNELS --proc-type=secondary -- -r SERVICE_ID -- [-p PRINT_DELAY]
 ```
 
 App Specific Arguments
 --
   - `-p <print_delay>`: number of packets between each print, e.g. `-p 1` prints every packets.
+
+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/basic_monitor/go.sh

@@ -2,14 +2,30 @@
 
 function usage {
         echo "$0 CPU-LIST SERVICE-ID [-p PRINT] [-n NF-ID]"
+        echo "$0 -F config.json -p 1"
+        echo ""
         echo "$0 3 0 --> core 3, Service ID 0"
         echo "$0 3,7,9 1 --> cores 3,7, and 9 with Service ID 1"
+        echo "$0 -F config.json -p 2 --> loads values from config.json and print rate of 2"
         echo "$0 -p 1000 -n 6 3,7,9 1 --> cores 3,7, and 9 with Service ID 1 and Print Rate of 1000 and instance ID 6"
         exit 1
 }
 
 SCRIPT=$(readlink -f "$0")
 SCRIPTPATH=$(dirname "$SCRIPT")
+
+if [ -z $1 ]
+then
+  usage
+fi
+
+if [ $1 = "-F" ]
+then
+  config=$2
+  shift 2
+  exec sudo $SCRIPTPATH/build/app/monitor -F $config "$@"
+fi
+
 cpu=$1
 service=$2
 

examples/basic_monitor/monitor.c

@@ -177,11 +177,11 @@ packet_handler(struct rte_mbuf *pkt, struct onvm_pkt_meta *meta, __attribute__((
 
 int main(int argc, char *argv[]) {
         int arg_offset;
-
         const char *progname = argv[0];
 
         if ((arg_offset = onvm_nflib_init(argc, argv, NF_TAG, &nf_info)) < 0)
                 return -1;
+
         argc -= arg_offset;
         argv += arg_offset;