update-binfmts — maintain registry of executable binary formats

update-binfmts  is  copyright  (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
       Colin Watson <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.

       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.

       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'

       0     The requested action was successfully performed.

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

       update-binfmts — maintain registry of executable binary formats

       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.

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

   COMMONOPTIONS--packagepackage-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.  Similarly, when  removing
             old formats, the --unimport action should be used instead.

       --admindirdirectory
             Specifies  the  administrative  directory,  when  this  is  to  be  different  from  the default of
             /var/lib/binfmts.

       --importdirdirectory
             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--installnamepathspec
             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.

       --removenamepath
             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.

       --unimport [name]
             Unimport  a  packaged format file called name, or unimport 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 --remove option, for symmetry with --import.

       --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.

   BINARYFORMATSPECIFICATIONS--magicbyte-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.

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

       --maskbyte-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.

       --extensionextension
             This matches all files whose names end in ".extension".  Hexadecimal  escapes  are  not  recognized
             here.  Extension matching is case-sensitive.

       --detectorpath
             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
             --fix-binaryyes.

       --credentialsyes, --credentialsno
             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.

       --preserveyes, --preserveno
             Whether  to  preserve the original argv[0] when running the interpreter, rather than overwriting it
             with the full path to the binary.

       --fix-binaryyes, --fix-binaryno
             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 no, 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 --detector, 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.

   FORMATFILES
       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, preserve, and fix_binary options correspond to the  command-line  options  of  the
       same names.

update-binfmts [options] --installnamepathspecupdate-binfmts [options] --removenamepathupdate-binfmts [options] --import [name]
       update-binfmts [options] --unimport [name]
       update-binfmts [options] --display [name]
       update-binfmts [options] --enable [name]
       update-binfmts [options] --disable [name]
       update-binfmts [options] --find [path]

       Ian Jackson wrote update-alternatives and dpkg-divert, from which this program borrows heavily.

Debian                                          January 24, 2011                               UPDATE-BINFMTS(8)