Skip to main content

Netmap Installation on Linux

Zenarmor (Sensei) uses the netmap framework to access raw Ethernet frames. To enjoy all of the filtering functionalities of the Zenarmor, you must have the netmap framework installed on your system. Latest FreeBSD-based systems come with already installed netmap for you and are ready to be installed the Zenarmor. However, on Linux, netmap is not included by default. If you are using a Linux-based firewall such as iptables, ipfw, firewalld, etc., you should set up netmap on your Linux system to get the benefit of all Zenarmor capabilities or even Suricata. Installing netmap to Linux operating systems may a little tricky. Therefore, we provide you the netmap installation steps in this netmap starting tutorial. You find information about the following topics in this netmap quick start guide:

  • What is netmap?
  • Advantages of using netmap
  • netmap supported drivers/hardware requirements for netmap on Linux
  • netmap installation instructions on Linux operating systems(Ubuntu, Debian, CentOS etc.)
  • using/loading netmap kernel modules on your Linux machine
  • testing netmap installation on Linux

What is Netmap and Why do you need it?#

Netmap is a DPDK-like kernel interface that Zenarmor uses to deploy between your Ethernet Adapter and Linux/BSD Networking Stack. This allows us to have a peek at packets and take actions before they even reach their destinations.

Netmap provides extremely fast and efficient packet I/O in kernel, userspace, and virtual machine platforms. It is capable of handling tens of millions of packets per second, matching the speed of 10G and 40G ports even with small frames.

Netmap is compatible with FreeBSD, Linux, and some versions of Windows. For FreeBSD and Linux, it is implemented as a single kernel module.

info

Netmap is already included and enabled by default in recent FreeBSD (>= 10.x), OPNsense(r) and pfSense® software software releases. However, if you want to run Zenarmor in Routed Mode (L3 Mode, Reporting and Blocking available) on supported Linux Distributions (Ubuntu 18.04 LTS & 20.04 LTS, Centos 7, & 8, Debian 10 and AlmaLinux 1) you must install Netmap by yourself. Also, if you have a Surricata, you should install netmap for a better performance of your IPS system.

Requirements for Installing Netmap on Linux#

Netmap natively supports the following devices on Linux:

  • virtio_net
  • vmxnet3
  • Intel e1000(1G)
  • Intel e1000e (1G)
  • Realtek 8169(1G)
  • Intel i40e
  • Intel igb(1G)
  • Intel ixgbe(10G)
  • Intel ixgbevf

Netmap natively supports the following devices on FreeBSD:

  • Intel ixgbe(10G)
  • Intel ixl(10/40G)
  • iflib(4)(providing igb(4) and em(4))
  • re(4)
  • vtnet(4)
  • cxgbe(4)

If netmap does not natively support your NICs, they may still be used in netmap mode through emulation. Although performance is inferior to native netmap mode, it is significantly better than various raw socket types (bpf, PF PACKET, and so on).

It should be observed that for slow devices (such as 1 Gbit/s and slower NICs, or several 10 Gbit/s NICs whose hardware is unable to sustain line rate), emulated and native mode throughput will most likely be similar or even the same.

Netmap Installation on Linux#

Netmap installation on a standard Linux distribution is straightforward. The instructions given below are followed and tested on Ubuntu TLS 20.04, kernel version 5.4.0-74 and Debian 10.9, kernel version 4.19.0-16-amd64. However, the practice is the same for other distributions.

You can build and install the netmap kernel module for linux by following the standard ./configure && make && sudo make install workflow. But you may need to prepare your system before installing the netmap.

warning

Privileged access to your Linux system as root or via the sudo command.

All below given commands to be executed with root privileges either directly as a root user or by use of sudo command

Netmap Pre-installations for Linux#

1. Update your local package index by running the following command:

Update your local package index
sudo apt-get update

2. Since you will need to compile the netmap source code, first you must ensure that you have compiling tools and prerequisite software installed. You may need to do the following:

Install compiling tools
sudo apt install build-essential

3. Install dependencies (Git version control systems)

Install Git
sudo apt-get install -y git

4. Kernel Headers contain the C header files for the Linux kernel, which provide the various function and structure definitions needed when compiling any code that interfaces with the kernel, such as kernel modules or device drivers. To install linux headers run the following command:

Install linux headers
sudo apt-get install -y linux-headers-$(uname -r)

Netmap Installing Steps for Linux#

Netmap installing process refers six basic steps. To install the Netmap, the required basic six steps are provided below:

1. Download netmap from the official GitHub repository:

Download netmap
git clone https://github.com/luigirizzo/netmap.git

This will create a local clone of the remote netmap repository.

2. Enter the netmap net directory:

cd netmap

3. Netmap is originally a BSD tool, and to install on Linux you must enter LINUX directory:

cd LINUX

4. Next you must configure netmap. In most cases, running the scripts as follows is sufficient:

./configure

Configure Options#

The configure script has many useful options that you may need. Some of the configure options are givien below:

  • You can see the full list of options by running:
