# ktstr
`ktstr` runs ktstr scenarios directly on the host under whatever
scheduler is already active. Unlike `#[ktstr_test]` (which boots
KVM VMs), `ktstr` operates on the host's real topology and cgroups.
It does not manage scheduler lifecycle -- start your scheduler
externally before running.
Build from the workspace:
```sh
cargo build --bin ktstr
```
## Subcommands
### run
Run scenarios on the host:
```sh
ktstr run
ktstr run --flags llc,borrow --duration 30
ktstr run --filter cpuset --json
ktstr run --work-type YieldHeavy
```
Scenarios run under whatever scheduler is currently active on the
host. Start your scheduler before invoking `ktstr run`.
Without `--flags`, all valid flag profiles are generated for each
scenario. With `--flags`, only the specified profile is run. Flags
select which test profiles to run -- they do not configure the
scheduler. Start the scheduler with the desired features before
running ktstr.
`--filter` selects scenarios whose name contains the given substring.
**Flags:** llc, borrow, steal, rebal, reject-pin, no-ctrl.
**Work types:** CpuSpin, YieldHeavy, Mixed, IoSync, Bursty, PipeIo,
FutexPingPong, CachePressure, CacheYield, CachePipe, FutexFanOut.
### list
List available scenarios:
```sh
ktstr list
ktstr list --filter dynamic
ktstr list --json
```
### topo
Show the host CPU topology (CPUs, LLCs, NUMA nodes):
```sh
ktstr topo
```
### cleanup
Remove leftover cgroups from a previous run:
```sh
ktstr cleanup
ktstr cleanup --parent-cgroup /sys/fs/cgroup/ktstr
```
### kernel list
List cached kernel images:
```sh
ktstr kernel list
ktstr kernel list --json
```
### kernel build
Download, build, and cache a kernel image:
```sh
ktstr kernel build 6.14.2
ktstr kernel build 6.15-rc3
ktstr kernel build # latest stable
ktstr kernel build --source ../linux
ktstr kernel build --git https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git --ref v6.14
ktstr kernel build --force 6.14.2
ktstr kernel build --source ../linux --clean
```
Three source modes: positional VERSION (tarball download), `--source PATH`
(local tree), `--git URL --ref REF` (shallow clone). Without arguments,
downloads the latest stable release.
`--force` rebuilds even if a cached image exists. `--clean` runs
`make mrproper` before configuring (local source only). Dirty trees
(uncommitted changes) are built but not cached.
### kernel clean
Remove cached kernel images:
```sh
ktstr kernel clean
ktstr kernel clean --keep 2
ktstr kernel clean --force
```
`--keep N` retains the N most recent entries. Without `--force`,
prompts for confirmation (requires a terminal).
### shell
Boot an interactive shell in a KVM virtual machine:
```sh
ktstr shell
ktstr shell --kernel ../linux
ktstr shell --kernel 6.14.2
ktstr shell --topology 2,4,1
ktstr shell -i /path/to/binary
ktstr shell -i my_tool -i another_tool
```
Launches a VM with busybox and drops into a shell. The `--kernel`
flag accepts the same identifiers as other subcommands (path, version,
cache key). Without `--kernel`, resolves automatically via cache then
filesystem.
`--topology` sets the guest CPU topology as `sockets,cores,threads`
(default: `1,1,1`).
Files and directories passed via `-i`/`--include-files` are available
at `/include-files/<name>` inside the guest. Directories are walked
recursively, preserving structure (e.g. `-i ./release` includes all
files under `release/` at `/include-files/release/...`). Bare names
are resolved via PATH. Dynamically-linked ELF binaries get automatic
shared library resolution.
`--memory-mb` sets guest memory in MB (minimum 128). When absent, memory
is computed from the actual initramfs size after build.
### completions
Generate shell completions:
```sh
ktstr completions bash
ktstr completions zsh
ktstr completions fish
```
Supported shells: bash, zsh, fish, elvish, powershell.