NVIDIA DOCA Firewall Application Guide

This guide provides an example of firewall implementation on top of NVIDIA® BlueField® DPU .

Introduction

A firewall application is a network security application that leverages the DPU's hardware capability to monitor incoming and outgoing network traffic and allow or block packets based on a set of preconfigured rules.

The firewall application is based on DOCA Flow gRPC library, used for remote programming of the DPU's hardware.

The firewall can operate in two modes:

Static mode – the firewall application gets 5-tuple traffic from the user with a JSON file for packets to be dropped. The packets that do not match any of the 5-tuple are forwarded by a hairpin pipe.
Interactive mode – the user can add rules from the command line in real time to execute different firewall rules

System Design

The firewall application is designed to run on the host and to use DOCA Flow gRPC client to send instructions to a server that runs on the BlueField DPU instance. The DPU intercepts ingress traffic from the wire and either drops it or forwards it to the egress port using a hairpin. The decision is made using traffic classification.

Application Architecture

The firewall runs on top of DOCA Flow gRPC to classify packets.

Static Mode

The firewall application builds 4 pipes for each port: One control pipe, two drop pipes, and a hairpin pipe.
The drop pipes match only 5-tuple traffic with specific source and destination IPs and source and destination ports.
- One of the drop pipes matches TCP traffic and the other matches UDP
- The hairpin pipe matches every packet (no misses)
- The control pipe serves as a root pipe and has two entries: The first entry forwards the TCP traffic to the TCP drop pipe, and the second entry forwards UDP traffic to the UDP drop pipe
- The hairpin pipe serves as a forwarding miss component to the drop pipes. Therefore, every received packet is checked first against the drop pipes. If there is a match, then it is dropped, otherwise, it is forwarded to the hairpin pipe and is then matched.

Interactive Mode

Running in interactive mode initializes 2 ports, creates the same pipes as in "Static Mode", and the user then adds or removes entries.

When adding an entry, one must run commands to create a 5-tuple match beforehand
After an entry is created successfully, the relevant ID is printed for future use

Available commands:

add entry port_id=<port_id>
rm entry port_id=<port_id>,entry_id=[entry_id]
port pipes flush port_id=[port_id]
port pipes dump port_id=[port_id],file=[file_name]
create entry_match [field=value,…]

5-tuple match struct fields:

Fields	Field Options
`outer.src_ip_addr`
`outer.dst_ip_addr`
`outer.l4_type_ext`	`tcp`, `udp`
`outer.tcp_src_port`
`outer.tcp_dst_port`
`outer.udp_src_port`
`outer.udp_dst_port`

The following is an example for creating a pipe and adding an entry:

Copy
Copied!

            
            create entry_match outer.src_ip_addr=192.168.105.2,outer.dst_ip_addr=192.168.105.3,outer.l4_type_ext=tcp,outer.tcp_src_port=10000,outer.tcp_dst_port=5000
add entry port_id=0,pipe_queue=0

DOCA Libraries

This application leverages the following DOCA library:

DOCA Flow

Refer to its respective programming guide for more information.

Running the Application

Installation

Refer to the NVIDIA DOCA Installation Guide for Linux for details on how to install BlueField-related software.

Prerequisites

The DOCA Firewall application makes use of DOCA's gRPC infrastructure, and specifically the DOCA Flow gRPC server on the BlueField. For information about the required configuration steps, refer to NVIDIA DOCA gRPC Infrastructure User Guide.

Application Execution

The firewall application is provided in both source and binary forms, and the binary is located under /opt/mellanox/doca/applications/firewall/bin/doca_firewall.

Application usage instructions:

Copy
Copied!

            
            Usage: doca_firewall [DOCA Flags] [Program Flags]
 
DOCA Flags:
  -h, --help                              Print a help synopsis
  -v, --version                           Print program version information
  -l, --log-level                         Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  --sdk-log-level                         Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  -j, --json <path>                       Parse all command flags from an input json file
  -g, --grpc-address ip_address[:port]    Set the IP address for the grpc server
 
Program Flags:
  -m, --mode                              Set running mode {static, interactive}
  -r, --firewall-rules <path>             Path to the JSON file with 5-tuple rules when running with static mode

Note

This usage printout can be printed to the command line using the -h (or --help) options:

Copy
Copied!

            
            /opt/mellanox/doca/applications/firewall/bin/doca_firewall -h

Note

For additional information, refer to section "Command Line Flags".

CLI example for running the application on the host:

Interactive mode:

Copy
Copied!

            
            /opt/mellanox/doca/applications/firewall/bin/doca_firewall --grpc-address 192.168.101.2 -l 50 -m interactive

Static mode:

Copy
Copied!

            
            /opt/mellanox/doca/applications/firewall/bin/doca_firewall --grpc-address 192.168.101.2 -l 50 -m static -r firewall_rules.json

