1.\" $NetBSD: compat_linux.8,v 1.16 2000/04/15 00:16:56 hubertf Exp $ 2.\" 3.\" Copyright (c) 1995 Frank van der Linden 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed for the NetBSD Project 17.\" by Frank van der Linden 18.\" 4. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd January 16, 1999 33.Dt COMPAT_LINUX 8 34.Os 35.Sh NAME 36.Nm compat_linux 37.Nd setup procedure for running Linux binaries 38.Sh DESCRIPTION 39.Nx 40supports running Linux binaries. This only applies to i386 systems 41for now. Both the a.out and ELF binary formats are supported. Most programs 42should work, including the ones that use the Linux SVGAlib. Programs that 43will not work include the Linux /proc filesystem (which is different from 44the optional 45.Nx 46/proc filesystem), and i386-specific calls, such as 47enabling virtual 8086 mode. Currently, sound is only partially 48supported for Linux binaries (they will probably run, depending on 49what Linux sound support features are used). 50 51The Linux compatibility feature is active 52for kernels compiled with the 53.Dv COMPAT_LINUX 54option enabled. 55If support for Linux a.out executables is desired, the 56.Dv EXEC_AOUT 57option should be enabled in addition to 58.Dv COMPAT_LINUX . 59Similarly, if support for Linux 32-bit and/or 64-bit ELF executables 60is desired, the 61.Dv EXEC_ELF32 62and/or 63.Dv EXEC_ELF64 64options (respectively) should be enabled in addition to 65.Dv COMPAT_LINUX . 66.Pp 67A lot of programs are dynamically linked. This means, that you will 68also need the Linux shared libraries that the program depends on, and 69the runtime linker. Also, you will need to create a "shadow root" 70directory for Linux binaries on your 71.Nx 72system. This directory 73is named /emul/linux. Any file operations done by Linux programs 74run under 75.Nx 76will look in this directory first. So, if a Linux 77program opens, for example, /etc/passwd, 78.Nx 79will 80first try to open /emul/linux/etc/passwd, and if that does not exist 81open the 'real' /etc/passwd file. It is recommended that you install 82Linux packages that include configuration files, etc under /emul/linux, 83to avoid naming conflicts with possible 84.Nx 85counterparts. Shared 86libraries should also be installed in the shadow tree. 87.Pp 88Generally, you will need to look for the shared libraries that Linux 89binaries depend on only the first few times that you install a Linux 90program on your 91.Nx 92system. After a while, you will have a sufficient 93set of Linux shared libraries on your system to be able to run newly 94imported Linux binaries without any extra work. 95 96.Ss Setting up shared libraries 97How to get to know which shared libraries Linux binaries need, and where 98to get them? Basically, there are 2 possibilities (when following 99these instructions: you will need to be root on your 100.Nx 101system to 102do the necessary installation steps). 103 104.Bl -tag -width 123 -compact 105.It 1. 106You have access to a Linux system. In this case you can 107temporarily install the binary there, see what shared libraries 108it needs, and copy them to your 109.Nx 110system. Example: you have 111just ftp-ed the Linux binary of Doom. Put it on the Linux 112system you have access to, and check which shared libraries it 113needs by running `ldd linuxxdoom': 114.Pp 115.Bl -tag -width 123 -compact -offset indent 116.It (me@linux) ldd linuxxdoom 117.nf 118libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 119libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 120libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 121.fi 122.El 123.Pp 124You would need go get all the files from the last column, and 125put them under /emul/linux, with the names in the first column 126as symbolic links pointing to them. This means you eventually have 127these files on your 128.Nx 129system: 130.Pp 131.nf 132/emul/linux/usr/X11/lib/libXt.so.3.1.0 133/emul/linux/usr/X11/lib/libXt.so.3 (symbolic link to the above) 134/emul/linux/usr/X11/lib/libX11.so.3.1.0 135/emul/linux/usr/X11/lib/libX11.so.3 (symbolic link to the above) 136/emul/linux/lib/libc.so.4.6.29 137/emul/linux/lib/libc.so.4 (symbolic link to the above) 138.fi 139.Pp 140Note that if you already have a Linux shared library with a 141matching major revision number to the first column of the 'ldd' 142output, you won't need to copy the file named in the last column 143to your system, the one you already have should work. It is 144advisable to copy the shared library anyway if it is a newer version, 145though. You can remove the old one, as long as you make the symbolic 146link point to the new one. So, if you have these libraries 147on your system: 148.Pp 149.nf 150/emul/linux/lib/libc.so.4.6.27 151/emul/linux/lib/libc.so.4 -> /emul/linux/lib/libc.so.4.6.27 152.fi 153.Pp 154and you find that the ldd output for a new binary you want to 155install is: 156.nf 157.Pp 158libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 159.fi 160.Pp 161you won't need to worry about copying /lib/libc.so.4.6.29 too, 162because the program should work fine with the slightly older version. 163You can decide to replace the libc.so anyway, and that should leave 164you with: 165.Pp 166.nf 167/emul/linux/lib/libc.so.4.6.29 168/emul/linux/lib/libc.so.4 -> /emul/linux/lib/libc.so.4.6.29 169.fi 170.Pp 171Please note that the symbolic link mechanism is 172.Em only 173needed for Linux binaries, the 174.Nx 175runtime linker takes care of 176looking for matching major revision numbers itself, you 177don't need to worry about that. 178.Pp 179Finally, you must make sure that you have the Linux runtime linker 180and its config files on your system. You should copy these 181files from the Linux system to their appropriate place on your 182.Nx 183system (in the /emul/linux tree): 184.Pp 185.nf 186/lib/ld.so 187/etc/ld.so.cache 188/etc/ld.so.config 189.fi 190.Pp 191.It 2. 192You don't have access to a Linux system. In that case, you 193should get the extra files you need from various ftp sites. 194Information on where to look for the various files is appended 195below. For now, let's assume you know where to get the files. 196.Pp 197Retrieve the following files (from _one_ ftp site to avoid 198any version mismatches), and install them under /emul/linux 199(i.e. /foo/bar is installed as /emul/linux/foo/bar): 200.Pp 201.nf 202/sbin/ldconfig 203/usr/bin/ldd 204/lib/libc.so.x.y.z 205/lib/ld.so 206.fi 207.Pp 208ldconfig and ldd don't necessarily need to be under /emul/linux, 209you can install them elsewhere in the system too. Just make sure 210they don't conflict with their 211.Nx 212counterparts. A good idea 213would be to install them in /usr/local/bin as ldconfig-linux and 214ldd-linux. 215.Pp 216Create the file /emul/linux/etc/ld.so.conf, containing the 217directories in which the Linux runtime linker should look 218for shared libs. It is a plain text file, containing a directory 219name on each line. /lib and /usr/lib are standard, you could 220add the following: 221.Pp 222.nf 223/usr/X11/lib 224/usr/local/lib 225.fi 226.Pp 227Note that these are mapped to /emul/linux/XXXX by 228.Nx Ns 's 229compat 230code, and should exist as such on your system. 231 232Run the Linux ldconfig program. It should be statically 233linked, so it doesn't need any shared libraries by itself. 234It will create the file /emul/linux/etc/ld.so.cache 235You should rerun the Linux version of the ldconfig program 236each time you add a new shared library. 237.Pp 238You should now be set up for Linux binaries which only need 239a shared libc. You can test this by running the Linux ldd 240on itself. Suppose that you have it installed as ldd-linux, it 241should produce something like: 242.Pp 243.Bl -tag -width 123 -compact -offset indent 244.It (me@netbsd) ldd-linux `which ldd-linux` 245libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 246.El 247.Pp 248This being done, you are ready to install new Linux binaries. 249Whenever you install a new Linux program, you should check 250if it needs shared libraries, and if so, whether you have 251them installed in the /emul/linux tree. To do this, you run 252the Linux version ldd on the new program, and watch its output. 253ldd (see also the manual page for 254.Xr ldd 1 ) 255will print a list 256of shared libraries that the program depends on, in the 257form <majorname> (<jumpversion>) => <fullname>. 258.Pp 259If it prints "not found" in stead of <fullname> it means that 260you need an extra library. Which library this is, is shown 261in <majorname>, which will be of the form libXXXX.so.<N> 262You will need to find a libXXXX.so.<N>.<mm> on a Linux ftp site, 263and install it on your system. The XXXX (name) and <N> (major 264revision number) should match; the minor number(s) <mm> are 265less important, though it is advised to take the most 266recent version. 267.Pp 268.It 3. 269For i386, you can simply install the SuSE shared libs using the 270.Pa pkgsrc/emulators/suse_linux 271package(s). 272.El 273.Ss Setting up other files 274Newer version of Linux use /etc/nsswitch.conf for network information, 275such as 276.Tn NIS 277and DNS. You must create or get a valid copy of this file 278and put it in /emul/linux/etc. 279 280.Ss Finding the necessary files. 281[ 282.Em Note: 283As of October, 1998, a reasonable set of Linux libraries and other files 284needed for Linux emulation may be obtained from 285.Dl ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/linux_lib-2.5.tar.gz 286It is recommended you try to retrieve this file (or a more recent 287version) from ftp.freebsd.org first as this tar file contains 288everything one typically needs and is is very simple to use for this 289application. Failing that, see the instructions below. 290] 291.Pp 292.Em Note: 293the information below is valid as of the time this 294document was written (March, 1995), but certain details 295such as names of ftp sites, directories and distribution names 296may have changed by the time you read this. 297.Pp 298Linux is distributed by several groups that make their own set 299of binaries that they distribute. Each distribution has its own 300name, like "Slackware" or "Yggdrasil". The distributions are 301available on a lot of ftp sites. Sometimes the files are unpacked, 302and you can get the individual files you need, but mostly they 303are stored in distribution sets, usually consisting of subdirectories 304with gzipped tar files in them. The primary ftp sites for the 305distributions are: 306.Pp 307.nf 308sunsite.unc.edu:/pub/Linux/distributions 309tsx-11.mit.edu:/pub/linux/distributions 310.fi 311.Pp 312Some European mirrors: 313.Pp 314.nf 315ftp.luth.se:/pub/linux/distributions 316ftp.demon.co.uk:/pub/linux/distributions 317src.doc.ic.ac.uk:/packages/linux/distributions 318.fi 319.Pp 320For simplicity, let's concentrate on Slackware here. This distribution 321consists of a number of subdirectories, containing separate packages. 322Normally, they're controlled by an install program, but you can 323retrieve files "by hand" too. First of all, you will need to look 324in the "contents" subdir of the distribution. You will find 325a lot of small textfiles here describing the contents of the separate 326packages. The fastest way to look something up is to retrieve all 327the files in the contents subdirectory, and grep through them for the file 328you need. Here is an example of a list of files that you might need, and 329in which contents-file you will find it by grepping through them: 330.Pp 331.Bd -unfilled -offset indent 332Needed Package 333 334ld.so ldso 335ldconfig ldso 336ldd ldso 337libc.so.4 shlibs 338libX11.so.6.0 xf_lib 339libXt.so.6.0 xf_lib 340libX11.so.3 oldlibs 341libXt.so.3 oldlibs 342.Ed 343.Pp 344So, in this case, you will need the packages ldso, shlibs, xf_lib and oldlibs. 345In each of the contents-files for these packages, look for a line saying 346"PACKAGE LOCATION", it will tell you on which 'disk' the package is, 347in our case it will tell us in which subdirectory we need to look. 348For our example, we would find the following locations: 349.Pp 350.Bd -unfilled -offset indent 351Package Location 352 353ldso diska2 354shlibs diska2 355oldlibs diskx6 356xf_lib diskx9 357.Ed 358.Pp 359The locations called "diskXX" refer to the "slakware/XX" subdirectories 360of the distribution, others may be found in the "contrib" subdirectory. 361In this case, we could now retrieve the packages we need by retrieving 362the following files (relative to the root of the Slackware distribution 363tree): 364.Pp 365.nf 366slakware/a2/ldso.tgz 367slakware/a2/shlibs.tgz 368slakware/x6/oldlibs/tgz 369slakware/x9/xf_lib.tgz 370.fi 371.Pp 372Extract the files from these gzipped tarfiles in your /emul/linux directory 373(possibly omitting or afterwards removing files you don't need), and you 374are done. 375 376.Ss Programs using SVGAlib 377SVGAlib binaries require some extra care. The pcvt virtual console driver 378has to be in the kernel for them to work, and you will also have to create 379some symbloic links in the /emul/linux/dev directory, namely: 380.Pp 381.nf 382/emul/linux/dev/console -> /dev/tty 383/emul/linux/dev/mouse -> whatever device your mouse is connected to 384/emul/linux/dev/ttyS0 -> /dev/tty00 385/emul/linux/dev/ttyS1 -> /dev/tty01 386.fi 387.Pp 388Be warned: the first link mentioned here makes SVGAlib binaries 389work, but may confuse others, so you may have to remove it again at 390some point. 391.Sh BUGS 392The information about Linux distributions may become outdated. 393.Pp 394Pathnames pointed to by symbolic links are not looked up in the 395shadow root when running a Linux executable. This is not consistent. 396.Pp 397Linux executables can not handle directory offset cookies > 32 bits. 398Should such an offset occur, you will see the message "linux_getdents: 399dir offset too large for emulated program". Currently, this can only 400happen on NFS mounted filesystems, mounted from servers that return 401offsets with information in the upper 32 bits. These errors should 402rarely happen, but can be avoided by mounting this filesystem with offset 403translation enabled. See the 404.Fl X 405option to 406.Xr mount_nfs 8 . 407The 408.Fl 2 409option to 410.Xr mount_nfs 8 411will also have the desired effect, but is less preferable. 412