blob: ec83bbce547a5c3bdf1b4f7c35c9dc515c41c767
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 ':' |
19 | upon your needs) and echo it to /proc/sys/fs/binfmt_misc/register. |
20 | |
21 | Here is what the fields mean: |
22 | - 'name' is an identifier string. A new /proc file will be created with this |
23 | name below /proc/sys/fs/binfmt_misc; cannot contain slashes '/' for obvious |
24 | reasons. |
25 | - 'type' is the type of recognition. Give 'M' for magic and 'E' for extension. |
26 | - 'offset' is the offset of the magic/mask in the file, counted in bytes. This |
27 | defaults to 0 if you omit it (i.e. you write ':name:type::magic...'). Ignored |
28 | when using filename extension matching. |
29 | - 'magic' is the byte sequence binfmt_misc is matching for. The magic string |
30 | may contain hex-encoded characters like \x0a or \xA4. Note that you must |
31 | escape any NUL bytes; parsing halts at the first one. In a shell environment |
32 | you might have to write \\x0a to prevent the shell from eating your \. |
33 | If you chose filename extension matching, this is the extension to be |
34 | recognised (without the '.', the \x0a specials are not allowed). Extension |
35 | matching is case sensitive, and slashes '/' are not allowed! |
36 | - 'mask' is an (optional, defaults to all 0xff) mask. You can mask out some |
37 | bits from matching by supplying a string like magic and as long as magic. |
38 | The mask is anded with the byte sequence of the file. Note that you must |
39 | escape any NUL bytes; parsing halts at the first one. Ignored when using |
40 | filename extension matching. |
41 | - 'interpreter' is the program that should be invoked with the binary as first |
42 | argument (specify the full path) |
43 | - 'flags' is an optional field that controls several aspects of the invocation |
44 | of the interpreter. It is a string of capital letters, each controls a |
45 | certain aspect. The following flags are supported - |
46 | 'P' - preserve-argv[0]. Legacy behavior of binfmt_misc is to overwrite |
47 | the original argv[0] with the full path to the binary. When this |
48 | flag is included, binfmt_misc will add an argument to the argument |
49 | vector for this purpose, thus preserving the original argv[0]. |
50 | e.g. If your interp is set to /bin/foo and you run `blah` (which is |
51 | in /usr/local/bin), then the kernel will execute /bin/foo with |
52 | argv[] set to ["/bin/foo", "/usr/local/bin/blah", "blah"]. The |
53 | interp has to be aware of this so it can execute /usr/local/bin/blah |
54 | with argv[] set to ["blah"]. |
55 | 'O' - open-binary. Legacy behavior of binfmt_misc is to pass the full path |
56 | of the binary to the interpreter as an argument. When this flag is |
57 | included, binfmt_misc will open the file for reading and pass its |
58 | descriptor as an argument, instead of the full path, thus allowing |
59 | the interpreter to execute non-readable binaries. This feature |
60 | should be used with care - the interpreter has to be trusted not to |
61 | emit the contents of the non-readable binary. |
62 | 'C' - credentials. Currently, the behavior of binfmt_misc is to calculate |
63 | the credentials and security token of the new process according to |
64 | the interpreter. When this flag is included, these attributes are |
65 | calculated according to the binary. It also implies the 'O' flag. |
66 | This feature should be used with care as the interpreter |
67 | will run with root permissions when a setuid binary owned by root |
68 | is run with binfmt_misc. |
69 | 'F' - fix binary. The usual behaviour of binfmt_misc is to spawn the |
70 | binary lazily when the misc format file is invoked. However, |
71 | this doesn't work very well in the face of mount namespaces and |
72 | changeroots, so the F mode opens the binary as soon as the |
73 | emulation is installed and uses the opened image to spawn the |
74 | emulator, meaning it is always available once installed, |
75 | regardless of how the environment changes. |
76 | |
77 | |
78 | There are some restrictions: |
79 | - the whole register string may not exceed 1920 characters |
80 | - the magic must reside in the first 128 bytes of the file, i.e. |
81 | offset+size(magic) has to be less than 128 |
82 | - the interpreter string may not exceed 127 characters |
83 | |
84 | To use binfmt_misc you have to mount it first. You can mount it with |
85 | "mount -t binfmt_misc none /proc/sys/fs/binfmt_misc" command, or you can add |
86 | a line "none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0" to your |
87 | /etc/fstab so it auto mounts on boot. |
88 | |
89 | You may want to add the binary formats in one of your /etc/rc scripts during |
90 | boot-up. Read the manual of your init program to figure out how to do this |
91 | right. |
92 | |
93 | Think about the order of adding entries! Later added entries are matched first! |
94 | |
95 | |
96 | A few examples (assumed you are in /proc/sys/fs/binfmt_misc): |
97 | |
98 | - enable support for em86 (like binfmt_em86, for Alpha AXP only): |
99 | 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 |
100 | 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 |
101 | |
102 | - enable support for packed DOS applications (pre-configured dosemu hdimages): |
103 | echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register |
104 | |
105 | - enable support for Windows executables using wine: |
106 | echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register |
107 | |
108 | For java support see Documentation/java.txt |
109 | |
110 | |
111 | You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) |
112 | or 1 (to enable) to /proc/sys/fs/binfmt_misc/status or /proc/.../the_name. |
113 | Catting the file tells you the current status of binfmt_misc/the entry. |
114 | |
115 | You can remove one entry or all entries by echoing -1 to /proc/.../the_name |
116 | or /proc/sys/fs/binfmt_misc/status. |
117 | |
118 | |
119 | HINTS: |
120 | ====== |
121 | |
122 | If you want to pass special arguments to your interpreter, you can |
123 | write a wrapper script for it. See Documentation/java.txt for an |
124 | example. |
125 | |
126 | Your interpreter should NOT look in the PATH for the filename; the kernel |
127 | passes it the full filename (or the file descriptor) to use. Using $PATH can |
128 | cause unexpected behaviour and can be a security hazard. |
129 | |
130 | |
131 | Richard Günther <rguenth@tat.physik.uni-tuebingen.de> |
132 |