Skip to content

Experimenting with Gatekeeper

Jump to bottom
Cody Doucette edited this page Jan 14, 2019 · 29 revisions

This page describes how to test Gatekeeper and experiment with its functionality.

Table of Contents

Setting Up a Gatekeeper Environment

There are multiple options for setting up Gatekeeper:

Once the environment is setup, follow the instructions in the README to compile, configure, and run Gatekeeper.

Generating Packets on DPDK Interfaces

This section describes how to install and use the DPDK pktgen program to generate packets on the XIA server.

Server Physical Setup

The XIA server has four DPDK-enabled ports that can be used to send and receive packets. The diagram below shows the four ports (along with their PCI identifiers): 

    +-----------------------------------------+
    |  -----               -----              |
    |  | o | A (83:00.0)   | o | B (83:00.1)  |
    |  --|--               --|--              |
    |    |                   |                |
    |  --|--               --|--              |
    |  | o | C (85:00.0)   | o | D (85:00.1)  |
    |  -----               -----              |
    +-----------------------------------------+

Note that ports A and C are connected, and ports B and D are connected. Besides, the MAC addresses of the four ports are A(e8:ea:6a:06:1f:7c), B(e8:ea:6a:06:1f:7d), C(e8:ea:6a:06:21:b2), D(e8:ea:6a:06:21:b3) respectively. The port MAC addresses may be used for generating specific packets in the following sections.

