Kernel Support for miscellaneous Binary Formats (binfmt_misc) | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Recognition and registration

binfmt-misc.rst:1-21

Magic/mask 또는 extension과 interpreter를 register filesystem에 연결합니다.

Registration fields

binfmt-misc.rst:22-55

Name, type, offset, magic, mask, interpreter와 flags 형식을 정의합니다.

Invocation flags

binfmt-misc.rst:56-92

argv, open fd, credential과 namespace-resistant emulator 처리 flag를 설명합니다.

Limits and ordering

binfmt-misc.rst:93-111

문자 수·magic 위치 limit, boot mount와 newest-first matching을 설명합니다.

Examples and control

binfmt-misc.rst:112-151

Em86·DOS·Wine 등록과 enable/disable/remove 및 PATH 보안 규칙을 제공합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 Kernel Support for miscellaneous Binary Formats (binfmt_misc)

2 =============================================================

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.

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

12 aka ``.com`` or ``.exe``.

14 First you must mount binfmt_misc::

16 mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc

18 To actually register a new binary type, you have to set up a string looking like

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``.

22 Here is what the fields mean:

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 ``\``.

40 If you chose filename extension matching, this is the extension to be

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

45 bits from matching by supplying a string like magic and as long as magic.

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.

49 - ``interpreter``

50 is the program that should be invoked with the binary as first

51 argument (specify the full path)

52 - ``flags``

53 is an optional field that controls several aspects of the invocation

54 of the interpreter. It is a string of capital letters, each controls a

55 certain aspect. The following flags are supported:

57 ``P`` - preserve-argv[0]

58 Legacy behavior of binfmt_misc is to overwrite

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

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

            ``/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

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

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.

75 ``C`` - credentials

76 Currently, the behavior of binfmt_misc is to calculate

77 the credentials and security token of the new process according to

78 the interpreter. When this flag is included, these attributes are

79 calculated according to the binary. It also implies the ``O`` flag.

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.

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

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.

93 There are some restrictions:

95 - the whole register string may not exceed 1920 characters

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

100 To use binfmt_misc you have to mount it first. You can mount it with

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.

104

105 You may want to add the binary formats in one of your ``/etc/rc`` scripts during

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

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)::

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

126

127 For java support see Documentation/admin-guide/java.rst

128

129

130 You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable)

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``.

134

135 You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name``

136 or ``/proc/sys/fs/binfmt_misc/status``.

137

138

139 Hints

140 -----

141

142 If you want to pass special arguments to your interpreter, you can

143 write a wrapper script for it.

144 See :doc:`Documentation/admin-guide/java.rst <./java>` for an example.

145

146 Your interpreter should NOT look in the PATH for the filename; the kernel

147 passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can

148 cause unexpected behaviour and can be a security hazard.

149

150

151 Richard Günther <[email protected]>

152

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Binfmt_misc 인식과 등록 형식

1-21

Binfmt_misc kernel feature를 사용하면 일부 제약을 제외한 거의 모든 program을 shell에서 이름만 입력해 실행할 수 있습니다. Compile된 Java, Python 또는 Emacs program도 포함됩니다.

어떤 binary에 어떤 interpreter를 호출할지 binfmt_misc에 알려야 합니다. File 시작 부분의 byte를 사용자가 지정한 magic sequence와 비교하고 mask로 일부 bit를 제외해 binary type을 인식합니다. `.com`, `.exe` 같은 filename extension으로도 인식할 수 있습니다.

먼저 binfmt_misc를 mount합니다.

First you must mount binfmt_misc::

	mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc

새 binary type을 등록할 때 `:name:type:offset:magic:mask:interpreter:flags` 형식의 string을 `/proc/sys/fs/binfmt_misc/register`에 씁니다. Colon은 필요에 따라 다른 delimiter로 선택할 수 있습니다.

Binfmt_misc dispatch

Open executable by nameMatch magic+mask or extensionSelect registered entryApply flagsInvoke full-path interpreter

Executable 식별부터 interpreter 실행까지의 흐름입니다.

등록 string field

22-55

Binfmt_misc registration fields

FieldMeaning

name`/proc/sys/fs/binfmt_misc` 아래 만들 identifier; slash 금지

type`M`은 magic, `E`는 extension 인식

offsetMagic/mask의 byte offset; 생략 시 0, extension에서는 무시

magicMatch할 byte sequence 또는 dot 없는 extension

maskMagic와 같은 길이의 optional bit mask; 기본 all 0xff

interpreterBinary를 첫 argument로 받아 호출할 program의 full path

flagsInterpreter invocation을 제어하는 capital-letter string

delimiter예제의 colon; 필요에 따라 선택 가능

등록 string의 8개 위치와 magic/extension 차이를 정리합니다.

