Kernel Debug Syntax

Description

During a kernel debug session, Security Gateway Dedicated Check Point server that runs Check Point software to inspect traffic and enforce Security Policies for connected network resources. / Cluster Member Security Gateway that is part of a cluster. / Scalable Platform Security Group Member Member of a Security Group in ElasticXL Cluster, Maestro, and Scalable Chassis. Acronym: SGM. prints special debug messages that help Check Point Support and R&D understand how it processes the applicable connections.

Important:

In Cluster Two or more Security Gateways that work together in a redundant configuration - High Availability, or Load Sharing., you must configure and perform the kernel debug procedure on all cluster members in the same way.
On Scalable Platforms (Maestro and Chassis), you must connect to the applicable Security Group A logical group of Security Appliances (in Maestro) / Security Gateway Modules (on Scalable Chassis) that provides Active/Active cluster functionality. A Security Group can contain one or more Security Appliances / Security Gateway Modules. Security Groups work separately and independently from each other. To the production networks, a Security Group appears a single Security Gateway. In Maestro, each Security Group contains: (A) Applicable Uplink ports, to which your production networks are connected; (B) Security Appliances (the Quantum Maestro Orchestrator determines the applicable Downlink ports automatically); (C) Applicable management port, to which the Check Point Management Server is connected..

Action Plan to Collect a Kernel Debug

Note - See the Kernel Debug Procedure, or the Kernel Debug Procedure with Connection Life Cycle.

Step	Action	Instructions
1	Configure the applicable debug settings: Restore the default settings. Allocate the debug buffer.	In this step, you prepare the kernel debug options: Restore the default debug settings, so that any other debug settings do not interfere with the kernel debug. Allocate the kernel debug buffer, in which Security Gateway / Cluster Member / each Security Group Member holds the applicable debug messages.
2	Configure the applicable kernel debug modules and their debug flags.	In this step, you prepare the applicable kernel debug modules and their debug flags, so that Security Gateway / Cluster Member / each Security Group Member collects only applicable debug messages.
3	Start the collection of the kernel debug into an output file.	In this step, you configure Security Gateway / Cluster Member / each Security Group Member to write the debug messages from the kernel debug buffer into an output file.
4	Stop the kernel debug.	In this step, you configure Security Gateway / Cluster Member / each Security Group Member to stop writing the debug messages into an output file.
5	Restore the default kernel debug settings.	In this step, you restore the default kernel debug options.

CLI Syntax

Notes:

The syntax below applies to both Gaia Clish The name of the default command line shell in Check Point Gaia operating system. This is a restricted shell (role-based administration controls the number of commands available in the shell). / Gaia gClish The name of the global command line shell in Check Point Gaia operating system for Security Appliances connected to Check Point Quantum Maestro Orchestrators and for Security Gateway Modules on Scalable Chassis. Commands you run in this shell apply to all Security Gateway Module / Security Appliances in the Security Group. and the Expert mode.
The syntax below applies to the Security Gateway, each Cluster Member, and Scalable Platform Security Group.

Important - To run these commands in the Expert mode on a Scalable Platform Security Group, you must use the "g_fw ctl ..." command instead of the "fw ctl ..." command.

General syntax for the 'fw ctl debug' command (configuring the kernel debug modules and debug flags)

fw ctl debug

[-h]

[0 | -x]

[-buf 8200]

[-v {"<List of VSIDs>" | all} -k]

[-d "<Strings to Search>"]

[-s "<String to Stop Debug>"]

[-F "<Source IP>,<Source Port>,<Dest IP>,<Dest Port>,<Protocol Number>"]

[-H "<IP Address>"]

[-e "<Expression>" | -i {<Path to Filter File> | -} | -u]

[-z]

-m <Name of Debug Module> {all | [+|-] <List of Debug Flags>}

General syntax for the 'fw ctl kdebug' command (configuring the kernel debug output)

fw ctl kdebug

[-h]

[-v {"<List of VSIDs>" | all} -k]

[-p <List of Fields>]

[-T | -t]

[-f]

-o /<Path>/<Name of Output File>

[-m <Number of Cyclic Files> [-s <Size of Each Cyclic File in KB>]]

To restore the default kernel debug settings

To reset all debug flags and enable only the default debug flags in all kernel modules:

fw ctl debug 0

To disable all debug flags including the default flags in all kernel modules:

Best Practice - Do not run this command, because it disables even the basic default debug messages.

