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