man-page

Versions 2.1.43 and later of the Linux kernel have contained the binfmt_misc module. This enables a system administrator to register interpreters for various binary formats based on a magic number or their file extension, and cause the appropriate interpreter to be invoked whenever a matching file is executed. Think of it as a more flexible version of the #! executable interpreter mechanism, or as something which can behave a little like "associations" in certain other operating systems (though in GNU/Linux the tendency is to keep this sort of thing somewhere else, like your file manager).

manages a persistent database of these interpreters.

When each package providing a registered interpreter is installed, changed, or removed,

is called to update information about that interpreter.

is usually called from the

scripts in Debian packages.

Exactly one action must be specified; this may be accompanied by any one of the common options.

Specifies the name of the current package, to be used by package post-installation and pre-removal scripts. System administrators installing binary formats for local use should probably ignore this option.

When installing new formats, the

action should be used instead. Similarly, when removing old formats, the

action should be used instead.

Specifies the administrative directory, when this is to be different from the default of

Specifies the directory from which packaged binary formats are imported, when this is to be different from the default of

Don't do anything, just demonstrate what would be done.

Display some usage information.

Display version information.

Install a binary format identified by

with interpreter

into the database. After registration, this format will be used when the kernel tries to execute a file matching

(see

below).

will attempt to enable this binary format in the kernel as well as adding it to its own database; see

below.

You cannot install a format with any of the names ".", "..", "register", or "status", as these are used by the filesystem or the binfmt_misc module.

Remove the binary format identified by

with interpreter

from the database. This will also attempt to disable the binary format in the kernel; see

below.

Import a packaged format file called

or import all format files currently on the system if no

is given. If

is not a full path, it is assumed to be a file in the import directory

by default). See

below for the required contents of these files.

For packages, this is preferable to using the

option, as a format file can be installed without

needing to be available.

Unimport a packaged format file called

or unimport all format files currently on the system if no

is given. If

is not a full path, it is assumed to be a file in the import directory

by default). See

below for the required contents of these files.

For packages, this is preferable to using the

option, for symmetry with

Display any information held in the database about the binary format identifier

or about all known binary formats if no

is given. Also show whether displayed binary formats are enabled or disabled.

Enable binary format

or all known binary formats if no

is given, in the kernel, thus enabling direct execution of matching files. You must have binfmt_misc compiled into the kernel or loaded as a module for this to work.

Disable binary format

or all known binary formats if no

is given, in the kernel, thus disabling direct execution of matching files. You must have binfmt_misc compiled into the kernel or loaded as a module for this to work.

Print the list of interpreters that will be tried in sequence when attempting to execute

one per line. The first one for which

succeeds will be used.

Note that if multiple formats match an executable, then the order is in general not defined, and may not be preserved between

operations, so you should generally try to ensure that this option prints at most one line for any given

The exception to this is that any format with a userspace detector will be run before any format without a userspace detector.

This matches all files with the magic number

Hexadecimal escapes may be included in the

by preceding them with \x, for example

for a linefeed. Remember to protect such escapes with quotes or an additional backslash to prevent their interpretation by the shell.

Also see

and

This is the offset of the magic/mask in the file, counted in bytes. The default is 0. Only valid with

This mask will be logically-ANDed with the string to be checked against the magic number given with

The default is all 0xff, i.e. no effect. Only valid with

This matches all files whose names end in

Hexadecimal escapes are not recognized here. Extension matching is case-sensitive.

If this option is used, a userspace detector program will be used to check whether the file is suitable for this interpreter. This may be used when the binary format is more complex than can be handled by the kernel's format specifications alone. The program should return an exit code of zero if the file is appropriate and non-zero otherwise. This option cannot be used together with

Whether to keep the credentials of the original binary to run the interpreter; this is typically useful to run setuid binaries, but has security implications.

Whether to preserve the original

when running the interpreter, rather than overwriting it with the full path to the binary.

Whether to open the interpreter binary immediately and always use the opened image. This allows the interpreter from the host to be used regardless of usage in chroots or different mount namespaces. The default behaviour is

meaning that the kernel should open the interpreter binary lazily when needed. This option requires Linux 4.8 or newer. It cannot be used together with

or with multiple binary formats that share the same magic number, since the kernel will only open a single interpreter binary which will then not be able to detect and execute the real interpreter from inside a chroot or from a different mount namespace.

A format file is a sequence of options, one per line, corresponding roughly to the options given to an

command. Each option consists of a key, followed by whitespace, followed by a value.

The

option should be set to the current package. The

option should be set to the path to the interpreter that will handle this binary format. The

and

options correspond to the command-line options of the same names.

The requested action was successfully performed.

Problems were encountered whilst parsing the command line or performing the action.

This format file can be used with an interpreter capable of handling Java .class files:

package javawrapper interpreter /usr/bin/javawrapper magic \xca\xfe\xba\xbe

This corresponds roughly to the following command:

update-binfmts --package javawrapper \ --install javawrapper /usr/bin/javawrapper \ --magic '\xca\xfe\xba\xbe'

If you're not careful, you can break your system with

An easy way to do this is to register an ELF binary as a handler for ELF, which will almost certainly cause your system to hang immediately; even if it doesn't, you won't be able to run

to fix it. In the future

may have some checks to prevent this sort of thing happening accidentally, though of course you can still manipulate the binfmt_misc kernel module directly.

See the GNU General Public License version 3 or later for copying conditions.

You can find the GNU GPL v3 in

on any modern Debian system.

Richard Guenther wrote the binfmt_misc kernel module.

Ian Jackson wrote

and

from which this program borrows heavily.