share/man/man4/linux.4

   1 .\" Copyright (c) 2000 Sheldon Hearn
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd January 9, 2022
  28 .Dt LINUX 4
  29 .Os
  30 .Sh NAME
  31 .Nm linux
  32 .Nd Linux ABI support
  33 .Sh SYNOPSIS
  34 To enable the Linux ABI at boot time, place the following line in
  35 .Xr rc.conf 5 :
  36 .Bd -literal -offset indent
  37 linux_enable="YES"
  38 .Ed
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 kernel module provides limited Linux ABI (application binary interface)
  43 compatibility, making it possible to run many unmodified Linux applications
  44 without the need for virtualization or emulation.
  45 Some of the facilities provided are:
  46 .Bl -bullet
  47 .It
  48 Linux to native system call translation
  49 .It
  50 Linux-specific system calls
  51 .It
  52 Special signal handling for Linux processes
  53 .It
  54 Path translation mechanism
  55 .It
  56 Linux-specific virtual file systems
  57 .El
  58 .Pp
  59 The path translation mechanism makes Linux processes look up file paths
  60 under
  61 .Va emul_path
  62 (defaulting to
  63 .Pa /compat/linux )
  64 before
  65 .Pa / .
  66 For example, when Linux process attempts to open
  67 .Pa /etc/passwd ,
  68 it will really access
  69 .Pa /compat/linux/etc/passwd ,
  70 unless the latter does not exist.
  71 This is used to make sure Linux processes load Linux shared libraries
  72 instead of their similarly-named FreeBSD counterparts, and also
  73 to provide alternative versions of certain other files and virtual
  74 file systems.
  75 .Pp
  76 To install Linux shared libraries and system files into
  77 .Pa /compat/linux ,
  78 either use the
  79 .Pa emulators/linux_base-c7
  80 port or package,
  81 or
  82 .Xr debootstrap 8
  83 installed from
  84 .Pa sysutils/debootstrap .
  85 .Pp
  86 To avoid mounting Linux-specific filesystems at startup, add the following
  87 line to the
  88 .Xr rc.conf 5
  89 file:
  90 .Pp
  91 .Dl linux_mounts_enable="NO"
  92 .Sh SYSCTL VARIABLES
  93 The following variables are available as both
  94 .Xr sysctl 8
  95 variables and
  96 .Xr loader 8
  97 tunables:
  98 .Bl -tag -width indent
  99 .It Va compat.linux.debug
 100 Enable debugging messages.
 101 Set to 0 to silence them.
 102 Defaults to 3.
 103 A setting of 1 prints debug messages, tells about unimplemented stuff (only
 104 once).
 105 Set to 2 is like 1, but also prints messages about implemented but not tested
 106 stuff (only once).
 107 Setting it to 3 or higher is like 2, but no rate limiting of messages.
 108 .It Va compat.linux.default_openfiles
 109 Default soft openfiles resource limit for Linux applications.
 110 Set to -1 to disable the limit.
 111 Defaults to 1024.
 112 .It Va compat.linux.emul_path
 113 Path to the Linux run-time environment.
 114 Defaults to
 115 .Pa /compat/linux .
 116 .It Va compat.linux.osname
 117 Linux kernel operating system name.
 118 Defaults to "Linux".
 119 .It Va compat.linux.osrelease
 120 Linux kernel operating system release.
 121 Changing this to something else is discouraged on non-development systems,
 122 because it may change the way Linux programs work.
 123 Some versions of GNU libc are known to use different syscalls depending
 124 on the value of this sysctl.
 125 .It Va compat.linux.oss_version
 126 Linux Open Sound System version.
 127 Defaults to 198144.
 128 .It Va compat.linux.preserve_vstatus
 129 When set to 1, it prevents Linux applications from resetting the
 130 .Xr termios 4
 131 VSTATUS setting.
 132 From a user perspective, this makes
 133 .Va SIGINFO
 134 work for Linux executables.
 135 Defaults to 1.
 136 .It Va compat.linux.setid_allowed
 137 Enable handling of set-user-ID and set-group-ID mode bits for the new
 138 process image file when image is to be executed under Linux ABI.
 139 When set to 0, new Linux images always use credentials of the program
 140 that issued the
 141 .Xr execve 2
 142 call, regardless of the image file mode.
 143 This might be reasonable or even required, because
 144 .Fx
 145 does not emulate the Linux environment completely, and missed features
 146 may result in security vulnerabilities.
 147 Defaults to 1.
 148 .El
 149 .Sh FILES
 150 .Bl -tag -width /compat/linux/dev/shm -compact
 151 .It Pa /compat/linux
 152 Linux run-time environment
 153 .It Pa /compat/linux/dev
 154 device file system, see
 155 .Xr devfs 5
 156 .It Pa /compat/linux/dev/fd
 157 file descriptor file system mounted with the
 158 .Cm linrdlnk
 159 option, see
 160 .Xr fdescfs 5
 161 .It Pa /compat/linux/dev/shm
 162 in-memory file system, see
 163 .Xr tmpfs 5
 164 .It Pa /compat/linux/proc
 165 Linux process file system, see
 166 .Xr linprocfs 5
 167 .It Pa /compat/linux/sys
 168 Linux kernel objects file system, see
 169 .Xr linsysfs 5
 170 .El
 171 .Sh SEE ALSO
 172 .Xr brandelf 1 ,
 173 .Xr pty 4 ,
 174 .Xr elf 5 ,
 175 .Xr fdescfs 5 ,
 176 .Xr linprocfs 5 ,
 177 .Xr linsysfs 5 ,
 178 .Xr tmpfs 5
 179 .Sh HISTORY
 180 Linux ABI support first appeared for i386 in
 181 .Fx 2.1 .
 182 Support for amd64 binaries first appeared in
 183 .Fx 10.3 .
 184 Support for arm64 binaries first appeared in
 185 .Fx 12.0 .
 186 .Sh BUGS
 187 Support for some of the Linux-specific system calls and system call arguments
 188 is missing.