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