UPDATE-BINFMTS
Section: Maintenance Commands (8)
Index
Return to Main Contents
BSD mandoc
NAME
update-binfmts
- maintain registry of executable binary formats
SYNOPSIS
[
options
]
-
-install
name path spec
[
options
]
-
-remove
name path
[
options
]
-
-import
[
name
]
[
options
]
-
-display
[
name
]
[
options
]
-
-enable
[
name
]
[
options
]
-
-disable
[
name
]
[
options
]
-
-find
[
path
]
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).
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
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
Sx 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
Sx 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
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
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
Qq Pf . Ar 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.
- --preserve yes , --preserve no
-
Whether to preserve the original
argv[0]
when running the interpreter, rather than overwriting it with the full path
to the binary.
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
credentials
and
preserve
options correspond to the command-line options of the same names.
EXIT STATUS
- 0
-
The requested action was successfully performed.
- 2
-
Problems were encountered whilst parsing the command line or performing the
action.
EXAMPLES
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'
NOTES
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.
AUTHOR
An -nosplit
is copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010, 2011
An Colin Watson Aq
cjwatson@debian.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.
THANKS
Ian Jackson wrote
update-alternatives
and
dpkg-divert
from which this program borrows heavily.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- COMMON OPTIONS
-
- ACTIONS
-
- BINARY FORMAT SPECIFICATIONS
-
- FORMAT FILES
-
- EXIT STATUS
-
- EXAMPLES
-
- NOTES
-
- AUTHOR
-
- THANKS
-