---
name: "stap-onboot"
section: "8"
platform: "linux"
package: "systemtap"
version: "5.6-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/stap-onboot"
---

# stap-onboot(8)

Embed SystemTap scripts into initramfs for early-boot execution

## NAME

stap-onboot - Embed SystemTap scripts into initramfs for early-boot execution

## SYNOPSIS

**stap-onboot** \[*OPTIONS*\] \[*SCRIPT*...\]

## DESCRIPTION

The **stap-onboot** command compiles SystemTap scripts and uses dracut to embed them into an initramfs, allowing the scripts to run during early boot before the root filesystem is mounted. This is useful for debugging early-boot issues or applying CVE band-aid scripts that need to run as early as possible.

Scripts are read from **/etc/systemtap/script.d/**. Compiled modules are cached in **/var/cache/systemtap/*KERNEL*/**.

## OPTIONS

- **-b**

  Backup the existing initramfs before overwriting it. The backup is saved with a *.bak* extension.

- **-c** *configfile*

  Specify an alternate configuration file instead of the default **/etc/systemtap/config**.

- **-o** *path.img*

  Specify the output initramfs file path. By default, the initramfs for the current kernel is updated at **/boot/initramfs-*KERNEL*.img**.

- **-r** *kernelrelease*

  Specify the kernel release to build the initramfs for. Defaults to the currently running kernel (**uname -r**).

## ARGUMENTS

- *SCRIPT*

  One or more script names (without the *.stp* extension) to compile and embed in the initramfs. Scripts must exist in **/etc/systemtap/script.d/**. If no scripts are specified, a clean initramfs without SystemTap scripts is created.

## EXAMPLES

Compile and embed *myScript.stp* into the initramfs, backing up the original: # stap-onboot -b myScript

Create an initramfs for a different kernel: # stap-onboot -r 6.1.0-1.fc37.x86\_64 earlyDebug

Create a custom initramfs in a specific location: # stap-onboot -o /tmp/test-initramfs.img bandaid

Remove all SystemTap scripts from the initramfs: # stap-onboot

## FILES

- **/etc/systemtap/script.d/*SCRIPT*.stp**

  Source SystemTap scripts to be embedded.

- **/etc/systemtap/config**

  Configuration file for script options. Each script can have options defined as *SCRIPTNAME*\_OPT=*...*.

- **/var/cache/systemtap/*KERNEL*/**

  Directory where compiled *.ko* modules are cached.

- **/boot/initramfs-*KERNEL*.img**

  Default output location for the generated initramfs.

- **/usr/lib/dracut/modules.d/99stap**

  Dracut module directory for SystemTap integration.

## SEE ALSO

[*stap*(1)](/stap/1.md), [*staprun*(8)](/staprun/8.md), [*dracut*(8)](/dracut/8.md), [*systemd.service*(5)](/systemd.service/5.md)