When you run multiple DPDK applications at the same time (such as two instances of pktgen, or pktgen and another DPDK application, you need to blacklist the PCI devices, or ports in this case, that you don't want to use. Depending on how you blacklist the devices, the port numbers that are assigned by DPDK will change.

For example, if you blacklist ports A, B, and C in one instance of pktgen, then port D is known as port 0 in that instance. If, at the same time, you blacklist ports A, C, and D in another instance of pktgen, then in that instance port B is known as port 0. To avoid ambiguity, in this document we will refer to the ports using these letter designations (A, B, C, D) instead of by numbers.

Setting up pktgen

First, obtain the pktgen source code and build it: 

    $ git clone http://dpdk.org/git/apps/pktgen-dpdk
    $ cd pktgen-dpdk
    $ make

Once it compiles, do a setup step: 

    $ sudo -E ./setup.sh

The application should be ready to run at this point, but you may also encounter the need to perform the following step (still in the pktgen-dpdk directory): 

    $ cp Pktgen.lua app/app/x86_64-native-linuxapp-gcc/

Running Two Instances of pktgen

This demonstration will show how we can generate packets on port A and send them to port C. To begin, open two terminals.

In the first terminal, go to the dpdk-pktgen directory and run: 

    $ cd app/app/x86_64-native-linuxapp-gcc/
    $ sudo ./pktgen -l 0-2 --socket-mem 256 --file-prefix pg1 -b 83:00.1 -b 85:00.0 -b 85:00.1 -- -T -P -m "[1:2].0"

The "-c 7" option specifies which lcores are available for use, which is lcores 0, 1, and 2. The "-m [1:2].0" part specifies that lcores 1 and 2 will handle rx/tx on port 0, and lcore 0 is automatically assigned to the pktgen program for displaying statistics.

The "--socket-mem 256" option puts a limit on the memory used, which is often needed when multiple DPDK applications are run at the same time. The "--file-prefix pg1" option specifies a special file prefix to use for this DPDK application's meta information, which again is needed if there are multiple DPDK applications running (which we will have in the next part).

The "-b" options blacklist different ports -- in other words, excludes those ports from being used in the application. In this command, we only want to use port A (at PCI location 83:00.0), so we blacklist the other three ports: B (83:00.1), C (85:00.0), and D (85:00.1).

The "-T" option gives the display statistics some color and the "-P" makes all ports run in promiscuous mode.

In the second terminal, run the same command, but with different lcores and blacklisted ports: 

    $ cd app/app/x86_64-native-linuxapp-gcc/
    $ sudo ./pktgen -c 70 --socket-mem 256 --file-prefix pg2 -b 83:00.0 -b 83:00.1 -b 85:00.1 -- -T -P -m "[5:6].0"

This does the same as the first command, but instead allows lcores 4, 5, and 6 to be used, uses a different file prefix, and blacklists all ports except for port C.

More information about the command-line parameters is here.

Once the applications are running, go to the terminal running pktgen on port A. You can start packets flowing using: 

    $ Pktgen> start 0

Remember that port numbering always starts from 0 within an application, so since we blacklisted all other ports, port 0 means port A.

When you do this, you should see the second terminal's statistics being updated. You could also start packets flowing on the second terminal (port C) and see the packets being received on port A -- on the second terminal, port C will also be called port 0, since that is the only active port in that application.

You can stop packets flowing with: 

    $ Pktgen> stop 0

And quit with: 

    $ Pktgen> quit

Debugging Gatekeeper

Since Gatekeeper is compiled with the -g option, gdb can be directly used with Gatekeeper. After it is compiled, you can run: 

    $ sudo gdb ./build/gatekeeper

From there, you can use gdb as described in its documentation.

Configuring Gatekeeper

Static Configuration

The network and individual blocks are configured using the configuration files in the lua directory:

Command Line Parameters

EAL Configuration

Since Gatekeeper is a DPDK application, it can be given EAL parameters from the command line to configure various device, debugging, and memory options.

There are two EAL parameters that may be especially useful when running Gatekeeper:

Global Log Level

--log-level <val>

The global log level is the baseline log level for all logs in Gatekeeper (see Network for more information). The global log level defined in the command line is only used for the early Gatekeeper setup, and is overwritten by the global log level defined in lua/net.lua.

Gatekeeper Log Level

--log-level gatekeeper:<val>

The Gatekeeper log level is used for all logs that are not directly related to the individual blocks (see Network for more information). The Gatekeeper log level defined in the command line is only used for the early Gatekeeper setup, and is overwritten by the Gatekeeper log level defined in lua/net.lua.

Dynamic Configuration

At runtime, Gatekeeper can be dynamically configured using the Dynamic Config. This allows the user to add, delete, and show routes, neighbors, policies, etc.

Testing Gatekeeper DoS Defense Algorithms

This section describes how to test the functional blocks that compose Gatekeeper's main denial of service defense capabilities. These include the GK (Gatekeeper), GT (Grantor), GT-GK Unit (GGU), and SOL (Solicitor) blocks. Once you successfully configured Gatekeeper, and compiled it. Then, we can generate packets using pktgen to test each functional block.

First, open two terminals. In one terminal (T1), runs the following command to open the Gatekeeper directory: 

 $ cd gatekeeper

On the other terminal (T2), runs the following command to open the pktgen directory: 

 $ cd pktgen-dpdk/app/app/x86_64-native-linuxapp-gcc/

Testing GK block

To test the GK bock, one needs to specify the packets' IP destinations, which will be used to lookup the policies in LPM table. Note that the policies maintained by the LPM table can be dynamically configured using Lua scripts. For simplicity, we don't configure any policy here. On terminal T1, we can start Gatekeeper program on port C as the front port and port D as the back port by running the command: 

 $ sudo ./build/gatekeeper -c 0xff -b 83:00.0 -b 83:00.1 --socket-mem 256

Since we blacklisted ports A and B, we need to modify the lua/if_map.lua to filter the interface mapping for ports A and B: 

 return {
        ["ens2f0"] = "0000:04:00.0",
        ["ens2f1"] = "0000:04:00.1",
        ["ens2f2"] = "0000:04:00.2",
        ["ens2f3"] = "0000:04:00.3",
 --     ["enp131s0f0"] = "0000:83:00.0",
 --     ["enp131s0f1"] = "0000:83:00.1",
        ["enp133s0f1"] = "0000:85:00.1",
        ["enp133s0f0"] = "0000:85:00.0",
 }

Note that, if you are using different ports names on your machine (e.g., virtual machine), you need to manually adjust the network ports (i.e., front_ports and back_ports) in lua/net.lua.

On terminal T2, we can run the pktgen program to generate test packets on port A using the following command: 

 $ sudo ./pktgen -c 0xf00 --socket-mem 256 --file-prefix pg1 -b 83:00.1 -b 85:00.0 -b 85:00.1 -- -T -P -m "[9:10].0"

To generate test packets, and send them to port C (i.e., the front port), one can use the following command: 

 $ Pktgen> set 0 count 1
 $ Pktgen> set 0 src ip 10.0.0.2/24
 $ Pktgen> set 0 dst ip 10.0.0.1
 $ Pktgen> set 0 dst mac e8:ea:6a:06:21:b2
 $ Pktgen> start 0

Note that, this packet will be dropped by GK block. One can construct more complex test packets with more knowledge about the GK block. However, the commands are similar but with different parameters for the packets.

Testing GGU block

The procedure is similar to the one for testing the GK block. However, one needs to send packets to the back port (i.e., port D), since these test packets are generated from GT block running on a Grantor server inside ISP. Specifically, one can use the following commands: 

 $ sudo ./pktgen -c 0xf00 --socket-mem 256 --file-prefix pg1 -b 83:00.0 -b 85:00.0 -b 85:00.1 -- -T -P -m "[9:10].0"
 $ Pktgen> set 0 count 1
 $ Pktgen> proto udp 0
 $ Pktgen> set 0 dport 0xB0B0
 $ Pktgen> set 0 sport 0xA0A0
 $ Pktgen> set 0 src ip 66.9.149.187/32
 $ Pktgen> set 0 dst ip 10.0.1.1
 $ Pktgen> set 0 dst mac e8:ea:6a:06:21:b3
 $ Pktgen> start 0

Note that, 10.0.1.1 is the configured IP address of the back port, specified in lua/net.lua. 0xB0B0 and 0xA0A0 are the destination and source ports respectively, which are configured in lua/gt.lua. This UDP packet is just for illustration and doesn't carry any GGU policy decisions.

Testing Gatekeeper Configuration and Setup

This section describes how to test the functional blocks that enable Gatekeeper to be setup and function in a network. These include the CPS (Control Plane Services) and LLS (Link Layer Services) blocks.

Clone this wiki locally