As a result, the /var/log/messages file will not contain this basic useful information.

fw ctl debug -x

To configure the debug modules and debug flags

General syntax:

fw ctl debug [-v {"<List of VSIDs>" | all} -k] [-z] -m <Name of Debug Module> {all | [+|-] <List of Debug Flags>}

To see a list of all debug modules and their flags:

Note - The list of kernel modules depends on the Software Blades you enabled on the Security Gateway / ClusterXL / Security Group.

fw ctl debug -m

To see a list of debug flags that are already enabled:

fw ctl debug

To enable all debug flags in the specified kernel module:

fw ctl debug -m <Name of Debug Module> all

To enable only the specified debug flags in the specified kernel module in addition to already enabled debug flags:

fw ctl debug -m <Name of Debug Module> + <List of Debug Flags>

To enable only the specified debug flags in the specified kernel module and disable all other debug flags:

fw ctl debug -m <Name of Debug Module> + <List of Debug Flags>

To disable only the specified debug flags in the specified kernel module:

fw ctl debug -m <Name of Debug Module> - <List of Debug Flags>

To collect the kernel debug output in the Gateway mode

General syntax (only supported parameters are listed):

fw ctl kdebug [-p <List of Fields>] -T -f -o /<Path>/<Name of Output File> [-m <Number of Cyclic Files> -s <Size of Each Cyclic File in KB>]

To start the collection of the kernel debug into an output file:

fw ctl kdebug -T -f > /<Path>/<Name of Output File>

To start collecting the kernel debug into cyclic output files:

fw ctl kdebug -T -f -o /<Path>/<Name of Output File> -m <Number of Cyclic Files> -s <Size of Each Cyclic File in KB>

To collect the kernel debug output in the VSX mode - from specific Virtual Systems

General syntax (only supported parameters are listed):

fw ctl kdebug [-p <List of Fields>] -v {"<List of VSIDs>" | all} -k -T -f -o /<Path>/<Name of Output File> [-m <Number of Cyclic Files> -s <Size of Each Cyclic File in KB>]

To start the collection of the kernel debug into an output file:

fw ctl kdebug -v {"<List of VSIDs>" | all} -k -T -f > /<Path>/<Name of Output File>

To start collecting the kernel debug into cyclic output files:

fw ctl kdebug -v {"<List of VSIDs>" | all} -k -T -f -o /<Path>/<Name of Output File> -m <Number of Cyclic Files> -s <Size of Each Cyclic File in KB>

CLI Parameters

Parameters

Note - Only supported parameters are listed.

Parameter

Description

-h

Shows the built-in help.

0

-x

Controls how to disable the debug flags:

0

Resets all debug flags and enables only the default debug flags in all kernel modules.

-x

Disables all debug flags, including the default flags in all kernel modules.

Best Practice - Do not use the "-x" parameter, because it disables even the basic default debug messages.

As a result, the /var/log/messages file will not contain this basic useful information.

-buf 8200

Allocates the kernel debug buffer.

Notes:

Security Gateway / Cluster Member / each Security Group Member allocates the kernel debug buffer with the specified size for each CoreXL Performance-enhancing technology for Security Gateways on multi-core processing platforms. Multiple Check Point Firewall instances are running in parallel on multiple CPU cores. Firewall instance.
The maximal supported buffer size is 8192 kilobytes..
If not specified explicitly, the default buffer size is 50 kilobytes.
For an approximate total memory utilization, refer to sk160955.

-v {"<List of VSIDs>" | all} -k

Specifies the list of Virtual Systems.

A VSX Gateway Physical server that hosts VSX virtual networks, including all Virtual Devices that provide the functionality of physical network devices. It holds at least one Virtual System, which is called VS0. automatically filters the collected kernel debug information for debug messages only for these Virtual Systems.

-v "<List of VSIDs>" -k

Monitors the debug messages only from the specified Virtual Systems.

To specify the Virtual Systems, enter their VSID number separated with commas and without spaces:

"VSID1[,VSID2,VSID3,...,VSIDn]"

Example: -v "1,3,7" -k

-v all -k

Monitors the debug messages from all configured Virtual Systems.

Notes:

To get the ID numbers of Virtual Systems, run: vsx stat {-v | -l}
This parameter is supported only in the VSX mode.
When you use this parameter "-v", you must also use the parameter "-k".

