dropwatch(1)

kernel dropped packet monitoring utility

Section 1 dropwatch bookworm source

Summary

dropwatch is an interactive tool for watching packets that the Linux kernel drops, so you can figure out where in the network stack traffic is being lost. You launch it, type 'start' at its prompt to begin receiving drop alerts from the kernel, and it reports the locations (kernel functions or raw instruction pointers) where drops occur. It is mainly used for diagnosing mysterious packet loss on a host.

Tip: dropwatch needs to talk to the kernel via netlink, so run it as root (or with CAP_NET_ADMIN) or you won't get any alerts.

Description

dropwatch

NAME

dropwatch - kernel dropped packet monitoring utility

SYNOPSIS

dropwatch [-l method | list]

DESCRIPTION

dropwatch is an interactive utility for monitoring and recording packets that are dropped by the kernel.

OPTIONS

-l method | list, --lmethod method | list

Select the translation method to use when a drop alert arrives. By default the raw instruction pointer of a drop location is output, but by the use of the -l option, we can assign a translation method so that the instruction pointer can be translated into function names. Currently supported lookup methods are:

	list		Show all supported methods.
	kas		Use /proc/kallsyms to lookup instruction pointers to function mappings.

INTERACTIVE COMMANDS

	start		Tells the kernel to start reporting dropped packets.
	stop		Tells the kernel to discontinue reporting dropped packets.
	exit		Exits the dropmonitor program.
	help		Displays summary of all commands.

set alertlimit value

Sets a triggerpoint to stop monitoring for dropped packets after value alerts have been received.

set alertmode { summary | packet }

summary - Default mode. A summary of recent packet drops is sent to user space. The alert includes drop locations and number of drops in each location.

packet - Each dropped packet is sent to user space. The alert includes the packet itself and various metadata such as drop location and timestamp.

set trunc len

Sets the truncation length. Reported packets will be truncated to length len. This setting is only applicable when alertmode is set to packet. By default packets are not truncated. A value of 0 disables truncation.

set queue len

Sets the queue length in the kernel. When alertmode is set to packet, the kernel queues dropped packets in a per-CPU drop list before preparing a netlink message for each. This setting controls the queue’s length. By default this is limited by the kernel to 1,000 packets. Increasing this value will increase the memory utilization of the system.

set sw { true | false }

Enables or disables the monitoring of software originated drops. By default software originated drops are monitored.

set hw { true | false }

Enables or disables the monitoring of hardware originated drops. By default hardware originated drops are not monitored.

	show		Query existing configuration from the kernel and show it.
	stats		Query statistics from the kernel and show it.

Tail dropped - Number of packets that could not be enqueued to the per-CPU drop list(s).

Examples

dropwatch -l list

List the supported symbol-translation methods before starting.

dropwatch -l kas

Start dropwatch using /proc/kallsyms to translate drop addresses into readable kernel function names.

start

Typed at the dropwatch prompt: tells the kernel to begin reporting dropped packets (use 'stop' to halt, 'exit' to quit).

set alertmode packet

Typed at the dropwatch prompt: switch from summary mode to per-packet alerts that include the packet and metadata.