summaryrefslogtreecommitdiff
path: root/Documentation/binfmt_misc.txt
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-09-21 09:51:11 -0300
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2016-10-24 08:12:35 -0200
commit9d85025b0418163fae079c9ba8f8445212de8568 (patch)
tree4629e2dedf4a9ed45a6855c129101f9b52138372 /Documentation/binfmt_misc.txt
parent186128f75392f8478ad1b32a675627d738881ca4 (diff)
docs-rst: create an user's manual book
Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/binfmt_misc.txt')
-rw-r--r--Documentation/binfmt_misc.txt151
1 files changed, 0 insertions, 151 deletions
diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt
deleted file mode 100644
index 9c5ff8f260bf..000000000000
--- a/Documentation/binfmt_misc.txt
+++ /dev/null
@@ -1,151 +0,0 @@
-Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
-=====================================================================
-
-This Kernel feature allows you to invoke almost (for restrictions see below)
-every program by simply typing its name in the shell.
-This includes for example compiled Java(TM), Python or Emacs programs.
-
-To achieve this you must tell binfmt_misc which interpreter has to be invoked
-with which binary. Binfmt_misc recognises the binary-type by matching some bytes
-at the beginning of the file with a magic byte sequence (masking out specified
-bits) you have supplied. Binfmt_misc can also recognise a filename extension
-aka ``.com`` or ``.exe``.
-
-First you must mount binfmt_misc::
-
- mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
-
-To actually register a new binary type, you have to set up a string looking like
-``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the
-``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``.
-
-Here is what the fields mean:
-
-- ``name``
- is an identifier string. A new /proc file will be created with this
- ``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for
- obvious reasons.
-- ``type``
- is the type of recognition. Give ``M`` for magic and ``E`` for extension.
-- ``offset``
- is the offset of the magic/mask in the file, counted in bytes. This
- defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``).
- Ignored when using filename extension matching.
-- ``magic``
- is the byte sequence binfmt_misc is matching for. The magic string
- may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you
- must escape any NUL bytes; parsing halts at the first one. In a shell
- environment you might have to write ``\\x0a`` to prevent the shell from
- eating your ``\``.
- If you chose filename extension matching, this is the extension to be
- recognised (without the ``.``, the ``\x0a`` specials are not allowed).
- Extension matching is case sensitive, and slashes ``/`` are not allowed!
-- ``mask``
- is an (optional, defaults to all 0xff) mask. You can mask out some
- bits from matching by supplying a string like magic and as long as magic.
- The mask is anded with the byte sequence of the file. Note that you must
- escape any NUL bytes; parsing halts at the first one. Ignored when using
- filename extension matching.
-- ``interpreter``
- is the program that should be invoked with the binary as first
- argument (specify the full path)
-- ``flags``
- is an optional field that controls several aspects of the invocation
- of the interpreter. It is a string of capital letters, each controls a
- certain aspect. The following flags are supported:
-
- ``P`` - preserve-argv[0]
- Legacy behavior of binfmt_misc is to overwrite
- the original argv[0] with the full path to the binary. When this
- flag is included, binfmt_misc will add an argument to the argument
- vector for this purpose, thus preserving the original ``argv[0]``.
- e.g. If your interp is set to ``/bin/foo`` and you run ``blah``
- (which is in ``/usr/local/bin``), then the kernel will execute
- ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can
- execute ``/usr/local/bin/blah``
- with ``argv[]`` set to ``["blah"]``.
- ``O`` - open-binary
- Legacy behavior of binfmt_misc is to pass the full path
- of the binary to the interpreter as an argument. When this flag is
- included, binfmt_misc will open the file for reading and pass its
- descriptor as an argument, instead of the full path, thus allowing
- the interpreter to execute non-readable binaries. This feature
- should be used with care - the interpreter has to be trusted not to
- emit the contents of the non-readable binary.
- ``C`` - credentials
- Currently, the behavior of binfmt_misc is to calculate
- the credentials and security token of the new process according to
- the interpreter. When this flag is included, these attributes are
- calculated according to the binary. It also implies the ``O`` flag.
- This feature should be used with care as the interpreter
- will run with root permissions when a setuid binary owned by root
- is run with binfmt_misc.
- ``F`` - fix binary
- The usual behaviour of binfmt_misc is to spawn the
- binary lazily when the misc format file is invoked. However,
- this doesn``t work very well in the face of mount namespaces and
- changeroots, so the ``F`` mode opens the binary as soon as the
- emulation is installed and uses the opened image to spawn the
- emulator, meaning it is always available once installed,
- regardless of how the environment changes.
-
-
-There are some restrictions:
-
- - the whole register string may not exceed 1920 characters
- - the magic must reside in the first 128 bytes of the file, i.e.
- offset+size(magic) has to be less than 128
- - the interpreter string may not exceed 127 characters
-
-To use binfmt_misc you have to mount it first. You can mount it with
-``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add
-a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your
-``/etc/fstab`` so it auto mounts on boot.
-
-You may want to add the binary formats in one of your ``/etc/rc`` scripts during
-boot-up. Read the manual of your init program to figure out how to do this
-right.
-
-Think about the order of adding entries! Later added entries are matched first!
-
-
-A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``):
-
-- enable support for em86 (like binfmt_em86, for Alpha AXP only)::
-
- 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
- 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
-
-- enable support for packed DOS applications (pre-configured dosemu hdimages)::
-
- echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register
-
-- enable support for Windows executables using wine::
-
- echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register
-
-For java support see Documentation/java.txt
-
-
-You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable)
-or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or
-``/proc/.../the_name``.
-Catting the file tells you the current status of ``binfmt_misc/the_entry``.
-
-You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name``
-or ``/proc/sys/fs/binfmt_misc/status``.
-
-
-Hints
------
-
-If you want to pass special arguments to your interpreter, you can
-write a wrapper script for it. See Documentation/java.txt for an
-example.
-
-Your interpreter should NOT look in the PATH for the filename; the kernel
-passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can
-cause unexpected behaviour and can be a security hazard.
-
-
-Richard Günther <rguenth@tat.physik.uni-tuebingen.de>