When you use this "-k" parameter, the kernel debug output also contains the debug messages from kernel components that are not part of any Virtual System, such as SecureXL Check Point product on a Security Gateway that accelerates IPv4 and IPv6 traffic that passes through a Security Gateway. and CoreXL dispatcher.

-d "<Strings to Search>"

When you specify this parameter, the Security Gateway / Cluster Member / Security Group:

Examines the applicable debug messages based on the enabled kernel debug modules and their debug flags.
Collects only debug messages that contain at least one of the strings specified as "<string>" into the kernel debug buffer.
Excludes debug messages that contain at least one of the strings specified as "^<string>" into the kernel debug buffer.
Writes the entire kernel debug buffer into the output file.

Notes:

These strings can be any plain text (not a regular expression) that you see in the debug messages.

You can separate the applicable strings by commas without spaces (up to 250 characters in total):

-d "String1,String2,...,StringN"

You can specify each applicable string separately (use this format if a string contains the comma character):

-d "String1" -d "String2 ... -d "StringN"

You can specify strings to exclude from the kernel debug:

-d "^String1,^String2,...,^StringN"

-d "^String1" -d "^String2 ... -d "^StringN"

You can specify up to 10 strings (total for included and excluded strings).

-s "<String to Stop Debug>"

When you specify this parameter, the Security Gateway / Cluster Member / Security Group:

Collects the applicable debug messages into the kernel debug buffer based on the enabled kernel debug modules and their debug flags.
Does not write any of these debug messages from the kernel debug buffer into the output file.
Stops collecting all debug messages when it detects the first debug message that contains the specified string in the kernel debug buffer.
Writes the entire kernel debug buffer into the output file.

Notes:

This one string can be any plain text (not a regular expression) that you see in the debug messages.
String length is up to 50 characters.

-F "<Source IP>,<Source Port>,<Dest IP>,<Dest Port>,<Protocol Number>"

Specifies the capture filter (for both accelerated and non-accelerated traffic):

<Source IP>

Specifies the source IP address
<Source Port>

Specifies the source Port Number (see IANA Service Name and Port Number Registry)
<Dest IP>

Specifies the destination IP address
<Dest Port>

Specifies the destination Port Number (see IANA Service Name and Port Number Registry)
<Protocol Number>

Specifies the Protocol Number (see IANA Protocol Numbers)

Notes:

You cannot use the "-F" parameter together with these parameters: "-H", "-e", "-i".

The "-F" parameter uses the Kernel Debug Filters.

For more information, see Kernel Debug Filters.

For the Source IP address:

simple_debug_filter_saddr_<N> "<IP Address>"

For the Source Ports:

simple_debug_filter_sport_<N> <1-65535>

For the Destination IP address:

simple_debug_filter_daddr_<N> "<IP Address>"

For the Destination Ports:

simple_debug_filter_dport_<N> <1-65535>

For the Protocol Number:

simple_debug_filter_proto_<N> <0-254>

Value 0 means "any".
This parameter supports up to 5 capture filters (up to 5 instances of the "-F" parameter in the syntax).

The kernel debug performs the logical "OR" between all specified simple capture filters.
If you are running multiple "fw ctl debug" commands at the same time, then you must specify all debug filters only in one command.

Using the "-F" parameter in multiple "fw ctl debug" commands will result in the last specified filter overriding the "-F" filters in all previous "fw ctl debug" commands.

-H "<IP Address>"

Creates an IP address filter - the debug output will include only connections to or from the specified IP address.

For more information, see Kernel Debug Filters.

Example - Capture traffic only to and from the Host 1.1.1.1:

fw ctl debug –H "1.1.1.1"

Notes:

You cannot use the "-H" parameter together with these parameters: "-F", "-e", "-i".
This parameter supports up to 3 capture filters (up to 3 instances of the "-H" parameter in the syntax).
If you are running multiple "fw ctl debug" commands at the same time, then you must specify all debug filters only in one command.

Using the "-H" parameter in multiple "fw ctl debug" commands will result in the last specified filter overriding the "-H" filters in all previous "fw ctl debug" commands.

-m <Name of Debug Module>

Specifies the name of the kernel debug module, for which you print or configure the debug flags.

To see a list of all debug modules, run: fw ctl debug -m

See Kernel Debug Modules and Debug Flags.

{all | [+|-] <List of Debug Flags>}

Specifies which debug flags to enable or disable in the specified kernel debug module.

To see a list of all debug modules and their flags, run: fw ctl debug -m

See Kernel Debug Modules and Debug Flags.

all

Enables all debug flags in the specified kernel debug module.

+ <List of Debug Flags>

Enables only the specified debug flags in the specified kernel module in addition to already enabled debug flags.

You must press the space key after the plus (+) character:

+ <Flag1> [<Flag2> ... <FlagN>]

Example: + drop conn

<List of Debug Flags>

Enables only the specified debug flags in the specified kernel module and disables all other enabled debug flags:

<Flag1> [<Flag2> ... <FlagN>]

Example: "drop conn"

- <List of Debug Flags>

Disables only the specified debug flags in the specified kernel debug module.

You must press the space key after the minus (-) character:

- <Flag1> [<Flag2> ... <FlagN>]

Example: - conn

-e "<Expression>"

-i <Path to Filter File>

-i -

-u

Specifies the INSPECT filter for the debug:

-e "<Expression>"

Specifies the INSPECT filter.

See the R81.20 CLI Reference Guide > Chapter "Security Gateway Commands" > Section "fw" > Section "fw monitor".
-i <Path to Filter File>

Specifies the file that contains the INSPECT filter.
-i -

Specifies that the INSPECT filter arrives from the standard input.

The Security Gateway / Cluster Member / Security Group prompts to enter the INSPECT filter on the screen.
-u

Removes the INSPECT debug filter.

Notes:

These are legacy parameters ("-e" and "-i").
When you use these parameters ("-e" and "-i"), the Security Gateway / Cluster Member / Security Group cannot apply the specified INSPECT filter to the accelerated traffic.
For new debug filters, see Kernel Debug Filters.

-z

The Security Gateway / Cluster Member / Security Group processes some connections in both SecureXL code and in the Host appliance code (for example, Passive Streaming Library (PSL) - an IPS Check Point Software Blade on a Security Gateway that inspects and analyzes packets and data for numerous types of risks (Intrusion Prevention System). infrastructure, which transparently listens to TCP traffic as network packets, and rebuilds the TCP stream out of these packets.).

The Security Gateway / Cluster Member / Security Group processes some connections in only in the Host appliance code.

When you use this parameter "-z", kernel debug output contains the debug messages only from the Host appliance code.

-p <List of Fields>

By default, when the Security Gateway / Cluster Member / Security Group prints the debug messages, these messages start with the applicable CPU ID and CoreXL Firewall instance ID.

You can print additional fields in the beginning of each debug message.

Notes:

These fields are available:

all, proc, pid, date, mid, type, freq, topic, time, ticks, tid, text, errno, host, vsid, cpu.
When you specify the applicable fields, separate them with commas and without spaces:

Field1,Field2,...,FieldN
The more fields you specify, the higher the load on the CPU and on the hard disk.

-T

-t

"-T" - Prints the time stamp in microseconds in front of each debug message.

"-t" - Prints the time stamp in millseconds in front of each debug message. This time resolution is not enough to analyze the kernel debug properly.

Best Practice - Always use the "-T" parameter to make the debug analysis easier.

-f

Collects the debug data until you stop the kernel debug in one of these ways:

When you press the CTRL+C keys.
When you run the "fw ctl debug 0" command.
When you run the "fw ctl debug -x" command.
When you kill the "fw ctl kdebug" process.

-o /<Path>/<Name of Output File>

Specifies the path and the name of the debug output file.

Best Practice - Always use the largest partition on the disk - "/var/log/".

The Security Gateway / Cluster Member / Security Group can generate many debug messages within short time.

As a result, the debug output file can grow to large size very fast.

-o /<Path>/<Name of Output File> -m <Number of Cyclic Files> -s <Size of Each Cyclic File in KB>

Saves the collected debug data into cyclic debug output files.

When the size of the current "<Name of Output File>" reaches the specified "<Size of Each Cyclic File in KB>" (more or less), the Security Gateway / Cluster Member / Security Group renames the current "<Name of Output File>" to "<Name of Output File>.0" and creates a new "<Name of Output File>".

If the "<Name of Output File>.0" already exists, the Security Gateway renames the "<Name of Output File>.0" to "<Name of Output File>.1", and so on - until the specified limit "<Number of Cyclic Files>". When the Security Gateway reaches the "<Number of Cyclic Files>", it deletes the oldest files.

The valid values are:

<Number of Cyclic Files> - from 1 to 999
<Size of Each Cyclic File in KB> - from 1 to 2097150