STAPRUN(8)

✨ STAPRUN(8) — the systemtap runtime, explained by your fave 💖

okay bestie, welcome to staprun from the System Manager's Manual. this is the back half of the whole Systemtap situation and honestly? it's giving quietly essential. let's get into it 🫶

---

🌸 NAME 🌸

staprun — the systemtap runtime, periodt.

---

🎀 SYNOPSIS 🎀

staprun [ OPTIONS ] MODULE [ MODULE-OPTIONS ]

---

💅 DESCRIPTION 💅

so the way this works: staprun is the back-end of the Systemtap tool. it's expecting a kernel module that was produced by the front-end stap tool. that's the whole vibe. 💫

and why is systemtap split into a front-end and a back-end, you ask? iconic question. because splitting it means you can compile a systemtap script on a development machine (one that has the kernel development tools, which you literally need to compile the script), and then just carry the resulting kernel module over to a production machine that has zero development tools installed. no cap, that's the entire point. 🔥

if you wanna know the version number, go check stappaths (7), or just run rpm -q systemtap (that's the fedora/red hat route) or apt-get -v systemtap (that's the ubuntu route). ✨

---

💖 OPTIONS 💖

staprun supports the options below, and that's the list. any other option you throw at it will just print out the supported options at you. respectfully. 🙈

• -v — verbose mode, bestie. the level of verbosity is also set in the SYSTEMTAP_VERBOSE environment variable. 👑
• -V — print the version number and dip. bye! ✌️
• -w — suppress warnings from the script. shhh. 🤫
• -u — load the uprobes.ko module.
• -c CMD — run command CMD, and staprun will exit when CMD does. the '_stp_target' variable will contain the pid for CMD.
• -x PID — the '_stp_target' variable gets set to PID.
• -N PID — sets the '_stp_namespaces_pid' variable to PID.
• -o FILE — send output to FILE. if the module uses bulk mode, the output will be in percpu files FILE_x (FILE_cpux in background and bulk mode) where 'x' is the cpu number. this supports strftime(3) formats for FILE. 🗂️
• -b BUFFER_SIZE — the systemtap module will specify a buffer size, and setting one here will override that value. the value should be an integer between 1 and 4095, which is assumed to be the buffer size in MB. that value will be per-cpu if bulk mode is used.
• -L — load the module and start probes, then detach from the module leaving the probes running. you can attach back to the module later with the -A option. 🦋
• -A — attach to an already-loaded systemtap module.
• -C WHEN — control the coloring of error messages. WHEN must be either "never", "always", or "auto" (which means: only enable if you're at a terminal). if the option is missing, then "auto" is assumed. colors can be modified using the SYSTEMTAP_COLORS environment variable. see the stap(1) manual page for more info on the syntax and behaviour. 🌈
• -M INTERVAL — enable monitor mode, with INTERVAL seconds between updates.
• -d — delete a module. only detached or unused modules that the user has permission to access will be deleted. use "*" (quoted!) to delete all unused modules. 💀
• -D — run staprun in the background as a daemon and show its pid.
• -R — rename the module to a unique name before inserting it.
• -r N:URI — pass the given number and URI data to the tapset functions remote_id() and remote_uri().
• -S size[,N] — sets the maximum size of the output file and the maximum number of output files. if the size of the output file will exceed size megabytes, systemtap switches the output file to the next file. and if the number of output files exceeds N, systemtap removes the oldest output file. you can omit the second argument. ✨
• -T timeout — sets the maximum time the reader thread will wait before dumping the trace buffer. value is in ms, and the default is 200ms. setting this to a high value decreases the number of stapio wake-ups, allowing deeper sleep for embedded platforms. but it impacts interactivity on the terminal, since traces are dumped less often in cases of low throughput. there is no interactivity or performance impact for high throughput, because the trace is dumped when the buffer is full, before this timeout expires. 🧚
• var1=val — sets the value of global variable var1 to val. global variables contained within a module are treated as module options and can be set from the staprun command line. 💜

---

🌟 ARGUMENTS 🌟

MODULE is either a module path or a module name. if it's a module name, the module will be looked for in the following directory (where 'VERSION' is the output of "uname -r"):

/lib/modules/VERSION/systemtap

any additional arguments on the command line are passed straight to the module. one use of these additional module arguments is setting the value of global variables declared within the module. 👇

 $ stap -p4 -m mod1 -e 'global var1="foo"; probe begin{printf("%s\n",
var1); exit()}'

