DOCA Documentation v2.5.1 LTS
1.0

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.

system-design-diagram-version-1-modificationdate-1702685136120-api-v2.png

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

application-architecture-diagram-version-1-modificationdate-1702685135857-api-v2.png

Static Mode

static-mode-diagram-version-1-modificationdate-1702685135467-api-v2.png

  1. The firewall application builds 4 pipes for each port: One control pipe, two drop pipes, and a hairpin pipe.

  2. 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


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.

  1. 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".

  2. CLI example for running the application on the host:

    1. Interactive mode:

      Copy
      Copied!
                  

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

    2. 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

  3. 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"

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 .

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:

  1. 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

  2. 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 .

  1. Parse application argument.

    1. Initialize the arg parser resources and register DOCA general parameters.

      Copy
      Copied!
                  

      doca_argp_init();

    2. Register firewall application parameters.

      Copy
      Copied!
                  

      register_firewall_params();

    3. Parse application parameters.

      Copy
      Copied!
                  

      doca_argp_start();

  2. 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.

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

    Copy
    Copied!
                

    firewall_pipes_init();

  4. Configure firewall rules.

    Mode

    Procedure

    Static

    1. Initialize drop packets array from the input JSON file:

      Copy
      Copied!
                  

      init_drop_packets();

    2. Add firewall drop rules parsed from JSON file:

      Copy
      Copied!
                  

      firewall_add_drop_rules();

    Interactive

    1. Initialize the firewall's interactive command line:

      Copy
      Copied!
                  

      interactive_cmdline();

    2. Free allocated resources.

      Copy
      Copied!
                  

      interactive_mode_cleanup();

  5. Firewall clean-up.

    Copy
    Copied!
                

    firewall_ports_destroy();

    1. Destroy all DOCA Flow resources.

  6. Arg parser destroy.

    Copy
    Copied!
                

    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

© Copyright 2023, NVIDIA. Last updated on Mar 5, 2024.