Kernel Debug Filters

By default, kernel debug output contains information about all processed connections.

You can configure filters for kernel debug to collect debug messages only for the applicable connections.

There are three types of debug filters:

  • By connection tuple parameters

  • By an IP address parameter

  • By a VPN peer parameter

To configure these kernel debug filters, assign the applicable values to the applicable kernel parameters before you start the kernel debug.

You assign the values to the applicable kernel parameters temporarily with the "fw ctl set" command.

Notes:

  • A Security Gateway supports:

    • up to five Connection Tuple filters in total (from all types)

    • up to three Host IP Address filters

    • up to two VPN Peer filters

  • A Security Gateway applies these debug filters to both the non-accelerated and accelerated traffic.

  • A Security Gateway applies these debug filters to Kernel Debug Procedure with Connection Life Cycle.

Best Practice - It is usually simpler to set the Connection Tuple and Host IP Address filters from within the 'fw ctl debug' and 'fw ctl kdebug' command. To filter the kernel debug by a VPN Peer, use the procedure below.

To configure debug filter of the type "By connection tuple parameters":

A Security Gateway processes connections based on the 5-tuple:

This debug filter lets you filter by these tuple parameters:

Tuple Parameter

Syntax for Kernel Parameters

Source IP address

fw ctl set str simple_debug_filter_saddr_<N> "<IPv4 or IPv6 Address>"

Source Ports

fw ctl set int simple_debug_filter_sport_<N> <1-65535>

Destination IP address

fw ctl set str simple_debug_filter_daddr_<N> "<IPv4 or IPv6 Address>"

Destination Ports

fw ctl set int simple_debug_filter_dport_<N> <1-65535>

Protocol Number

fw ctl set int simple_debug_filter_proto_<N> <0-254>

Notes:

  1. <N> is an integer between 1 and 5. This number is an index for the configured kernel parameters of this type.

  2. When you specify IP addresses, you must enclose them in double quotes.

  3. When you configure kernel parameters with the same index <N>, the debug filter is a logical "AND" of these kernel parameters.

    In this case, the final filter matches only one direction of the processed connection.

    • Example 1 - packets from the source IP address X to the destination IP address Y:

      simple_debug_filter_saddr_1 <Value X>
      AND
      simple_debug_filter_daddr_1 <Value Y>

    • Example 2 - packets from the source IP address X to the destination port Y:

      simple_debug_filter_saddr_1 <Value X>
      AND
      simple_debug_filter_dport_1 <Value Y>

  4. When you configure kernel parameters with the different indices <N>, the debug filter is a logical "OR" of these kernel parameters.

    This means that if you need the final filter to match both directions of the connection, you need to configure the applicable debug filters for both directions.

    • Example 1 - packets either from the source IP address X, or to the destination IP address Y:

      simple_debug_filter_saddr_1 <Value X>
      OR
      simple_debug_filter_daddr_2 <Value Y>

    • Example 2 - packets either from the source IP address X, or to the destination port Y:

      simple_debug_filter_saddr_1 <Value X>
      OR
      simple_debug_filter_dport_2 <Value Y>

  5. For information about the Port Numbers, see IANA Service Name and Port Number Registry.

  6. For information about the Protocol Numbers, see IANA Protocol Numbers.

To configure debug filter of the type "By an IP address parameter":

This debug filter lets you filter by one IP address, which is either the source or the destination IP address of the packet.

Syntax for Kernel Parameters:

fw ctl set str simple_debug_filter_addr_<N> "<IPv4 or IPv6 Address>"

Notes:

  1. <N> is an integer between 1 and 3.

    This number is an index for the configured kernel parameters of this type.

  2. You can configure one, two, or three of these kernel parameters at the same time.

    • Example 1:

      Configure one IP address (simple_debug_filter_addr_1).

    • Example 2:

      Configure two IP addresses (simple_debug_filter_addr_1 and simple_debug_filter_addr_2).

      This would match packets, where any of these IP addresses appears, either as a source or a destination.

  3. You must enclose the IP addresses in double quotes.

To configure debug filter of the type "By a VPN peer parameter":

This debug filter lets you filter by one IP address.

Syntax for Kernel Parameters:

fw ctl set str simple_debug_filter_vpn_<N> "<IPv4 or IPv6 Address>"

Notes:

  1. <N> is an integer - 1 or 2.

    This number is an index for the configured kernel parameters of this type.

  2. You can configure one or two of these kernel parameters at the same time.

    • Example 1:

      Configure one VPN peer (simple_debug_filter_vpn_1).

    • Example 2:

      Configure two VPN peers (simple_debug_filter_vpn_1 and simple_debug_filter_vpn_2).

  3. You must enclose the IP addresses in double quotes.

To disable all debug filters:

You can disable all the configured debug filters of all types.

Syntax for Kernel Parameter:

fw ctl set int simple_debug_filter_off 1

Usage Example

You need the kernel debug to show the information about the connection from Source IP address 192.168.20.30 from any Source Port to Destination IP address 172.16.40.50 to Destination Port 80 (192.168.20.30:<Any> --> 172.16.40.50:80).

Run these commands before you start the kernel debug:

fw ctl set int simple_debug_filter_off 1

fw ctl set str simple_debug_filter_saddr_1 "192.168.20.30"

fw ctl set str simple_debug_filter_daddr_1 "172.16.40.50"

fw ctl set str simple_debug_filter_saddr_2 "172.16.40.50"

fw ctl set str simple_debug_filter_daddr_2 "192.168.20.30"

fw ctl set int simple_debug_filter_dport_1 80

fw ctl set int simple_debug_filter_sport_2 80

Important - In the above example, two Connection Tuple filters are used ("..._1" and "..._2") - one for each direction, because we want the debug filter to match both directions of this connection.