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