update-binfmts
maintain registry of executable binary formats
Synopsis
update-binfmts
[options] --install name path
spec
update-binfmts [options]
--remove name path
update-binfmts [options]
--import [name]
update-binfmts [options]
--display [name]
update-binfmts [options]
--enable [name]
update-binfmts [options]
--disable [name]
update-binfmts [options]
--find [path]
add an example, a script, a trick and tips
examples
0
The requested action was successfully performed.
2
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'
source
chmod 755 /usr/local/bin/gorun
update-binfmts --install go /usr/local/bin/gorun
--extension go
source
sudo yum install wine
update-binfmts --install wine /usr/bin/wine --extension
exe
source
which update-binfmts >/dev/null 2>&1
|| exit 0
. /lib/lsb/init-functions
[ -r /etc/default/rcS ] && . /etc/default/rcS
log_daemon_msg "Enabling $DESC"
"$NAME"
update-binfmts --enable ||
CODE=$?
log_end_msg $CODE
exit $CODE
;;
stop)
if init_is_upstart; then
source
mask="\xff\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff"
update-binfmts --install $name
/usr/bin/qemu-m68k \
--magic $magic --mask $mask
source
which update-binfmts >/dev/null 2>&1
|| exit 0
. /lib/lsb/init-functions
[ -r /etc/default/rcS ] && . /etc/default/rcS
if [ "$cachefail" = 1 ]; then
update-binfmts --enable ||
CODE=$?
fi
log_end_msg $CODE
exit $CODE
;;
stop)
source
if which update-binfmts
>/dev/null; then
# try to remove and ignore the error
if [ -e
/var/lib/binfmts/jar ]; then
update-binfmts --package oracle-java7 --remove jar
/usr/bin/jexec || true
fi
description
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).
update-binfmts manages a persistent database of
these interpreters.
When each
package providing a registered interpreter is installed,
changed, or removed, update-binfmts is called
to update information about that interpreter.
update-binfmts is usually called from the
postinst or prerm scripts in Debian
packages.
options
Exactly one action must be
specified; this may be accompanied by any one of the common
options.
COMMON
OPTIONS
--package package-name
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 --import action should
be used instead.
--admindir
directory
Specifies the administrative
directory, when this is to be different from the default of
/var/lib/binfmts.
--importdir
directory
Specifies the directory from
which packaged binary formats are imported, when this is to
be different from the default of
/usr/share/binfmts.
--test
Don’t do anything, just
demonstrate what would be done.
--help
Display some usage
information.
--version
Display version
information.
ACTIONS
--install name path spec
Install a binary format
identified by name with interpreter path into
the database. After registration, this format will be used
when the kernel tries to execute a file matching spec
(see BINARY FORMAT SPECIFICATIONS below).
--install
will attempt to enable this binary format in the kernel as
well as adding it to its own database; see
--enable 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
name path
Remove the binary format
identified by name with interpreter path from
the database. This will also attempt to disable the binary
format in the kernel; see --disable
below.
--import
[name]
Import a packaged format file
called name, or import all format files currently on
the system if no name is given. If name is not
a full path, it is assumed to be a file in the import
directory (/usr/share/binfmts by default). See
FORMAT FILES below for the required contents of these
files.
For packages,
this is preferable to using the --install
option, as a format file can be installed without
update-binfmts needing to be available.
--display
[name]
Display any information held in
the database about the binary format identifier name,
or about all known binary formats if no name is
given. Also show whether displayed binary formats are
enabled or disabled.
--enable
[name]
Enable binary format
name, or all known binary formats if no name
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
[name]
Disable binary format
name, or all known binary formats if no name
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.
--find
[path]
Print the list of interpreters
that will be tried in sequence when attempting to execute
path, one per line. The first one for which execvp(3)
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
update-binfmts operations, so you should
generally try to ensure that this option prints at most one
line for any given path. The exception to this is
that any format with a userspace detector will be run before
any format without a userspace detector.
BINARY FORMAT
SPECIFICATIONS
--magic byte-sequence
This matches all files with the
magic number byte-sequence. Hexadecimal escapes may
be included in the byte-sequence by preceding them
with \x, for example ’\x0a’ for a linefeed.
Remember to protect such escapes with quotes or an
additional backslash to prevent their interpretation by the
shell.
Also see
--offset and
--mask.
--offset
offset
This is the offset of the
magic/mask in the file, counted in bytes. The default is 0.
Only valid with --magic.
--mask
byte-sequence
This mask will be
logically-ANDed with the string to be checked against the
magic number given with --magic. The
default is all 0xff, i.e. no effect. Only valid with
--magic.
--extension
extension
This matches all files whose
names end in ".extension". Hexadecimal
escapes are not recognized here. Extension matching is
case-sensitive.
--detector
path
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.
--credentials
yes, --credentials no
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.
FORMAT
FILES
A format file is a sequence of options, one per line,
corresponding roughly to the options given to an
--install command. Each option consists
of a key, followed by whitespace, followed by a value.
The
package option should be set to the current package.
The interpreter option should be set to the path to
the interpreter that will handle this binary format. The
magic, offset, mask, extension,
detector, and credentials options correspond
to the command-line options of the same names.
notes
If you’re not careful, you can break your system with
update-binfmts. 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 update-binfmts to fix it. In the
future update-binfmts 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.
thanks
Ian Jackson wrote update-alternatives and
dpkg-divert, from which this program borrows heavily.
Debian January 24, 2011 Debian
author
update-binfmts is
copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006,
2007, 2008, 2009, 2010, 2011 Colin Watson
<cjwatson[:at:]debian[:dot:]org>. See the GNU General Public
License version 3 or later for copying conditions.
You can find the
GNU GPL v3 in
/usr/share/common-licenses/GPL-3 on any
modern Debian system.
Richard Guenther
wrote the binfmt_misc kernel module.