From ce1429f7c9ccaf93d15cbad1b6a7a4dd0976f1a2 Mon Sep 17 00:00:00 2001 From: Alberto Compagno Date: Wed, 6 Mar 2019 16:04:43 +0100 Subject: [HICN-93] Added documentation in the README.md about cli commands, configuration file and binary api. Added simple example with two vpp forwarders, client and server ping application Change-Id: I170500cd23c9a08b18ac902307a60e7558eb4ea0 Signed-off-by: Alberto Compagno --- hicn-plugin/README.md | 197 ++++++++++++++++++++++++++++++++- hicn-plugin/src/cli.c | 10 +- hicn-plugin/src/faces/ip/face_ip_cli.c | 8 +- 3 files changed, 199 insertions(+), 16 deletions(-) diff --git a/hicn-plugin/README.md b/hicn-plugin/README.md index 0ac646eeb..e0e0580de 100644 --- a/hicn-plugin/README.md +++ b/hicn-plugin/README.md @@ -76,7 +76,7 @@ Hardware support: - [DPDK](http://DPDK.org/) compatible nic -### Getting started ### +## Getting started ## In order to start, the hICN plugin requires a running instance of VPP The steps required to successfully start hICN are: @@ -88,7 +88,7 @@ The steps required to successfully start hICN are: Detailed information for configuring VPP can be found at [https://wiki.fd.io/view/VPP](https://wiki.fd.io/view/VPP). -##### Setup the host for VPP ##### +### Setup the host for VPP ### Hugepages must be enabled in the system @@ -110,7 +110,7 @@ If the DPDK interface we want to assign to VPP is up, we must bring it down $ sudo ifconfig down ``` -##### Configure VPP ##### +### Configure VPP ### The file /etc/VPP/startup.conf contains a set of parameters to setup VPP at startup. The following example sets up VPP to use a DPDK interfaces: @@ -135,7 +135,7 @@ dpdk { ``` Where `0000:08:00.0` must be replaced with the actual PCI address of the DPDK interface -##### Start VPP ##### +### Start VPP ### VPP can be started as a process or a service: @@ -148,6 +148,195 @@ $ sudo vpp -c /etc/vpp/startup.conf ``` +### Configure hICN plugin ### +The hICN plugin can be configured either using the VPP command-line interface (CLI), through a configuration file or through the VPP binary api + +#### hICN plugin CLI #### + +The CLI commands for the hICN plugin start all with the hicn keyword. To see the full list of command available type: + +``` shell +$ sudo vppctl +vpp# hicn ? +``` + +`hicn control param`: configures the internal parameter of the hICN plugin. This command must be run before hicn control start. + +``` +hicn control param { pit { size | { dfltlife | minlife | maxlife } } | cs {size | app } } + :set the maximum number of entry in the PIT or CS. Default for PIT is 131072, for CS is 4096. + :set the default, maximum or minimum lifetime of pit entries. Default value 2s (default), 0.2s (minumum), 20s (maximum) + :set the portion of CS to reserve to application running locally on the forwarder. Default is 30% of the cs size. +``` + +`hicn control start`: starts the hICN plugin in VPP. + +`hicn control stop` : stops the hICN plugin in VPP. Currently not supported. + +`hicn face app` : manipulates producer and consumer application faces in the forwarder. + +``` +hicn face app {add intfc {prod prefix cs_size } {cons}} | {del } + :software interface existing in vpp on top of which to create an application face + :prefix to bound to the producer application face. Only content matching the prefix will be allowed through such face. + :content store size associated to the producer face. + :id of the face to remove + +``` + +`hicn face ip`: manipulates ip application faces in the forwarder. + +``` +hicn face ip {add local remote intfc } | {del id } + :the IPv4 or IPv6 local IP address to bind to + :the IPv4 or IPv6 address of the remote system + :software interface on thop of which we create the face + :id of the face to remove +``` + + +`hicn face show`: list the available faces in the forwarder. + +``` +hicn face show [| type ] + :face id of which we want to display the informations + :shows all the ip or udp faces available +``` + +`hicn face udp`: manipulates udp application faces in the forwarder. + +``` +hicn face udp {add src_addr port dst_addr port } intfc | {del id } + :the IPv4 or IPv6 local IP address to bind to + :the local UDP port + :the IPv4 or IPv6 address of the remote system + :the remote UDP port + :software interface on thop of which we create the face + :id of the face to remove + +``` + +`hicn fib`: manipulates hicn fib entries. + +``` +hicn fib {{add | delete } prefix face } | set strategy prefix + :prefix to add to the FIB + :face id to add as nexto hop in the FIB entry + :set a strategy for the corresponding prefix +``` + +`hicn mapme`: enable and disable mapme. + +``` +hicn mapme {enable|disable|set } +``` + + +`hicn pgen client`: set an vpp forwarder as an hicn packet generator client + +``` +hicn pgen client fwd src n_ifaces name lifetime intfc max_seq n_flows + :set if the underlying forwarder is configured as ip or hicn + :source address to use in the interests, i.e., the locator for routing the data packet back + :set the number of ifaces (consumer faces) to emulate. If more than one, each interest is sent times, each of it with a different source address calculated from + :prefix to use to generate hICN names + :lifetime of the interests + :interface through which the forwarder receives data + :max the sequence number to use in the interest. Cycling between 0 and this value + :emulate multiple flows downloaded in parallel +``` + +`hicn pgen server`: set an vpp forwarder as an hicn packet generator client + +``` +hicn pgen server fwd name intfc size + :set if the underlying forwarder is configured as ip or hicn + :prefix to use to reply to interest + :interface through which the forwarder receives interest + :size of the data payload +``` + +`hicn punting`: manipulates punting rules + +``` +hicn punting {add|delete} prefix intfc {type ip | type src_port dst_port } + :prefix to punt to the hICN plugin + :software interface where to apply the punting + :creates a punting rule for hICN packet encapsulated into a ip4/6|udp tunnel or for regular hicn packet + :source port of the udp4/6 tunnel + :destination port of the udp4/6 tunnel +``` + +`hicn show`: show forwarder information. +``` +hicn show [detail] [strategies] + :shows additional details as pit,cs entries allocation/deallocation + :shows only the available strategies int he forwarder +``` + +`hicn strategy mw set`: set the weight for a face. + +``` +hicn strategy mw set prefix face weight + :prefix to which the strategy applies + :id of the face to set the weight + :weight +``` + +#### hICN plugin configuration file #### + +A configuration can be use to setup the hicn plugin when vpp starts. The configuration file is made of a list of CLI commands. In order to set vpp to read the configuration file, the file /etc/vpp/startup.conf needs to be modified as follows: + +``` +unix { + nodaemon + log /tmp/vpp.log + full-coredump + startup-config +} +``` +#### hICN plugin binary api #### + +The binary api, or the vapi, can be used as well to configure the hicn plugin. For each cli command there is a corresponding message in the binary api. The list of messages is available in the file hicn.api (located in hicn/hicn-plugin/src/) + +### Example: consumer and producer Ping ### + +In this example, we connect two vpp forwarders, A and B, each of them running the hicn plugin. On top of forwarder A we run the ping_client application, on top of forwarder B we run the ping_server application. Each application connects to the underlying forwarder through a memif-interface. The two forwarders are connected through a dpdk link. + +#### Forwarder A #### + +```shell +$ sudo vppctl +vpp# set interface ip address TenGigabitEtherneta/0/0 2001::2/64 +vpp# set interface state TenGigabitEtherneta/0/0 up +vpp# hicn control start +vpp# hicn face ip add local 2001::2 remote 2001::3 intfc TenGigabitEtherneta/0/0 +vpp# hicn fib add prefix b002::1/64 face 0 +vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/0 type ip +``` + +#### Forwarder B #### + +```shell +$ sudo vppctl +vpp# set interface ip address TenGigabitEtherneta/0/1 2001::3/64 +vpp# set interface state TenGigabitEtherneta/0/1 up +vpp# hicn control start +vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/1 type ip +``` + +Once the two forwarder are started, run the ping_server application on the host where the forwarder B is running + +```shell +$ sudo ping_server -n b002::1 +``` + +and the client on the host where forwarder B is running + +```shell +$ sudo ping_client -n b002::1 +``` + ## License ## This software is distributed under the following license: diff --git a/hicn-plugin/src/cli.c b/hicn-plugin/src/cli.c index b03d6a29c..12a65495a 100644 --- a/hicn-plugin/src/cli.c +++ b/hicn-plugin/src/cli.c @@ -1197,7 +1197,7 @@ VLIB_CLI_COMMAND(hicn_cli_node_ctl_command, static)= VLIB_CLI_COMMAND(hicn_cli_fib_set_command, static)= { .path = "hicn fib", - .short_help = "hicn fib {{add | delete } prefix face }" + .short_help = "hicn fib {{add | delete } prefix face }" " | set strategy prefix ", .function = hicn_cli_fib_set_command_fn, }; @@ -1207,7 +1207,7 @@ VLIB_CLI_COMMAND(hicn_cli_show_command, static)= { .path = "hicn show", .short_help = "hicn show " - "[detail] [internal]" + "[internal]" "[strategies]", .function = hicn_cli_show_command_fn, }; @@ -1216,7 +1216,7 @@ VLIB_CLI_COMMAND(hicn_cli_show_command, static)= VLIB_CLI_COMMAND(hicn_cli_punting_command, static)= { .path = "hicn punting", - .short_help = "hicn punting {add|delete} prefix intfc {type ip | type src_port dst_port }", + .short_help = "hicn punting {add|delete} prefix intfc {type ip | type src_port dst_port }", .function = hicn_cli_punting_command_fn, }; @@ -1231,7 +1231,7 @@ VLIB_CLI_COMMAND(hicn_cli_mapme_command, static)= VLIB_CLI_COMMAND(hicn_cli_pgen_client_set_command, static)= { .path = "hicn pgen client", - .short_help = "hicn pgen client fwd src n_ifaces name lifetime intfc max_seq n_flows ", + .short_help = "hicn pgen client fwd src n_ifaces name lifetime intfc max_seq n_flows ", .long_help = "Run hicn in packet-gen client mode\n", .function = hicn_cli_pgen_client_set_command_fn, }; @@ -1240,7 +1240,7 @@ VLIB_CLI_COMMAND(hicn_cli_pgen_client_set_command, static)= VLIB_CLI_COMMAND(hicn_cli_pgen_server_set_command, static)= { .path = "hicn pgen server", - .short_help = "hicn pgen server fwd name intfc size ", + .short_help = "hicn pgen server fwd name intfc size ", .long_help = "Run hicn in packet-gen server mode\n", .function = hicn_cli_pgen_server_set_command_fn, }; diff --git a/hicn-plugin/src/faces/ip/face_ip_cli.c b/hicn-plugin/src/faces/ip/face_ip_cli.c index 1558c82cb..534ae7f63 100644 --- a/hicn-plugin/src/faces/ip/face_ip_cli.c +++ b/hicn-plugin/src/faces/ip/face_ip_cli.c @@ -34,8 +34,6 @@ hicn_face_ip_cli_set_command_fn (vlib_main_t * vm, ip46_address_t local_addr; ip46_address_t remote_addr; hicn_face_id_t face_id = HICN_FACE_NULL; - int app_face = 0; - u32 cs_reserved = HICN_PARAM_FACE_DFT_CS_RESERVED; int ret = HICN_ERROR_NONE; int sw_if; int face_op = HICN_FACE_NONE; @@ -74,10 +72,6 @@ hicn_face_ip_cli_set_command_fn (vlib_main_t * vm, format_unformat_error, line_input); } } - else if (unformat (line_input, "app_face %d", &app_face)) - { - if (unformat (line_input, "cs_size %d", &cs_reserved)); - } else { return clib_error_return (0, "%s '%U'", @@ -144,7 +138,7 @@ hicn_face_ip_cli_set_command_fn (vlib_main_t * vm, VLIB_CLI_COMMAND (hicn_face_ip_cli_set_command, static) = { .path = "hicn face ip", - .short_help = "hicn face ip {add local remote intfc } {app_face <0/1>} {cs_size } | {del id }", + .short_help = "hicn face ip {add local remote intfc } | {del id }", .function = hicn_face_ip_cli_set_command_fn, }; /* *INDENT-ON* */ -- cgit 1.2.3-korg