DUMP_ON_EVICTION(4)

NAME
dump_on_eviction, lbug_on_eviction - configure subsystem-specific logging and crash behavior on eviction events in Lustre

SYNOPSIS
lctl set_param dump_on_eviction=subsystem_list
lctl set_param lbug_on_eviction=hex_mask
lctl get_param dump_on_eviction
dump_on_eviction=subsystem_list
lctl get_param lbug_on_eviction
lbug_on_eviction=subsystem_list

DESCRIPTION
The dump_on_eviction and lbug_on_eviction parameters control the behavior of the Lustre filesystem when eviction events occur. Eviction refers to the forced removal of a client, lock, or recovery context from the system due to timeout or other failure conditions. These parameters allow fine-grained control over whether Lustre dump log with detailed diagnostic information (dump_on_eviction) or triggers an immediate kernel crash (lbug_on_eviction) upon eviction events in specific subsystems.

Both parameters accept either a comma/space/plus-separated list of subsystem names or a numeric bitmask (hexadecimal, decimal, octal). The values are applied using:
lctl set_param dump_on_eviction=subsystem_list
lctl set_param lbug_on_eviction=bit_mask

The value of output setting uses space-separated list.
lctl get_param dump_on_eviction
dump_on_eviction=ldlm stale

The following subsystems are supported:

1 (0x01)
    Special alias for enabling all subsystems except pinger, this is old behavior: llite, ldlm, stale. Equivalent to mask 0x0E.

llite (0x02)
    Client eviction during reconnect, the server informs the client that it has been evicted. This affects the client-side, but server could be a client to another server.

ldlm (0x04)
    Eviction by LDLM (Distributed Lock Manager) due to lock callback timer expired, server side event.

stale (0x08)
    Eviction triggered by stale recovery state — e.g., when a client fails to reconnect within recovery timeout and its state is considered abandoned by the MDS/OSS, server side.

pinger (0x10)
    Eviction of a client due to failure at pinger heartbeats — the server did not receive a request from the client during the waiting time. Previously, pinger evictions did not trigger logging or crashes; this subsystem enables diagnostic behavior.

The parameter lbug_on_eviction accepts a numeric mask (e.g., 0x14) or comma/space/plus-separated list of subsystem names (e.g., ldlm+stale), and will trigger an immediate kernel crash (LBUG()) when any matching eviction occurs. The parameter dump_on_eviction behaves similarly but only triggers dumpint of Lustre log without crashing the system. This is useful for debugging production systems where crashes are undesirable.

EXAMPLES
Use lbug_on_eviction carefully, as it crash a server. Pinger and ldlm evictions often occur due to network problems.

Enable logging for LDLM and stale recovery evictions (no crash):
    lctl set_param dump_on_eviction=ldlm+stale

Trigger kernel crash on pinger eviction:
    lctl set_param lbug_on_eviction=pinger

Enable logging and crashes for all eviction types:
    lctl set_param dump_on_eviction=llite,ldlm,stale,pinger
    lctl set_param lbug_on_eviction=0x1E

Disable all eviction logging (default behavior):
    lctl set_param dump_on_eviction=0
    lctl set_param lbug_on_eviction=0

SEE ALSO
lctl(8),

HISTORY
This feature was introduced in Lustre 2.17 to provide diagnostic control over eviction events.