summaryrefslogtreecommitdiffstats
path: root/hicn-plugin
diff options
context:
space:
mode:
authorAlberto Compagno <acompagn+fdio@cisco.com>2019-03-06 16:04:43 +0100
committerAlberto Compagno <acompagn+fdio@cisco.com>2019-03-06 17:18:30 +0100
commitce1429f7c9ccaf93d15cbad1b6a7a4dd0976f1a2 (patch)
tree8bdba2e1ad03b1efdfce7d01a2c7316d4286e400 /hicn-plugin
parentb980b4384d610e64e4c8bdd749a6e8fb0ebd5117 (diff)
[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 <acompagn+fdio@cisco.com>
Diffstat (limited to 'hicn-plugin')
-rw-r--r--hicn-plugin/README.md197
-rw-r--r--hicn-plugin/src/cli.c10
-rw-r--r--hicn-plugin/src/faces/ip/face_ip_cli.c8
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 <interface_name> 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 <entries> | { dfltlife | minlife | maxlife } <seconds> } | cs {size <entries> | app <portion to reserved to app>} }
+ <entries> :set the maximum number of entry in the PIT or CS. Default for PIT is 131072, for CS is 4096.
+ <seconds> :set the default, maximum or minimum lifetime of pit entries. Default value 2s (default), 0.2s (minumum), 20s (maximum)
+ <portion to reserved to app> :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 <sw_if> {prod prefix <hicn_prefix> cs_size <size_in_packets>} {cons}} | {del <face_id>}
+ <sw_if> :software interface existing in vpp on top of which to create an application face
+ <hicn_prefix> :prefix to bound to the producer application face. Only content matching the prefix will be allowed through such face.
+ <size_in_packets> :content store size associated to the producer face.
+ <face_id> :id of the face to remove
+
+```
+
+`hicn face ip`: manipulates ip application faces in the forwarder.
+
+```
+hicn face ip {add local <src_address> remote <dst_address> intfc <sw_if>} | {del id <face_id>}
+ <src_address> :the IPv4 or IPv6 local IP address to bind to
+ <dst_address> :the IPv4 or IPv6 address of the remote system
+ <sw_if> :software interface on thop of which we create the face
+ <face_id> :id of the face to remove
+```
+
+
+`hicn face show`: list the available faces in the forwarder.
+
+```
+hicn face show [<face_id>| type <ip/udp>]
+ <face_id> :face id of which we want to display the informations
+ <ip/udp> :shows all the ip or udp faces available
+```
+
+`hicn face udp`: manipulates udp application faces in the forwarder.
+
+```
+hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address> port <dst_port>} intfc <sw_if> | {del id <face_id>}
+ <src_address> :the IPv4 or IPv6 local IP address to bind to
+ <src_port> :the local UDP port
+ <dst_address> :the IPv4 or IPv6 address of the remote system
+ <dst_port> :the remote UDP port
+ <sw_if> :software interface on thop of which we create the face
+ <face_id> :id of the face to remove
+
+```
+
+`hicn fib`: manipulates hicn fib entries.
+
+```
+hicn fib {{add | delete } prefix <prefix> face <face_id> } | set strategy <strategy_id> prefix <prefix>
+ <prefix> :prefix to add to the FIB
+ <face_id> :face id to add as nexto hop in the FIB entry
+ <strategy_id> :set a strategy for the corresponding prefix
+```
+
+`hicn mapme`: enable and disable mapme.
+
+```
+hicn mapme {enable|disable|set <param> <value>}
+```
+
+
+`hicn pgen client`: set an vpp forwarder as an hicn packet generator client
+
+```
+hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> lifetime <interest-lifetime> intfc <data in-interface> max_seq <max sequence number> n_flows <number of flows>
+ <ip|hicn> :set if the underlying forwarder is configured as ip or hicn
+ <src_addr> :source address to use in the interests, i.e., the locator for routing the data packet back
+ <n_ifaces> :set the number of ifaces (consumer faces) to emulate. If more than one, each interest is sent <n_ifaces> times, each of it with a different source address calculated from <src_addr>
+ <prefix> :prefix to use to generate hICN names
+ <interest-lifetime> :lifetime of the interests
+ <data in-interface> :interface through which the forwarder receives data
+ <max sequence number> :max the sequence number to use in the interest. Cycling between 0 and this value
+ <number of flows> :emulate multiple flows downloaded in parallel
+```
+
+`hicn pgen server`: set an vpp forwarder as an hicn packet generator client
+
+```
+hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size <payload_size>
+ <ip|hicn> :set if the underlying forwarder is configured as ip or hicn
+ <prefix> :prefix to use to reply to interest
+ <interest in-interface> :interface through which the forwarder receives interest
+ <payload_size> :size of the data payload
+```
+
+`hicn punting`: manipulates punting rules
+
+```
+hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|udp6> src_port <src_port> dst_port <dst_port>}
+ <prefix> :prefix to punt to the hICN plugin
+ <sw_if> :software interface where to apply the punting
+ <ip|udp4|udp6> :creates a punting rule for hICN packet encapsulated into a ip4/6|udp tunnel or for regular hicn packet
+ <src_port> :source port of the udp4/6 tunnel
+ <dst_port> :destination port of the udp4/6 tunnel
+```
+
+`hicn show`: show forwarder information.
+```
+hicn show [detail] [strategies]
+ <detail> :shows additional details as pit,cs entries allocation/deallocation
+ <strategies> :shows only the available strategies int he forwarder
+```
+
+`hicn strategy mw set`: set the weight for a face.
+
+```
+hicn strategy mw set prefix <prefix> face <face_id> weight <weight>
+ <prefix> :prefix to which the strategy applies
+ <face_id> :id of the face to set the weight
+ <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 <path to configuration file>
+}
+```
+#### 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 <prefix> face <faceid> }"
+ .short_help = "hicn fib {{add | delete } prefix <prefix> face <facei_d> }"
" | set strategy <strategy_id> prefix <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 <ip_address/mask> intfc <interface> {type ip | type <udp4|udp6> src_port <port> dst_port <port>}",
+ .short_help = "hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|udp6> src_port <port> dst_port <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 <ip|hicn> src <addr> n_ifaces <n_ifaces> name <addr/subnet> lifetime <interest-lifetime> intfc <data in-interface> max_seq <max sequence number> n_flows <number of flows>",
+ .short_help = "hicn pgen client fwd <ip|hicn> src <src_addr> n_ifaces <n_ifaces> name <prefix> lifetime <interest-lifetime> intfc <data in-interface> max_seq <max sequence number> n_flows <number of 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 <ip|hicn> name <addr/subnet> intfc <interest in-interface> size <payload_size>",
+ .short_help = "hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size <payload_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 <local_address> remote <remote_address> intfc <sw_if>} {app_face <0/1>} {cs_size <size_in_packets>} | {del id <face_id>}",
+ .short_help = "hicn face ip {add local <src_address> remote <dst_address> intfc <sw_if>} | {del id <face_id>}",
.function = hicn_face_ip_cli_set_command_fn,
};
/* *INDENT-ON* */