Skip to main content

Crate reverie_preload

Crate reverie_preload 

Source
Expand description

Shared LD_PRELOAD + seccomp/SIGSYS instrumentation runtime for Reverie’s ld-preload backends (e9patch and liteinst).

This crate factors the primitives every ld-preload backend needs out of any one backend so they are written and reviewed once:

  • seccomp — the trap-everything-but-the-trusted-gate BPF filter;
  • trap — the trusted syscall gate, the SIGSYS handler, and dispatcher registration;
  • dispatch — the SyscallDispatcher seam and the shared fail-closed PassthroughDispatcher;
  • fork — fork-following (the filter is inherited atomically; only per-process state must be reset);
  • signal — signal multiplexing / reserved-signal policy;
  • sync — the async-signal-safe SpinMutex the in-guest tool hosts use for RPC and per-thread state;
  • lifecycle — the LifecycleController seam that makes switching to a hybrid in-process-trap + ptrace backend an additive change rather than a rewrite;
  • [rpc] (feature coordinator-rpc) — a synchronous coordinator RPC client wire-compatible with the async reverie-rpc-transport;
  • [tool_host] (feature coordinator-rpc) — the backend-agnostic driver that polls an in-guest Reverie tool’s async handlers with a no-op waker and carries the shared ERESTARTSYS restart protocol.

§Coverage boundaries

Established by the research-ldpreload-derisking task and enforced here: this runtime is for trusted, dynamically linked, non-AT_SECURE, no-exec x86-64 guests. It does not cover vDSO fast paths, the ~40 loader/startup syscalls before the constructor runs, static binaries, or execve. fork is fully covered because the kernel inherits the filter atomically.

§Two ways to use it

  • As a library (rlib): e9patch/liteinst embed the runtime, register a custom SyscallDispatcher, and call install.
  • As a standalone LD_PRELOAD (cdylib): set REVERIE_PRELOAD_TOOL and preload libreverie_preload.so; the constructor installs a built-in tool.

Modules§

dispatch
The dispatcher seam: how a backend or tool handles a trapped syscall.
fmt
Async-signal-safe line formatting.
fork
Fork-following.
lifecycle
The lifecycle-controller seam.
seccomp
Classic-BPF seccomp filter for LD_PRELOAD instrumentation.
signal
Signal multiplexing between the runtime and the guest.
sync
Async-signal-safe synchronization primitives for the in-guest tool hosts.
trap
The syscall trap: trusted gate, SIGSYS handler, and dispatcher registration.

Enums§

BuiltinTool
The built-in tools the standalone LD_PRELOAD cdylib can install.

Constants§

LIB_ENV
Environment variable overriding the located preload library path.
SPOOF_PID
The value BuiltinTool::SpoofGetpid returns for getpid.
TOOL_ENV
Environment variable selecting a built-in tool for the standalone cdylib.

Functions§

configure_command
Configure command to load the runtime and select a built-in tool.
initialize_from_environment
Read TOOL_ENV and, if it names a built-in tool, install the runtime.
install⚠
Install the runtime with a caller-provided dispatcher and controller.
install_builtin⚠
Install a built-in tool with the default in-process controller.
preload_library_path
Locate the preload cdylib beside the current executable, or via LIB_ENV.
reverie_preload_initialize⚠
Constructor entry point invoked by the dynamic loader for the cdylib.