running that with an additional module argument:

 $ staprun mod1.ko var1="HelloWorld"
 HelloWorld

heads up bestie: spaces and exclamation marks currently cannot be passed into global variables this way. 😭

---

🌈 EXAMPLES 🌈

if you want a whole collection of sample scripts, see the stapex(3stap) manual page. 🎀

here's a very basic example of how to use staprun. first, use stap to compile a script. the stap program will report the pathname to the resulting module.

 $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
 /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko

then run staprun with the pathname to the module as an argument.

 $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
 Hello World!

ate. that's the whole flow. 💖

---

🦋 MODULE DETACHING AND ATTACHING 🦋

once staprun installs a Systemtap kernel module, users can detach from the kernel module and reattach to it later. the -L option loads the module and automatically detaches. users can also detach from the kernel module interactively by sending the SIGQUIT signal from the keyboard (typically by typing Ctrl-\). ⌨️

to reattach to a kernel module, you'd use the staprun -A option.

---

⭐ FILE SWITCHING BY SIGNAL ⭐

after staprun has launched the stapio program, users can command it to switch the output file to the next file when it's outputting to file(s) (that's staprun running with the -o option) by sending a SIGUSR2 signal to the stapio process. when it receives SIGUSR2, it will switch the output file to a new file with suffix .N where N is the sequential number. for example, 👇

 $ staprun -o foo ...

this outputs trace logs to foo, and if it receives a SIGUSR2 signal, it switches output to the foo.1 file. and receiving SIGUSR2 again, it switches to the foo.2 file. slay. 🔥

---

👑 SAFETY AND SECURITY 👑

Systemtap, in the default kernel-module runtime mode, is an administrative tool. it exposes kernel internal data structures and potentially private user information. see the stap(1) manual page for additional info on safety and security. ⚠️

to increase system security, users of systemtap must be root, or in the stapusr group, in order to execute this setuid staprun program. a user may select a particular privilege level with the stap --privilege= option, which staprun will later enforce.

• stapdev — members of the stapdev group can write and load script modules with root-equivalent privileges, without particular security constraints. (many safety constraints remain, tho.)
• stapsys — members of the stapsys group have almost all the privileges of stapdev, except for guru mode constructs.
• stapusr — members only of the stapusr group may any-privileged modules placed into the /lib/modules/VERSION/systemtap by the system administrator.
• stapusr — members only of the stapusr group may also write and load low-privilege script modules, which are normally limited to manipulating their own processes (and not the kernel, nor other users' processes).

part of the privilege enforcement mechanism may require using a stap-server and administrative trust in its cryptographic signer; see the stap-server(8) manual page for more information. 🔐

on a kernel with FIPS mode enabled, staprun normally refuses to attempt to load systemtap-generated kernel modules. this is because on some kernels, this results in a panic. 💀 if your kernel includes corrections such as linux commit #002c77a48b47, then you can force staprun to attempt module loads anyway, by setting the STAP_FIPS_OVERRIDE environment variable to any value.

---

🎀 FILES 🎀

• /lib/modules/VERSION/systemtap — if MODULE is a module name, the module will be looked for in this directory. users who are only in the 'stapusr' group can install modules located in this directory. this directory must be owned by the root user and must not be world writable. 🗂️

---

💜 SEE ALSO 💜

stap(1), stapprobes(3stap), stap-server(8), stapdyn(8), stapex(3stap)

---

💀 BUGS 💀

use the Bugzilla link of the project web page or our mailing list, bestie:

http://sourceware.org/systemtap/, <systemtap@sourceware.org>

---

and that's the page!! 🌸 written from the System Manager's Manual, filed under STAPRUN(8) — go forth and instrument responsibly, my love 💖✨🫶