1.\" $NetBSD: compat_linux.8,v 1.10 1998/02/06 06:14:48 perry 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 March 2, 1995 33.Dt COMPAT_LINUX 8 34.Os NetBSD 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 ldd(1)) will print a list 254of shared libraries that the program depends on, in the 255form <majorname> (<jumpversion>) => <fullname>. 256.Pp 257If it prints "not found" in stead of <fullname> it means that 258you need an extra library. Which library this is, is shown 259in <majorname>, which will be of the form libXXXX.so.<N> 260You will need to find a libXXXX.so.<N>.<mm> on a Linux ftp site, 261and install it on your system. The XXXX (name) and <N> (major 262revision number) should match; the minor number(s) <mm> are 263less important, though it is advised to take the most 264recent version. 265.El 266 267.Ss Setting up other files 268Newer version of Linux use /etc/nsswitch.conf for network information, 269such as YP and DNS. You must create or get a valid copy of this file 270and put it in /emul/linux/etc. 271 272.Ss Finding the necessary files. 273[ 274.Em Note: 275As of April, 1997, a reasonable set of Linux libraries and other files 276needed for Linux emulation may be obtained from 277.Dl ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/linux_lib-2.4.tar.gz 278It is recommended you try to retrieve this file (or a more recent 279version) from ftp.freebsd.org first as this tar file contains 280everything one typically needs and is is very simple to use for this 281application. Failing that, see the instructions below. 282] 283.Pp 284.Em Note: 285the information below is valid as of the time this 286document was written (March, 1995), but certain details 287such as names of ftp sites, directories and distribution names 288may have changed by the time you read this. 289.Pp 290Linux is distributed by several groups that make their own set 291of binaries that they distribute. Each distribution has its own 292name, like "Slackware" or "Yggdrasil". The distributions are 293available on a lot of ftp sites. Sometimes the files are unpacked, 294and you can get the individual files you need, but mostly they 295are stored in distribution sets, usually consisting of subdirectories 296with gzipped tar files in them. The primary ftp sites for the 297distributions are: 298.Pp 299.nf 300sunsite.unc.edu:/pub/Linux/distributions 301tsx-11.mit.edu:/pub/linux/distributions 302.fi 303.Pp 304Some European mirrors: 305.Pp 306.nf 307ftp.luth.se:/pub/linux/distributions 308ftp.demon.co.uk:/pub/linux/distributions 309src.doc.ic.ac.uk:/packages/linux/distributions 310.fi 311.Pp 312For simplicity, let's concentrate on Slackware here. This distribution 313consists of a number of subdirectories, containing separate packages. 314Normally, they're controlled by an install program, but you can 315retrieve files "by hand" too. First of all, you will need to look 316in the "contents" subdir of the distribution. You will find 317a lot of small textfiles here describing the contents of the seperate 318packages. The fastest way to look something up is to retrieve all 319the files in the contents subdirectory, and grep through them for the file 320you need. Here is an example of a list of files that you might need, and 321in which contents-file you will find it by grepping through them: 322.Pp 323.Bd -unfilled -offset indent 324Needed Package 325 326ld.so ldso 327ldconfig ldso 328ldd ldso 329libc.so.4 shlibs 330libX11.so.6.0 xf_lib 331libXt.so.6.0 xf_lib 332libX11.so.3 oldlibs 333libXt.so.3 oldlibs 334.Ed 335.Pp 336So, in this case, you will need the packages ldso, shlibs, xf_lib and oldlibs. 337In each of the contents-files for these packages, look for a line saying 338"PACKAGE LOCATION", it will tell you on which 'disk' the package is, 339in our case it will tell us in which subdirectory we need to look. 340For our example, we would find the following locations: 341.Pp 342.Bd -unfilled -offset indent 343Package Location 344 345ldso diska2 346shlibs diska2 347oldlibs diskx6 348xf_lib diskx9 349.Ed 350.Pp 351The locations called "diskXX" refer to the "slakware/XX" subdirectories 352of the distribution, others may be found in the "contrib" subdirectory. 353In this case, we could now retrieve the packages we need by retrieving 354the following files (relative to the root of the Slackware distribution 355tree): 356.Pp 357.nf 358slakware/a2/ldso.tgz 359slakware/a2/shlibs.tgz 360slakware/x6/oldlibs/tgz 361slakware/x9/xf_lib.tgz 362.fi 363.Pp 364Extract the files from these gzipped tarfiles in your /emul/linux directory 365(possibly omitting or afterwards removing files you don't need), and you 366are done. 367 368.Ss Programs using SVGAlib 369SVGAlib binaries require some extra care. The pcvt virtual console driver 370has to be in the kernel for them to work, and you will also have to create 371some symbloic links in the /emul/linux/dev directory, namely: 372.Pp 373.nf 374/emul/linux/dev/console -> /dev/tty 375/emul/linux/dev/mouse -> whatever device your mouse is connected to 376/emul/linux/dev/ttyS0 -> /dev/tty00 377/emul/linux/dev/ttyS1 -> /dev/tty01 378.fi 379.Pp 380Be warned: the first link mentioned here makes SVGAlib binaries 381work, but may confuse others, so you may have to remove it again at 382some point. 383.Sh BUGS 384The information about Linux distributions may become outdated. 385.Pp 386Pathnames pointed to by symbolic links are not looked up in the 387shadow root when running a Linux executable. This is not consistent. 388.Pp 389Linux executables can not handle directory offset cookies > 32 bits. 390Should such an offset occur, you will see the message "linux_getdents: 391dir offset too large for emulated program". Currently, this can only 392happen on NFS mounted filesystems, mounted from servers that return 393offsets with information in the upper 32 bits. These errors should 394rarely happen, but can be avoided by mounting this filesystem with offset 395translation enabled. See the 396.Fl X 397option to 398.Xr mount_nfs 8 . 399The 400.Fl 2 401option to 402.Xr mount_nfs 8 403will also have the desired effect, but is less preferable. 404