Configure Options
./configure --help
  • To view the supported drivers:
Viewing supported drivers
./configure --show-drivers

At the time of writing(June, 2021), only the following drivers are supported:

mlx5, vmxnet3, i40e, ixgbevf, ixgbe, igb, e1000e, e1000, veth.c, forcedeth.c, virtio_net.c, r8169.c, stmmac

  • You may want to have the new netmap-enabled driver modules alongside the original ones:
./configure --driver-suffix=-netmap

The new drivers will be known as r8169-netmap, ixgbe-netmap, and so on.

  • The script will search your kernel sources for patchable drivers. To fully utilize netmap, we must use netmap-enabled drivers. Netmap will continue to work with standard drivers, and to avoid building netmap-enabled ones, run configure as follows:
./configure --no-drivers

This is convenient when we don't have supported drivers, or a netmap enabled driver is causing issues.

For more information about the configure options, please refer to official netmap instructions and readme documentation.

5. Netmap contains some sample applications, such as benchmarking tools. Once netmap is configured build kernel modules and sample applications by running:

Build kernel modules
make
Build applications
make apps

6. Install the new modules and applications as follows:

Install modules and apps
make install

Loading netmap in a Linux system#

After installing the netmap on your Linux, you should follow the following four steps to start using the netmap:

1. Unload any modules for the network cards you intend to use, for example.

Unload NIC modules
rmmod virtio_net.kormmod e1000.ko
caution

Be careful, removing the NIC modules will drop any connection on this interface.

2. Load netmap and device driver module, for example.

On Ubuntu TLS 20.04:

Load netmap & NIC modules
insmod /usr/lib/modules/5.4.114/extra/netmap.koinsmod /usr/lib/modules/5.4.114/extra/virtio_net.koinsmod /usr/lib/modules/5.4.0-74-generic/kernel/drivers/net/ethernet/intel/e1000/e1000.ko

On Debian 10.9:

Load netmap & NIC modules
insmod /usr/lib/modules/4.19.0-16-amd64/extra/netmap.koinsmod /usr/lib/modules/4.19.0-16-amd64/extra/virtio_net-netmap.koinsmod /usr/lib/modules/4.19.0-16-amd64/kernel/drivers/net/ethernet/intel/e1000/e1000.ko

3. Using the lsmod command, you can confirm that modules are loaded:

Listing loaded modules
lsmod
Sample lsmod output
Module Size Used by
virtio_net 45056 0
netmap 204800 1 virtio_net

4. Activate the network interface(s) by turn it/them up, for example:

(replace ens18 with the name of your interface)

Turn NIC UP
ifconfig ens18 up

Or

Turn NIC UP
ifup ens18

Testing Netmap and Expected Performance Results#

You can perform testing for the netmap using the provided pkt-gen application on your Linux.

info

pkt-gen is a raw packet sender/receiver which can do line rate on a 10G interface. It has a large number of options, but the simplest form is:

(replace ens18 with the name of your interface)

Testing netmap with pht-gen

pkt-gen -i ens18 -f tx -l 60 # send a stream of 60-byte packets

In this case, testing was done on a machine with the following specification:

  • Ethernet controller: Intel Corporation 82540EM Gigabit Ethernet Controller
  • Ethernet controller: Red Hat, Inc. Virtio network device
  • CPU: 6 x Intel(R) Xeon(R) CPU X5675 @ 3.07GHz (1 Socket)
  • CPU: Intel Common KVM 1 core
  • RAM: 8GB, 1600MHz
  • 5.4.0-74-generic #83-Ubuntu SMP Sat May 8 02:35:39 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

The test produced the following results:

Sending on netmap:ens18: 2 queues, 1 threads and 1 cpus.
10.0.0.1 -> 10.1.0.1 (00:00:00:00:00:00 -> ff:ff:ff:ff:ff:ff)
Sent 10600783 packets 636046980 bytes 71799 events 60 bytes each in 7.55 seconds.
Speed: 1.404 Mpps Bandwidth: 673.963 Mbps (raw 673.963 Mbps). Average batch: 147.65 pkts
info

Netmap can send packets at very high rates, and for simple packet transmission and reception, speed is generally limited by factors other than the CPU (bus, NIC hw limitations or link speed).

For a physical link, you can compute the maximum number of packets per second with the formula:

pps = line_rate / (672 + 8 * pkt_size)

line_rate : the nominal link rate (e.g 10 Gbit/s)

pkt_size : the actual packet size including MAC headers and CRC.

The table below summarizes some of the study results (in Mpps):

pkt_size100M1G10G40G
64.14881.48814.8859.52
128.05890.5895.8923.58
256.03670.3673.6714.70
512.02090.2092.098.38
1024.01130.1131.134.51
1518.00780.0780.783.12

Table 1. Achieved line rates on different NICs for different packet sizes

caution

After installing and testing the netmap successfully, don't forget to configure loading netmap modules at boot automatically on your system.