Lunatik

• Index

Contents

• Class probe
• probe

Modules

• completion
• data
• device
• fib
• fifo
• linux
• lunatik
• lunatik.runner
• mailbox
• net
• netfilter
• notifier
• probe
• rcu
• socket
• socket.inet
• syscall
• syscall.table
• thread
• xdp
• xtable

Topics

• README

Module probe

kprobes mechanism.

This library allows Lua scripts to dynamically probe (instrument) kernel functions or specific instruction addresses. Callbacks can be registered to execute Lua code just before (pre-handler) and/or just after (post-handler) the probed instruction is executed.

Class probe

probe

Class probe

probe:enable (enable_flag)

Enables or disables an already registered probe. This method is called on a probe object.

Parameters:

• enable_flag boolean If true, the probe is enabled. If false, the probe is disabled. A disabled probe remains registered but its handlers will not be executed.

Returns:

nil

Raises:

Error if the probe was not properly registered or has been stopped.

Usage:

my_probe_object:enable(false) -- Disable the probe

probe:stop ()

Stops and unregisters the probe. This method is called on a probe object. Once stopped, the kprobe is disabled and unregistered from the kernel, and its handlers will no longer be called. The associated resources are released.

Returns:

nil

Usage:

my_probe_object:stop()

probe

new (symbol_or_address, handlers)

Creates and registers a new kernel probe. This function installs a kprobe at the specified kernel symbol or address. Lua callback functions can be provided to execute when the probe hits.

Parameters:

• symbol_or_address string or lightuserdata The kernel symbol name (string) or the absolute kernel address (lightuserdata) to probe. Suitable symbol names are typically those exported by the kernel or other modules, often visible in /proc/kallsyms (when viewed from userspace). The syscall module (e.g., syscall.numbers.openat) can be used to get system call numbers.

  For system call addresses, you can use syscall.address(syscall.numbers.openat). For other kernel symbols, linux.lookup("symbol_name") can provide the address. Directly using addresses requires knowing the exact memory location, which can vary between kernel builds and is generally less portable than using symbol names or lookup functions.

• handlers table

  A table containing the callback functions for the probe. It can have the following fields:

  • pre (function, optional): A Lua function to be called just before the probed instruction is executed.
  • post (function, optional): A Lua function to be called just after the probed instruction has executed.

  Both pre and post handlers receive two arguments:

  1. target (string|lightuserdata): The symbol name or address that was probed.
  2. dump_regs (function): A closure that, when called without arguments, will print the current CPU registers and stack trace to the system log. This is useful for debugging.

Returns:

probe A new probe object. This object can be used to later stop() or enable()/disable() the probe.

Raises:

Error if the probe cannot be registered (e.g., symbol not found, memory allocation failure, invalid address).