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