NVIDIA DOCA Firewall Application Guide
This guide provides an example of firewall implementation on top of NVIDIA® BlueField® DPU .
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
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.
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:
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
This application leverages the following DOCA library:
Refer to its respective programming guide for more information.
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:
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 levelfor
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 addressfor
the grpc server Program Flags: -m, --mode Set running mode {static
, interactive} -r, --firewall-rules <path> Path to the JSON file with5
-tuple rules when running withstatic
modeNoteThis usage printout can be printed to the command line using the -h (or --help) options:
/opt/mellanox/doca/applications/firewall/bin/doca_firewall -h
NoteFor additional information, refer to section "Command Line Flags".
CLI example for running the application on the host:
Interactive mode:
/opt/mellanox/doca/applications/firewall/bin/doca_firewall --grpc-address
192.168
.101.2
-l50
-m interactiveStatic mode:
/opt/mellanox/doca/applications/firewall/bin/doca_firewall --grpc-address
192.168
.101.2
-l50
-mstatic
-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:
doca_firewall --json [json_file]
For example:
cd /opt/mellanox/doca/applications/firewall/bin ./doca_firewall --json ./firewall_params.json
WarningBefore 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:
|
|
|
N/A |
sdk-log-level |
Sets the log level for the program:
|
|
|
j |
json |
Parse all command flags from an input json file |
N/A |
|
g |
grpc-address |
Set the IP address for the gRPC server |
|
|
Program Flags |
m |
mode |
Set running mode {static or interactive} Warning
This flag is mandatory.
|
|
r |
firewall-rules |
Path to JSON rules file |
|
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 .
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:
cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_grpc_support=true
ninja -C /tmp/build
doca_firewall is created under /tmp/build/firewall/src/.
Recompiling Firewall Application Only
To directly build only the firewall application:
cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_grpc_support=true
-Denable_all_applications=false
-Denable_firewall=true
ninja -C /tmp/build
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 :
cd /opt/mellanox/doca/applications/ meson /tmp/build ninja -C /tmp/build
Notedoca_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 .
Parse application argument.
Initialize the arg parser resources and register DOCA general parameters.
doca_argp_init();
Register firewall application parameters.
register_firewall_params();
Parse application parameters.
doca_argp_start();
Firewall initialization.
firewall_ports_init();
Create a new gRPC channel and initialize a stub.
Initialize DOCA Flow and DOCA Flow ports.
Create control, TCP, UDP, and hairpin pipes for both ports.
firewall_pipes_init();
Configure firewall rules.
Mode
Procedure
Static
Initialize drop packets array from the input JSON file:
init_drop_packets();
Add firewall drop rules parsed from JSON file:
firewall_add_drop_rules();
Interactive
Initialize the firewall's interactive command line:
interactive_cmdline();
Free allocated resources.
interactive_mode_cleanup();
Firewall clean-up.
firewall_ports_destroy();
Destroy all DOCA Flow resources.
Arg parser destroy.
doca_argp_destroy();
/opt/mellanox/doca/applications/firewall/src
/opt/mellanox/doca/applications/firewall/bin/firewall_params.json
/opt/mellanox/doca/applications/firewall/bin/firewall_rules.json