Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 1 | Kernel Support for miscellaneous (your favourite) Binary Formats v1.1 |
| 2 | ===================================================================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 12 | aka ``.com`` or ``.exe``. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 13 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 14 | First you must mount binfmt_misc:: |
| 15 | |
| 16 | mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 17 | |
| 18 | To actually register a new binary type, you have to set up a string looking like |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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``. |
Mike Frysinger | 43bd40e | 2014-10-13 15:52:05 -0700 | [diff] [blame] | 21 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 22 | Here is what the fields mean: |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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 ``\``. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 40 | If you chose filename extension matching, this is the extension to be |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 45 | bits from matching by supplying a string like magic and as long as magic. |
Mike Frysinger | 43bd40e | 2014-10-13 15:52:05 -0700 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 49 | - ``interpreter`` |
| 50 | is the program that should be invoked with the binary as first |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 51 | argument (specify the full path) |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 52 | - ``flags`` |
| 53 | is an optional field that controls several aspects of the invocation |
Mike Frysinger | 43bd40e | 2014-10-13 15:52:05 -0700 | [diff] [blame] | 54 | of the interpreter. It is a string of capital letters, each controls a |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 55 | certain aspect. The following flags are supported: |
| 56 | |
| 57 | ``P`` - preserve-argv[0] |
| 58 | Legacy behavior of binfmt_misc is to overwrite |
Mike Frysinger | 43bd40e | 2014-10-13 15:52:05 -0700 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 |
Mike Frysinger | 43bd40e | 2014-10-13 15:52:05 -0700 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 75 | ``C`` - credentials |
| 76 | Currently, the behavior of binfmt_misc is to calculate |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 77 | the credentials and security token of the new process according to |
| 78 | the interpreter. When this flag is included, these attributes are |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 79 | calculated according to the binary. It also implies the ``O`` flag. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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 |
James Bottomley | 4af75df | 2016-02-25 08:32:51 -0800 | [diff] [blame] | 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. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 91 | |
| 92 | |
| 93 | There are some restrictions: |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 94 | |
Mike Frysinger | bbaecc0 | 2014-10-13 15:52:03 -0700 | [diff] [blame] | 95 | - the whole register string may not exceed 1920 characters |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 104 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 105 | You may want to add the binary formats in one of your ``/etc/rc`` scripts during |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 112 | A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``): |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 113 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 114 | - enable support for em86 (like binfmt_em86, for Alpha AXP only):: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 115 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 118 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 119 | - enable support for packed DOS applications (pre-configured dosemu hdimages):: |
| 120 | |
| 121 | echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register |
| 122 | |
| 123 | - enable support for Windows executables using wine:: |
| 124 | |
| 125 | echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 126 | |
Mauro Carvalho Chehab | 8c27cef | 2016-10-18 10:12:27 -0200 | [diff] [blame] | 127 | For java support see Documentation/admin-guide/java.rst |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 128 | |
| 129 | |
| 130 | You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 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``. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 134 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 135 | You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name`` |
| 136 | or ``/proc/sys/fs/binfmt_misc/status``. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 137 | |
| 138 | |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 139 | Hints |
| 140 | ----- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 141 | |
| 142 | If you want to pass special arguments to your interpreter, you can |
Mauro Carvalho Chehab | 8c27cef | 2016-10-18 10:12:27 -0200 | [diff] [blame] | 143 | write a wrapper script for it. See Documentation/admin-guide/java.rst for an |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 144 | example. |
| 145 | |
| 146 | Your interpreter should NOT look in the PATH for the filename; the kernel |
Mauro Carvalho Chehab | 5902981 | 2016-09-21 13:56:19 -0300 | [diff] [blame] | 147 | passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 148 | cause unexpected behaviour and can be a security hazard. |
| 149 | |
| 150 | |
John Anthony Kazos Jr | be2a608 | 2007-05-09 08:50:42 +0200 | [diff] [blame] | 151 | Richard Günther <rguenth@tat.physik.uni-tuebingen.de> |