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