Orange Pi5 kernel

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