The application also supports a JSON-based deployment mode, in which all command-line arguments are provided through a JSON file:
Copy

Copied!
```
            
            doca_firewall --json [json_file]
        
```
For example:
Copy

Copied!
```
            
            cd /opt/mellanox/doca/applications/firewall/bin
./doca_firewall --json ./firewall_params.json
        
```
Warning

Before execution, ensure that the used JSON file contains the correct configuration parameters, and especially the PCIe addresses necessary for the deployment .

Command Line Flags

Flag Type	Short Flag	Long Flag/JSON Key	Description	JSON Content
General flags	`h`	`help`	Prints a help synopsis	N/A
	`v`	`version`	Prints program version information	N/A
	`l`	`log-level`	Set the log level for the application: DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70 ( requires compilation with `TRACE` log level support )	Copy Copied! `"log-level": 60`
	N/A	`sdk-log-level`	Sets the log level for the program: DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70	Copy Copied! `"sdk-log-level": 40`
	`j`	`json`	Parse all command flags from an input json file	N/A
	`g`	`grpc-address`	Set the IP address for the gRPC server	Copy Copied! `"grpc-address": "0.0.0.0"`
Program Flags	`m`	`mode`	Set running mode {`static` or `interactive`} Warning This flag is mandatory.	Copy Copied! `"mode": "interactive"`
Program Flags	`r`	`firewall-rules`	Path to JSON rules file	Copy Copied! `"firewall-rules": "firewall_rules.json"`

Note

Refer to DOCA Arg Parser for more information regarding the supported flags and execution modes.

Troubleshooting

Refer to the NVIDIA DOCA Troubleshooting Guide for any issue encountered with the installation or execution of the DOCA applications .

Recompiling the Application

In addition to providing the application in binary form, the installation also includes all of the application sources and compilation instructions so as to allow modifying the sources and recompiling the application. For more information about the applications, as well as development and compilation tips, refer to the DOCA Applications page.

The sources of the application can be found under the /opt/mellanox/doca/applications/firewall/src directory.

Recompiling All Applications

The applications are all defined under a single meson project, meaning that the default compilation will recompile all the DOCA applications.

To build all the applications together, including the gRPC-related applications, run:

Copy
Copied!

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_grpc_support=true
ninja -C /tmp/build

Note

doca_firewall is created under /tmp/build/firewall/src/.

Recompiling Firewall Application Only

To directly build only the firewall application:

Copy
Copied!

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_grpc_support=true -Denable_all_applications=false -Denable_firewall=true
ninja -C /tmp/build

Note

doca_firewall is created under /tmp/build/firewall/src/.

Alternatively, users can set the desired flags in the meson_options.txt file instead of providing them in the compilation command line:

Edit the following flags in /opt/mellanox/doca/applications/meson_options.txt:
- Set enable_all_applications to false
- Set enable_grpc_support to true
- Set enable_firewall to true

Run the following compilation commands :

Copy
Copied!

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

Note

doca_firewall is created under /tmp/build/firewall/src/.

Troubleshooting

Refer to the NVIDIA DOCA Troubleshooting Guide for any issue encountered with the compilation of the application .

Application Code Flow

Parse application argument.

Initialize the arg parser resources and register DOCA general parameters.

Copy
Copied!

            
            doca_argp_init();

Register firewall application parameters.

Copy
Copied!

            
            register_firewall_params();

Parse application parameters.

Copy
Copied!

            
            doca_argp_start();

Firewall initialization.
Copy

Copied!
```
            
            firewall_ports_init();
        
```
1. Create a new gRPC channel and initialize a stub.
2. Initialize DOCA Flow and DOCA Flow ports.

Create control, TCP, UDP, and hairpin pipes for both ports.

Copy
Copied!

            
            firewall_pipes_init();

Configure firewall rules.

Mode	Procedure
Static	Initialize drop packets array from the input JSON file: Copy Copied! `init_drop_packets();` Add firewall drop rules parsed from JSON file: Copy Copied! `firewall_add_drop_rules();`
Interactive	Initialize the firewall's interactive command line: Copy Copied! `interactive_cmdline();` Free allocated resources. Copy Copied! `interactive_mode_cleanup();`

Firewall clean-up.

Copy
Copied!

            
            firewall_ports_destroy();

Destroy all DOCA Flow resources.

Arg parser destroy.

Copy
Copied!

            
            doca_argp_destroy();

References

/opt/mellanox/doca/applications/firewall/src
/opt/mellanox/doca/applications/firewall/bin/firewall_params.json
/opt/mellanox/doca/applications/firewall/bin/firewall_rules.json

NVIDIA DOCA Firewall Application Guide

On This Page