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