update-binfmts

update-binfmts [options] --import
update-binfmts [options] --register <name> <interpreter> <flags> <offset> <magic> <mask>
update-binfmts [options] --unregister <name>
update-binfmts [options] --enable <name>
update-binfmts [options] --disable <name>
update-binfmts [options] --remove <name>
update-binfmts [options] --display [<name>]

--import
    Reads all configuration files from /etc/binfmt.d and other standard directories and registers their defined binary formats with the kernel. This is the most common operational mode.

--register <name> <interpreter> <flags> <offset> <magic> <mask>
    Registers a new binary format.
<name>: A unique identifier for the format.
<interpreter>: Path to the executable that can interpret this format (e.g., QEMU).
<flags>: Optional flags (e.g., 'P' for preserved, 'C' for credentials, 'F' for fixed, 'B' for no core dump).
<offset>: Byte offset where the magic number is located.
<magic>: Hexadecimal string representing the magic number.
<mask>: Hexadecimal string mask to apply to the magic number for matching.

--unregister <name>
    Unregisters the specified binary format from the kernel.

--enable <name>
    Enables a previously registered or disabled binary format. The format must exist in configuration.

--disable <name>
    Disables an active binary format. The format remains registered but will not be used by the kernel.

--remove <name>
    Removes the specified binary format registration from both the kernel and its configuration file.

--display [<name>]
    Displays information about currently registered binary formats. If <name> is provided, displays details for that specific format.

-v, --verbose
    Increases verbosity, showing more details about operations.

-q, --quiet
    Suppresses output messages.

-f, --force
    Forces the operation, overriding certain warnings or conditions.

-a, --all
    Used with --enable, --disable, or --remove to apply the action to all currently configured binary formats.

The update-binfmts command is a utility used to manage the registration and unregistration of foreign binary formats with the Linux kernel's binfmt_misc module.

This system allows the kernel to recognize and execute non-native executables, such as ARM binaries on an x86 system, by automatically invoking a specified interpreter (like a QEMU static binary). It reads configuration files typically found in /etc/binfmt.d/ and /usr/lib/binfmt.d/, then writes the corresponding rules to the /proc/sys/fs/binfmt_misc pseudo-filesystem.

update-binfmts is essential for setting up cross-architecture execution environments and is often invoked automatically during package installations or system boot via services like systemd-binfmt.service.

• Requires the binfmt_misc kernel module to be loaded.
• Requires superuser privileges (root) to register, unregister, enable, or disable formats.
• Incorrect magic numbers or masks can lead to misidentification or failure to execute foreign binaries.
• The specified interpreter must be present and executable on the system.

Binary format definitions are stored in plain text files, typically under /etc/binfmt.d/ and /usr/lib/binfmt.d/ (and potentially /run/binfmt.d/ and /var/lib/binfmt.d/). Each file usually defines one format per line, following a specific syntax. For example, a configuration line might look like:
:arm:M:0:\x7fELF\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x28\x00:/usr/bin/qemu-arm-static
The update-binfmts --import command parses these files to configure the kernel.

The update-binfmts command interacts with the kernel through the binfmt_misc pseudo-filesystem, which is typically mounted at /proc/sys/fs/binfmt_misc. Each registered format corresponds to an entry in this directory (e.g., /proc/sys/fs/binfmt_misc/arm). Writing to special files within this directory allows registration, unregistration, and control over formats. update-binfmts provides a user-friendly interface over these kernel-level operations.

The concept of binfmt_misc was introduced into the Linux kernel to provide a generic mechanism for supporting arbitrary executable formats. The update-binfmts utility emerged as a standardized tool to manage these registrations, particularly in Debian-based systems where it's often part of the binfmt-support package or integrated with dpkg for package management. With the advent of systemd, its integration expanded, with systemd-binfmt.service now commonly triggering update-binfmts --import during boot to ensure all configured formats are active.

binfmt_misc(4), systemd-binfmt.service(8), qemu-user-static(1)