Kernel Debug on Security Gateway

1

Configure the applicable debug settings:

1. Restore the default settings.
2. Allocate the debug buffer.

In this step, you prepare the kernel debug options:

1. Restore the default debug settings, so that any other debug settings do not interfere with the kernel debug.
2. Allocate the kernel debug buffer, in which Security Gateway 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 collects only applicable debug messages.

3

Start the collection of the kernel debug into an output file.

In this step, you configure Security Gateway 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 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.

fw ctl debug -h

fw ctl debug -buf 8200 [-v {"<List of VSIDs>" | all}] [-k]

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.

  Note - We do not recommend this option, because it disables even the basic default debug messages.

-d <Strings to Search>

When this parameter is specified, the Security Gateway:

1. Examines the applicable debug messages based on the enabled kernel debug modules and their debug flags.
2. Collects only debug messages that contain at least one of the specified strings into the kernel debug buffer.
3. 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.
• Separate the desired strings by commas without spaces:

  -d String1,String2,...,StringN

• You can specify up to 10 strings, up to 250 characters in total.

-s "<String to Stop Debug>"

When this parameter is specified, the Security Gateway:

1. Collects the applicable debug messages into the kernel debug buffer based on the enabled kernel debug modules and their debug flags.
2. Does not write any of these debug messages from the kernel debug buffer into the output file.
3. Stops collecting all debug messages when it detects the first debug message that contains the specified string in the kernel debug buffer.
4. 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.

-m <Name of Debug Module>

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

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

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

• all - Enables all debug flags in the specified kernel debug module.
• + <List of Debug Flags> - Enables the specified debug flags in the specified kernel debug module.

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

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

  Example: + drop conn

• - <List of Debug Flags> - Disables the specified debug flags in the specified kernel debug module.

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

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

  Example: - conn

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

Specifies the list of Virtual Systems. A VSX Gateway automatically filters the collected kernel debug information for debug messages only for these Virtual Systems.

• -v "<List of VSIDs>" - Monitors the 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"

• -v all - Monitors the messages from all configured Virtual Systems.

Notes:

• This parameter is supported only in VSX mode.
• This parameter and the -k parameter are mutually exclusive.

-e <Expression>

-i <Name of Filter File>

-i -

-u

Specifies the INSPECT filter for the debug:

• -e <Expression> - Specifies the INSPECT filter. For details and syntax, see sk30583: What is FW Monitor?.
• -i <Name of Filter File> - Specifies the file that contains the INSPECT filter.
• -i - - Specifies that the INSPECT filter arrives from the standard input. You are prompted to enter the INSPECT filter on the screen.
• -u - Removes the INSPECT debug filter.

Notes:

• This is a legacy parameter.
• When you use this parameter, the Security Gateway cannot apply the specified INSPECT filter to the accelerated traffic.
• For new debug filters, see Kernel Debug Filters.

-z

The Security Gateway processes some connections in both SecureXL code and in the Host appliance code (for example, Passive Streaming Library (PSL) - an IPS infrastructure, which transparently listens to TCP traffic as network packets, and rebuilds the TCP stream out of these packets.).

The Security Gateway processes some connections in only in the Host appliance code.

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

-k

The Security Gateway processes some connections in both kernel space code and in the user space code (for example, Web Intelligence).

The Security Gateway processes some connections only in the kernel space code.

When you use this parameter, kernel debug output contains the debug messages only from the kernel space.

Notes:

• This parameter is not supported in the VSX mode, in which the Firewall works in the user space.
• This parameter and the -v parameter are mutually exclusive.

-p <List of Fields>

By default, when the Security Gateway prints the debug messages, the messages start with the applicable CPU ID and CoreXL FW 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 desired 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

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

-f

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

• When you press CTRL+C.
• 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.

/<Path>/<Name of Output File>

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

Important:

• Always use the largest partition on the disk - /var/log/. Security Gateway can generate many debug messages within short time. As a result, the debug output file can grow to large size very fast.
• When Falcon Acceleration Cards (sk116242) are installed, the Host Security Appliance creates several debug output files - a file /var/log/ppk_<Slot_#>_debug.log for each acceleration card and the specified /<Path>/<Name of Output File> file. When you stop the debug, the Host Security Appliance unifies all these files into a single file named /<Path>/<Name of Output File>_unified.

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