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