1 Kernel Support for miscellaneous Binary Format
2 ==============================================
3
4 This Kernel feature allows you to invoke almos
5 every program by simply typing its name in the
6 This includes for example compiled Java(TM), P
7
8 To achieve this you must tell binfmt_misc whic
9 with which binary. Binfmt_misc recognises the
10 at the beginning of the file with a magic byte
11 bits) you have supplied. Binfmt_misc can also
12 aka ``.com`` or ``.exe``.
13
14 First you must mount binfmt_misc::
15
16 mount binfmt_misc -t binfmt_misc /proc
17
18 To actually register a new binary type, you ha
19 ``:name:type:offset:magic:mask:interpreter:fla
20 ``:`` upon your needs) and echo it to ``/proc/
21
22 Here is what the fields mean:
23
24 - ``name``
25 is an identifier string. A new /proc file w
26 name below ``/proc/sys/fs/binfmt_misc``; ca
27 obvious reasons.
28 - ``type``
29 is the type of recognition. Give ``M`` for
30 - ``offset``
31 is the offset of the magic/mask in the file
32 defaults to 0 if you omit it (i.e. you writ
33 Ignored when using filename extension match
34 - ``magic``
35 is the byte sequence binfmt_misc is matchin
36 may contain hex-encoded characters like ``\
37 must escape any NUL bytes; parsing halts at
38 environment you might have to write ``\\x0a
39 eating your ``\``.
40 If you chose filename extension matching, t
41 recognised (without the ``.``, the ``\x0a``
42 Extension matching is case sensitive, an
43 - ``mask``
44 is an (optional, defaults to all 0xff) mask
45 bits from matching by supplying a string li
46 The mask is anded with the byte sequence of
47 escape any NUL bytes; parsing halts at the
48 filename extension matching.
49 - ``interpreter``
50 is the program that should be invoked with
51 argument (specify the full path)
52 - ``flags``
53 is an optional field that controls several
54 of the interpreter. It is a string of capit
55 certain aspect. The following flags are sup
56
57 ``P`` - preserve-argv[0]
58 Legacy behavior of binfmt_misc is
59 the original argv[0] with the full
60 flag is included, binfmt_misc will
61 vector for this purpose, thus pres
62 e.g. If your interp is set to ``/b
63 (which is in ``/usr/local/bin``),
64 ``/bin/foo`` with ``argv[]`` set t
65 execute ``/usr/local/bin/blah``
66 with ``argv[]`` set to ``["blah"]`
67 ``O`` - open-binary
68 Legacy behavior of binfmt_misc is
69 of the binary to the interpreter a
70 included, binfmt_misc will open th
71 descriptor as an argument, instead
72 the interpreter to execute non-rea
73 should be used with care - the int
74 emit the contents of the non-reada
75 ``C`` - credentials
76 Currently, the behavior of binfmt_
77 the credentials and security token
78 the interpreter. When this flag is
79 calculated according to the binary
80 This feature should be used with c
81 will run with root permissions whe
82 is run with binfmt_misc.
83 ``F`` - fix binary
84 The usual behaviour of binfmt_misc
85 binary lazily when the misc format
86 this doesn't work very well in the
87 changeroots, so the ``F`` mode ope
88 emulation is installed and uses th
89 emulator, meaning it is always ava
90 regardless of how the environment
91
92
93 There are some restrictions:
94
95 - the whole register string may not exceed 19
96 - the magic must reside in the first 128 byte
97 offset+size(magic) has to be less than 128
98 - the interpreter string may not exceed 127 c
99
100 To use binfmt_misc you have to mount it first.
101 ``mount -t binfmt_misc none /proc/sys/fs/binfm
102 a line ``none /proc/sys/fs/binfmt_misc binfmt
103 ``/etc/fstab`` so it auto mounts on boot.
104
105 You may want to add the binary formats in one
106 boot-up. Read the manual of your init program
107 right.
108
109 Think about the order of adding entries! Later
110
111
112 A few examples (assumed you are in ``/proc/sys
113
114 - enable support for em86 (like binfmt_em86, f
115
116 echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00
117 echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00
118
119 - enable support for packed DOS applications (
120
121 echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:'
122
123 - enable support for Windows executables using
124
125 echo ':DOSWin:M::MZ::/usr/local/bin/wine:'
126
127 For java support see Documentation/admin-guide
128
129
130 You can enable/disable binfmt_misc or one bina
131 or 1 (to enable) to ``/proc/sys/fs/binfmt_misc
132 ``/proc/.../the_name``.
133 Catting the file tells you the current status
134
135 You can remove one entry or all entries by ech
136 or ``/proc/sys/fs/binfmt_misc/status``.
137
138
139 Hints
140 -----
141
142 If you want to pass special arguments to your
143 write a wrapper script for it.
144 See :doc:`Documentation/admin-guide/java.rst <
145
146 Your interpreter should NOT look in the PATH f
147 passes it the full filename (or the file descr
148 cause unexpected behaviour and can be a securi
149
150
151 Richard Günther <rguenth@tat.physik.uni-tuebin
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.