139 lines
4.5 KiB
Markdown
139 lines
4.5 KiB
Markdown
# kmod-tui
|
|
|
|
A terminal UI for Linux sysadmins to browse and inspect loaded kernel modules.
|
|
Read-only — built for looking, not for changing module state.
|
|
|
|
## Why
|
|
`lsmod` shows a flat table. `modinfo <mod>` shows one module. This tool gives
|
|
you a navigable, filterable, sorted view of all loaded modules with rich
|
|
per-module detail (license, author, description, parameters, holders,
|
|
dependency info) a keystroke away.
|
|
|
|
## Data sources (read-only)
|
|
- `/proc/modules` — the loaded module list
|
|
- `/sys/module/<name>/` — refcnt, coresize, initsize, initstate, srcversion,
|
|
taint, `parameters/`, `holders/`
|
|
- `modinfo <name>` — filename, license, description, author, depends,
|
|
vermagic, retpoline, intree, signature info (fetched lazily, only when a
|
|
module is selected for detail, so the list view stays fast)
|
|
|
|
## Install
|
|
|
|
**Option 1 — static binary (no toolchain needed)**
|
|
|
|
Grab it from the [v0.1.0 release](https://git.dhvlabs.space/hermes-agent-dhvlabs/kmod-tui/releases/tag/v0.1.0).
|
|
The binary is statically linked (musl) — no glibc, no Rust, no dependencies.
|
|
Runs on any Linux x86_64:
|
|
|
|
```sh
|
|
curl -LO "https://git.dhvlabs.space/hermes-agent-dhvlabs/kmod-tui/releases/download/v0.1.0/kmod-tui-linux-x86_64"
|
|
chmod +x kmod-tui-linux-x86_64
|
|
sudo mv kmod-tui-linux-x86_64 /usr/local/bin/kmod-tui
|
|
kmod-tui
|
|
```
|
|
|
|
Note: this Gitea instance requires sign-in to view/download, so use a browser
|
|
session or embed a token in the URL if scripting it.
|
|
|
|
If you already have the repo on a build box, just scp the binary anywhere:
|
|
|
|
```sh
|
|
scp target/x86_64-unknown-linux-musl/release/kmod-tui user@host:/usr/local/bin/kmod-tui
|
|
```
|
|
|
|
**Option 2 — build from source with rustup** (recommended if you want to hack on it)
|
|
|
|
```sh
|
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
|
cargo build --release
|
|
sudo mv target/release/kmod-tui /usr/local/bin/
|
|
```
|
|
|
|
**Option 3 — distro packages** (`apt install rustc cargo`) — works on Ubuntu
|
|
24.04+ (ships rustc 1.75, ratatui 0.28 needs ≥1.74). Older distros ship rust
|
|
that's too old; use rustup instead.
|
|
|
|
Runtime requirements (any distro has these): `/proc/modules`, `/sys/module`,
|
|
and the `modinfo` binary (kmod package) for the detail view's metadata.
|
|
The list view works without modinfo.
|
|
|
|
## Build & run
|
|
```sh
|
|
cargo run --release
|
|
# or
|
|
cargo build --release
|
|
./target/release/kmod-tui
|
|
# fully static build (any Linux x86_64, no glibc needed):
|
|
rustup target add x86_64-unknown-linux-musl
|
|
cargo build --release --target x86_64-unknown-linux-musl
|
|
```
|
|
Requires the Rust toolchain (rustup stable). No other deps; ratatui/crossterm
|
|
are vendored by cargo.
|
|
|
|
## Keys
|
|
|
|
List view:
|
|
```
|
|
j / ↓ move down
|
|
k / ↑ move up
|
|
g / Home top
|
|
G / End bottom
|
|
PgDn / PgUp scroll by 10
|
|
Enter open full-detail screen for the selected module
|
|
/ start filtering by module name (type, Esc to clear)
|
|
s cycle sort: name → size → refcnt → dependents
|
|
r refresh the module list from /proc/modules
|
|
? toggle help overlay
|
|
q quit
|
|
```
|
|
|
|
Full-detail view:
|
|
```
|
|
j / ↓ , k / ↑ move selection (stays in full-detail, reloads detail)
|
|
Esc / q back to list
|
|
? help
|
|
```
|
|
|
|
Filter mode (after `/`):
|
|
```
|
|
type append to filter
|
|
Backspace delete last char
|
|
Enter / Esc exit filter (Esc also clears)
|
|
```
|
|
|
|
## Layout
|
|
- Top bar: module count + kernel version + current sort/filter.
|
|
- Middle: scrollable module table (#, name, size, refcnt, used-by, state).
|
|
- Bottom: two-column detail pane for the highlighted module.
|
|
- Footer: key hints (context-sensitive).
|
|
|
|
## Architecture
|
|
```
|
|
src/
|
|
main.rs CLI bootstrap, event loop, key dispatch
|
|
app.rs App state: module list, cursor, filter, sort, view mode, lazy fetches
|
|
event.rs crossterm input polling
|
|
model.rs Module/ModInfo types, /proc + /sys collection, modinfo parsing, tests
|
|
ui/
|
|
mod.rs frame composition, status bar, footer, help overlay
|
|
list.rs module table
|
|
detail.rs detail pane + full-detail screen
|
|
```
|
|
|
|
## Tests
|
|
```sh
|
|
cargo test --release
|
|
```
|
|
Unit tests cover the /proc/modules `used-by` parser, the `modinfo` output
|
|
parser, and the human-readable size formatter.
|
|
|
|
## Non-goals (v1)
|
|
- Writing module parameters or loading/unloading modules — read-only by design.
|
|
- Showing all installable (not-yet-loaded) modules — planned for v1.1.
|
|
- Remote hosts — local only.
|
|
|
|
## Roadmap
|
|
- v1.1: dependency tree view, all-available-modules toggle, CSV/TSV export,
|
|
config file (`~/.config/kmod-tui/config.toml`).
|
|
- v2: optional inotify auto-refresh on `/proc/modules`.
|