BINMISCCTL(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 BINMISCCTL(8) — like, the manual page for `binmiscctl` (System Manager's Manual) 🎀

okay bestie, gather round, because this one is genuinely iconic — we're talking about teaching your kernel to recognize other kinds of binaries and hand them off to an interpreter. no cap, it's giving "multiverse of executables." 🌈

✨ NAME ✨

binmiscctl — manage binary image activators 🦋

🌸 SYNOPSIS 🌸

binmiscctl add name --interpreter path --magic magic --size size
           [--mask mask] [--offset offset] [--set-enabled] [--pre-open]
binmiscctl disable name
binmiscctl enable name
binmiscctl list
binmiscctl lookup name
binmiscctl remove name

💖 DESCRIPTION 💖

The binmiscctl utility is the management utility for configuring miscellaneous binaries image activators in the kernel. like, it's the group chat admin of binary formats ✨. It lets you add, delete, disable, enable, and look up interpreters. Also, all the interpreters can be listed. we love a full roster.

The first argument on the command line indicates the operation to be performed. Operation must be one of the following, bestie:

add name --interpreter path --magic magic --size size [--mask mask] [--offset offset] [--set-enabled] [--pre-open] — add a new activator entry in the kernel. You must specify a unique name, a path to the interpreter, header magic bytes that uniquely identify a suitable binary for the activator, and the size of the magic in bytes. (yes, all four. no skipping, that's the whole vibe check.)
- Optionally, you may specify a mask to do a bitwise AND with the header bytes. This effectively allows you to ignore fields in the binary header that do not uniquely identify the binary file's type. it's a filter, it's a glow-up for your matching logic 💅
- An offset may be specified for the magic bytes using the --offset option. By default the offset is zero. (zero is the default and zero is also the energy we're bringing to the first byte.)
- To enable the activator entry the --set-enabled option is used. The activator default state is disabled — so yes, you gotta opt in. 🙈
- To make the interpreter automatically available in jails and chroots, use the --pre-open option to allow the kernel to open the binary at configuration time rather then lazily when the interpreted program is started. (early bird gets the open file descriptor 🐦)
- The interpreter path may also contain arguments for the interpreter including #a which gets replaced by the old argv0 value in the interpreter string. so your interpreter can cosplay as the binary it's running. main character energy fr fr 👑
disable name — disable the activator entry identified with name. it's on read-only mode, it's taking a nap 😴
enable name — enable the activator entry identified with name. welcome back to the function, queen 👑
list — take a snapshot and print all the activator entries currently configured. it's the full photo dump 📸
lookup name — look up and print out the activator entry identified with name. one specific entry, served fresh 🍓
remove name — remove the activator entry identified with name. it's giving unfollow, block, delete 💀

🔥 EXAMPLES 🔥

Add an image activator to run the LLVM interpreter (lli(1)) on bitcode compiled files and set its state to enabled. In this example #a is replaced with the old argv0 value so that lli(1) can fake its argv0:

      # binmiscctl add llvmbc --interpreter ''/usr/bin/lli \
        --fake-argv0=#a'' --magic ''BC\xc0\xde'' --size 4 \
        --set-enabled

Set the state of the llvmbc image activator to disabled:

      # binmiscctl disable llvmbc

Set the state of the llvmbc image activator to enabled:

      # binmiscctl enable llvmbc

Delete the llvmbc image activator:

      # binmiscctl remove llvmbc

Look up and list the record for the llvmbc image activator:

      # binmiscctl lookup llvmbc

Add QEMU bsd-user program as an image activator for ARM AARCH64 binaries:

      # binmiscctl add arm64 \
        --interpreter "/usr/local/bin/qemu-aarch64-static" \
        --magic "\x7f\x45\x4c\x46\x02\x01\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x02\x00\xb7\x00" \
        --mask  "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                 \xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff" \
        --size 20 --set-enabled

Add QEMU bsd-user program as an image activator for ARM little-endian binaries:

      # binmiscctl add armelf \
        --interpreter "/usr/local/bin/qemu-arm-static" \
        --magic "\x7f\x45\x4c\x46\x01\x01\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x02\x00\x28\x00" \
        --mask  "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                 \xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff" \
        --size 20 --set-enabled

Add QEMU bsd-user program as an image activator for ARM big-endian binaries:

      # binmiscctl add armebelf \
        --interpreter "/usr/local/bin/qemu-arm-static" \
        --magic "\x7f\x45\x4c\x46\x01\x02\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x00\x02\x00\x28" \
        --mask  "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                 \xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff" \
        --size 20 --set-enabled

Add QEMU bsd-user program as an image activator for MIPS32 binaries:

      # binmiscctl add mips32 \
        --interpreter "/usr/local/bin/qemu-mips-static" \
        --magic "\x7f\x45\x4c\x46\x01\x02\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x00\x02\x00\x08" \
        --mask  "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                 \xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff" \
        --size 20 --set-enabled

Add QEMU bsd-user program as an image activator for MIPS64 binaries:

      # binmiscctl add mips64 \
        --interpreter "/usr/local/bin/qemu-mips64-static" \
        --magic "\x7f\x45\x4c\x46\x02\x02\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x00\x02\x00\x08" \
        --mask "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                \xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff" \
        --size 20 --set-enabled

Add QEMU bsd-user program as an image activator for PowerPC binaries:

      # binmiscctl add powerpc \
        --interpreter "/usr/local/bin/qemu-ppc-static" \
        --magic "\x7f\x45\x4c\x46\x01\x02\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x00\x02\x00\x14" \
        --mask  "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                 \xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff" \
        --size 20 --set-enabled

Add QEMU bsd-user program as an image activator for PowerPC64 binaries:

      # binmiscctl add powerpc64 \
        --interpreter "/usr/local/bin/qemu-ppc64-static" \
        --magic "\x7f\x45\x4c\x46\x02\x02\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x00\x02\x00\x15" \
        --mask  "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                 \xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff" \
        --size 20 --set-enabled

Add QEMU bsd-user program as an image activator for 64-bit RISC-V binaries:

      # binmiscctl add riscv64 \
        --interpreter "/usr/local/bin/qemu-riscv64-static" \
        --magic "\x7f\x45\x4c\x46\x02\x01\x01\x00\x00\x00\
                 \x00\x00\x00\x00\x00\x00\x02\x00\xf3\x00" \
        --mask  "\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\
                 \xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff" \
        --size 20 --set-enabled

🧚 Create and use an ARMv7 chroot on an AMD64 host

Use an existing source tree to build a chroot host with architecture overrides:

D=/path/to/chroot
cd /usr/src
mkdir -p $D
make world TARGET=arm TARGET_ARCH=armv7 DESTDIR=$D
make distribution TARGET=arm TARGET_ARCH=armv7 DESTDIR=$D

With emulators/qemu-user-static from the FreeBSD Ports Collection, the emulator must be copied into the jail path specified in the binmiscctl command. Using the example above:

mkdir $D/usr/local/bin
cp /usr/local/bin/qemu-arm-static $D/usr/local/bin

Now the user can chroot into the environment normally, as root:

chroot $D

ngl this part is the actual slay — cross-arch chroot on an AMD64 host. your laptop is now multilingual 💜

🫶 SEE ALSO 🫶

lli(1), execve(2), jail(8)

⭐ HISTORY ⭐

The binmiscctl command was added in FreeBSD 10.1. It was developed to support the imgact_binmisc kernel module. glow-up origin story, honestly 🌟

👑 AUTHORS 👑

Stacey D Son <sson@FreeBSD.org>

aaaand that's the whole page, bestie — no notes, ate, periodt. 💅✨ this beauty came from Debian, dated April 30, 2020, closing out as BINMISCCTL(8). go forth and activate some misc binaries 🎀🦋🌸

📦 where this page comes from

freebsd 14.5: base 14.5
freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms