MINI-INIT-ASM(1)

📦 version 0.3.1, in ubuntu stonking

💖 MINI-INIT-ASM 💖

okay bestie, sit down, because we're talking about mini-init-asm — your tiny PID 1 init for containers, written in pure assembly (yes, she's built different) ✨

🎀 NAME 🎀

mini-init-asm — a teeny tiny PID 1 init for containers, and it's written in pure assembly 💅

🦋 SYNOPSIS 🦋

mini-init-asm [-v|--verbose] [-V|--version] -- command [args...]

🌸 DESCRIPTION 🌸

So like, mini-init-asm is a tiny init made for container entrypoints — that's her whole job and she does it flawlessly 🫶

Here's the tea, fr fr:

  • She spawns exactly one main child process, in a new session and a new process group.
  • She forwards signals to the entire group.
  • She reaps children. (somebody has to, and it's giving responsible queen energy 👑)

She optionally supports subreaper mode and a simple restart-on-crash loop, if you're into that 🌈

Also, heads up: upstream builds currently produce architecture-named binaries — mini-init-amd64 and mini-init-arm64. Debian packaging typically installs the active architecture binary as mini-init-asm(1). iykyk 💜

✨ OPTIONS ✨

Short list, but she's iconic:

  • -v, --verbose — turn on verbose diagnostics on stderr. she gets chatty 💬
  • -V, --version — print the version and dip out. bye 👋

🧚 ENVIRONMENT 🧚

Okay so a whole vibe check here first: all numeric environment variables are parsed as non-negative decimal integers. Invalid values? Ignored, defaults apply. no drama, no crash, she just moves on 💅

💖 EP_GRACE_SECONDS

Grace period (in seconds) after the first shutdown signal (TERM/INT/HUP/QUIT) before escalating to SIGKILL.

Default: 10.

10 seconds of grace and then she's done being nice, periodt 💀

💖 EP_SIGNALS

A comma-separated list of additional signals to monitor and forward. Tokens are trimmed for surrounding spaces (so yes, you can be messy with your spaces, she'll forgive you 🎀).

Supported named tokens: USR1, USR2, PIPE, WINCH, TTIN, TTOU, CONT, ALRM

Supported numeric tokens: decimal signal numbers 1..64 — but note that SIGKILL and SIGSTOP are ignored. they don't play that game 🙈

Supported real-time tokens: RT1..RT30 (maps to SIGRTMIN+N), and these only work if EP_SIGRTMIN and EP_SIGRTMAX are set and valid.

Unknown tokens are ignored, with a warning in verbose mode. no cap.

💖 EP_SIGRTMIN

Decimal runtime value of SIGRTMIN for the target libc environment. Required to enable RT* tokens in EP_SIGNALS.

💖 EP_SIGRTMAX

Decimal runtime value of SIGRTMAX for the target libc environment. Required to enable RT* tokens in EP_SIGNALS.

The rationale, bestie: per signal(7), SIGRTMIN/SIGRTMAX can vary at runtime in some libcs (e.g. glibc with threads), so hard-coded RT numbering is unsafe. don't do it. she said what she said 🌸

💖 EP_SUBREAPER

If set to 1, enable PR_SET_CHILD_SUBREAPER so that mini-init-asm adopts orphaned descendants 🥺 (she takes them in, she's a giver).

The init still exits when the main child exits, though.

Default: 0.

💖 EP_EXIT_CODE_BASE

Base exit code for signal deaths: exit_code = base + signal_number.

Default: 128 (shell-compatible, love that for her). Valid range: 0..255.

💖 EP_RESTART_ENABLED

If set to 1, restart the child only if it died due to a signal and shutdown has not started.

Default: 0.

💖 EP_MAX_RESTARTS

Maximum number of restarts when restart is enabled. 0 means unlimited.

Default: 0.

💖 EP_RESTART_BACKOFF_SECONDS

Seconds to wait before restarting after a crash. 0 restarts immediately (chaotic, but valid ✨).

Default: 1.

💖 EP_ARM64_FALLBACK

The ARM64/QEMU workaround: if set to 1, she skips the epoll/signalfd loop and uses a simpler wait4-only path.

This mode primarily validates spawn and exit-code propagation.

Default: 0.

🌈 SIGNAL FORWARDING 🌈

The child is started as a new session leader and process group leader. When a signal is received, mini-init-asm forwards it to the entire child process group via kill(2) with a negative pid — that's kill(-pgid, sig), literally.

On the first shutdown signal (TERM/INT/HUP/QUIT), a grace timer is armed; when it expires and the child group is still present, SIGKILL is sent to the group. she warned you 💅

🔥 EXIT STATUS 🔥

  • If the child exits normally, mini-init-asm exits with the child exit status.
  • If the child dies due to a signal, mini-init-asm exits with EP_EXIT_CODE_BASE + signal number.
  • If mini-init-asm escalates to SIGKILL after the grace period, it exits as if the child died to SIGKILL.

⭐ EXAMPLES ⭐

Run a command under the init:

mini-init-asm -- /bin/sh -c 'echo hello; sleep 5'

Forward an additional numeric signal (SIGTRAP=5):

EP_SIGNALS=5 mini-init-asm -- /bin/sh -c 'trap "echo got TRAP; exit 0" TRAP; sleep 1000'

Enable RT tokens (values must match the target libc runtime):

EP_SIGRTMIN=34 EP_SIGRTMAX=64 EP_SIGNALS=RT1,RT5 mini-init-asm -- /bin/sh -c 'sleep 1000'

Restart-on-crash with backoff:

EP_RESTART_ENABLED=1 EP_MAX_RESTARTS=5 EP_RESTART_BACKOFF_SECONDS=2 \
  mini-init-asm -- ./your-app

💀 NOTES 💀

  • To discover SIGRTMIN/SIGRTMAX inside an image, one option is:
python3 -c 'import signal; print(signal.SIGRTMIN, signal.SIGRTMAX)'

👑 SEE ALSO 👑

signal(7), signalfd(2), epoll(7), timerfd_create(2), prctl(2), kill(2), wait4(2)

okay that's the whole thing, you're officially caught up 🫶 this was mini-init-asm version 0.3.1, dated 2026-01-11, and she ate, no crumbs left 💅✨🎀 stay tiny, stay init, mwah 💖

📦 where this page comes from