annotate Documentation/binfmt_misc.txt @ 524:7f8b544237bf

netfront: Allow netfront in domain 0.

This is useful if your physical network device is in a utility domain.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Apr 15 15:18:58 2008 +0100 (2008-04-15)
parents 831230e53067
rev   line source
ian@0 1 Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
ian@0 2 =====================================================================
ian@0 3
ian@0 4 This Kernel feature allows you to invoke almost (for restrictions see below)
ian@0 5 every program by simply typing its name in the shell.
ian@0 6 This includes for example compiled Java(TM), Python or Emacs programs.
ian@0 7
ian@0 8 To achieve this you must tell binfmt_misc which interpreter has to be invoked
ian@0 9 with which binary. Binfmt_misc recognises the binary-type by matching some bytes
ian@0 10 at the beginning of the file with a magic byte sequence (masking out specified
ian@0 11 bits) you have supplied. Binfmt_misc can also recognise a filename extension
ian@0 12 aka '.com' or '.exe'.
ian@0 13
ian@0 14 First you must mount binfmt_misc:
ian@0 15 mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
ian@0 16
ian@0 17 To actually register a new binary type, you have to set up a string looking like
ian@0 18 :name:type:offset:magic:mask:interpreter:flags (where you can choose the ':' upon
ian@0 19 your needs) and echo it to /proc/sys/fs/binfmt_misc/register.
ian@0 20 Here is what the fields mean:
ian@0 21 - 'name' is an identifier string. A new /proc file will be created with this
ian@0 22 name below /proc/sys/fs/binfmt_misc
ian@0 23 - 'type' is the type of recognition. Give 'M' for magic and 'E' for extension.
ian@0 24 - 'offset' is the offset of the magic/mask in the file, counted in bytes. This
ian@0 25 defaults to 0 if you omit it (i.e. you write ':name:type::magic...')
ian@0 26 - 'magic' is the byte sequence binfmt_misc is matching for. The magic string
ian@0 27 may contain hex-encoded characters like \x0a or \xA4. In a shell environment
ian@0 28 you will have to write \\x0a to prevent the shell from eating your \.
ian@0 29 If you chose filename extension matching, this is the extension to be
ian@0 30 recognised (without the '.', the \x0a specials are not allowed). Extension
ian@0 31 matching is case sensitive!
ian@0 32 - 'mask' is an (optional, defaults to all 0xff) mask. You can mask out some
ian@0 33 bits from matching by supplying a string like magic and as long as magic.
ian@0 34 The mask is anded with the byte sequence of the file.
ian@0 35 - 'interpreter' is the program that should be invoked with the binary as first
ian@0 36 argument (specify the full path)
ian@0 37 - 'flags' is an optional field that controls several aspects of the invocation
ian@0 38 of the interpreter. It is a string of capital letters, each controls a certain
ian@0 39 aspect. The following flags are supported -
ian@0 40 'P' - preserve-argv[0]. Legacy behavior of binfmt_misc is to overwrite the
ian@0 41 original argv[0] with the full path to the binary. When this flag is
ian@0 42 included, binfmt_misc will add an argument to the argument vector for
ian@0 43 this purpose, thus preserving the original argv[0].
ian@0 44 'O' - open-binary. Legacy behavior of binfmt_misc is to pass the full path
ian@0 45 of the binary to the interpreter as an argument. When this flag is
ian@0 46 included, binfmt_misc will open the file for reading and pass its
ian@0 47 descriptor as an argument, instead of the full path, thus allowing
ian@0 48 the interpreter to execute non-readable binaries. This feature should
ian@0 49 be used with care - the interpreter has to be trusted not to emit
ian@0 50 the contents of the non-readable binary.
ian@0 51 'C' - credentials. Currently, the behavior of binfmt_misc is to calculate
ian@0 52 the credentials and security token of the new process according to
ian@0 53 the interpreter. When this flag is included, these attributes are
ian@0 54 calculated according to the binary. It also implies the 'O' flag.
ian@0 55 This feature should be used with care as the interpreter
ian@0 56 will run with root permissions when a setuid binary owned by root
ian@0 57 is run with binfmt_misc.
ian@0 58
ian@0 59
ian@0 60 There are some restrictions:
ian@0 61 - the whole register string may not exceed 255 characters
ian@0 62 - the magic must reside in the first 128 bytes of the file, i.e.
ian@0 63 offset+size(magic) has to be less than 128
ian@0 64 - the interpreter string may not exceed 127 characters
ian@0 65
ian@0 66 To use binfmt_misc you have to mount it first. You can mount it with
ian@0 67 "mount -t binfmt_misc none /proc/sys/fs/binfmt_misc" command, or you can add
ian@0 68 a line "none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0" to your
ian@0 69 /etc/fstab so it auto mounts on boot.
ian@0 70
ian@0 71 You may want to add the binary formats in one of your /etc/rc scripts during
ian@0 72 boot-up. Read the manual of your init program to figure out how to do this
ian@0 73 right.
ian@0 74
ian@0 75 Think about the order of adding entries! Later added entries are matched first!
ian@0 76
ian@0 77
ian@0 78 A few examples (assumed you are in /proc/sys/fs/binfmt_misc):
ian@0 79
ian@0 80 - enable support for em86 (like binfmt_em86, for Alpha AXP only):
ian@0 81 echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
ian@0 82 echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
ian@0 83
ian@0 84 - enable support for packed DOS applications (pre-configured dosemu hdimages):
ian@0 85 echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register
ian@0 86
ian@0 87 - enable support for Windows executables using wine:
ian@0 88 echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register
ian@0 89
ian@0 90 For java support see Documentation/java.txt
ian@0 91
ian@0 92
ian@0 93 You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable)
ian@0 94 or 1 (to enable) to /proc/sys/fs/binfmt_misc/status or /proc/.../the_name.
ian@0 95 Catting the file tells you the current status of binfmt_misc/the entry.
ian@0 96
ian@0 97 You can remove one entry or all entries by echoing -1 to /proc/.../the_name
ian@0 98 or /proc/sys/fs/binfmt_misc/status.
ian@0 99
ian@0 100
ian@0 101 HINTS:
ian@0 102 ======
ian@0 103
ian@0 104 If you want to pass special arguments to your interpreter, you can
ian@0 105 write a wrapper script for it. See Documentation/java.txt for an
ian@0 106 example.
ian@0 107
ian@0 108 Your interpreter should NOT look in the PATH for the filename; the kernel
ian@0 109 passes it the full filename (or the file descriptor) to use. Using $PATH can
ian@0 110 cause unexpected behaviour and can be a security hazard.
ian@0 111
ian@0 112
ian@0 113 There is a web page about binfmt_misc at
ian@0 114 http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html
ian@0 115
ian@0 116 Richard GŁnther <rguenth@tat.physik.uni-tuebingen.de>