`magic`에는 `\x0a`, `\xA4` 같은 hex-encoded character를 넣을 수 있습니다. NUL byte는 반드시 escape해야 하며 첫 NUL에서 parsing이 멈춥니다. Shell이 backslash를 소비하지 않게 `\\x0a`로 써야 할 수도 있습니다. Extension mode에서는 dot을 제외한 extension을 쓰고 hex special은 허용하지 않습니다. Extension match는 case-sensitive이며 slash를 사용할 수 없습니다.

`mask`는 지정하지 않으면 모두 `0xff`이며 file byte sequence에 AND합니다. Magic와 같은 길이여야 하고 NUL을 escape해야 합니다. Extension matching에서는 무시합니다.

Interpreter invocation flag

56-92

Binfmt_misc flags

FlagNameBehavior and caution

Ppreserve-argv[0]Binary full path용 argument를 추가해 original argv[0] 보존

Oopen-binaryPath 대신 read-opened file descriptor 전달; unreadable binary도 실행 가능

CcredentialsInterpreter가 아니라 binary 기준 credential/security token 계산; O를 암시

Ffix binaryRegistration 때 emulator binary를 열어 mount namespace/chroot 변화 뒤에도 사용

P/O/C/F flag가 argument, file access, credential과 namespace 동작을 바꿉니다.

Legacy 동작은 original `argv[0]`을 binary full path로 덮어씁니다. `P`를 쓰면 `/bin/foo` interpreter와 `/usr/local/bin/blah` 실행 시 `argv[]`가 `["/bin/foo", "/usr/local/bin/blah", "blah"]`가 됩니다. Interpreter는 이를 이해하고 target을 `argv[]=["blah"]`로 실행해야 합니다.

`O`는 binary path 대신 open file descriptor를 전달하므로 non-readable binary 실행이 가능하지만, interpreter가 내용을 유출하지 않을 만큼 신뢰할 수 있어야 합니다.

`C`는 binary 기준으로 credential을 계산하고 `O`도 암시합니다. Root 소유 setuid binary를 실행하면 interpreter가 root permission으로 동작하므로 주의해야 합니다. `F`는 emulation 등록 시 binary를 미리 열어 mount namespace나 chroot environment가 변해도 emulator image를 계속 사용할 수 있게 합니다.

제약·자동 mount·matching 순서

93-111

Binfmt_misc registration limits

LimitValue

Whole register stringAt most 1920 characters

Magic locationoffset + size(magic) < 128 bytes

Interpreter stringAt most 127 characters

Binfmt_misc는 먼저 mount해야 합니다. `mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`를 실행하거나 `/etc/fstab`에 `none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`을 추가해 boot 때 자동 mount합니다.

Boot 중 `/etc/rc` script에서 binary format을 추가할 수 있으며 올바른 방법은 init program manual을 확인합니다. Entry 추가 순서가 중요합니다. 나중에 추가한 entry를 먼저 match합니다.

등록 예제·상태 제어·보안 hint

112-151

`/proc/sys/fs/binfmt_misc`에 있다고 가정한 예제입니다. Alpha AXP에서 em86용 i386/i486 ELF magic, preconfigured dosemu hdimage용 packed DOS application, Wine용 Windows `MZ` executable을 각각 register합니다.

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/admin-guide/java.rst

Binfmt_misc examples

EntryRecognitionInterpreter

i386 / i486ELF magic and mask/bin/em86

DEXEMagic 0x0e + DEX/usr/bin/dosexec

DOSWinMagic MZ/usr/local/bin/wine

JavaSee Documentation/admin-guide/java.rstWrapper example in Java documentation

예제가 인식하는 binary와 interpreter입니다.

`/proc/sys/fs/binfmt_misc/status` 또는 개별 `/proc/.../the_name`에 0을 쓰면 전체 또는 해당 type을 disable하고 1을 쓰면 enable합니다. File을 읽으면 현재 상태를 확인합니다. 개별 entry 또는 전체 status에 -1을 쓰면 하나 또는 모든 entry를 제거합니다.

Binfmt_misc entry control

echo 1Enable entry or subsystem

echo 0Disable entry or subsystem

cat fileRead current status

echo -1Remove one entry or all entries

Status file에 쓰는 값이 lifecycle을 제어합니다.

Interpreter에 특별한 argument를 넘기려면 wrapper script를 만들 수 있습니다. `Documentation/admin-guide/java.rst` 예제를 참조합니다.

Interpreter는 filename을 `$PATH`에서 찾으면 안 됩니다. Kernel이 전달한 full filename 또는 file descriptor를 사용해야 합니다. `$PATH` 검색은 예상 밖 동작과 security hazard를 일으킬 수 있습니다.

문서 저자는 Richard Günther <[email protected]>입니다.