1.\" $NetBSD: compat_linux.8,v 1.26 2002/03/29 16:07:39 bjh21 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 29, 2002 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 arm, alpha, i386, m68k and 41powerpc 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 option 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) =\*[Gt] /usr/X11/lib/libXt.so.3.1.0 136libX11.so.3 (DLL Jump 3.1) =\*[Gt] /usr/X11/lib/libX11.so.3.1.0 137libc.so.4 (DLL Jump 4.5pl26) =\*[Gt] /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-\*[Gt] 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) =\*[Gt] /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-\*[Gt] 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) =\*[Gt] /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 \*[Lt]majorname\*[Gt] (\*[Lt]jumpversion\*[Gt]) =\*[Gt] \*[Lt]fullname\*[Gt]. 332.Pp 333If it prints 334.Dq not found 335instead of \*[Lt]fullname\*[Gt] it means that 336you need an extra library. Which library this is, is shown 337in \*[Lt]majorname\*[Gt], which will be of the form libXXXX.so.\*[Lt]N\*[Gt] 338You will need to find a libXXXX.so.\*[Lt]N\*[Gt].\*[Lt]mm\*[Gt] on a Linux ftp site, 339and install it on your system. The XXXX (name) and \*[Lt]N\*[Gt] (major 340revision number) should match; the minor number(s) \*[Lt]mm\*[Gt] are 341less important, though it is advised to take the most 342recent version. 343.El 344.Ss Setting up procfs 345Some Linux binaries expect procfs to be mounted and that it would 346contain some Linux specific stuff. If it's not the case, they behave 347unexpectedly or even crash. 348.Pp 349Mount procfs on NetBSD using following command: 350.Bl -tag -width 123 -offset indent 351.It (me@netbsd) mount_procfs -o linux procfs /proc 352.El 353.Pp 354You can also setup system so that procfs is mounted automatically 355on system boot, by putting entry like below to 356.Pa /etc/fstab . 357.Bl -tag -width 123 -offset indent 358.It procfs /proc procfs ro,linux 359.El 360.Pp 361See also 362.Xr mount_procfs 8 363for further information. 364.Ss Setting up other files 365Newer version of Linux use 366.Pa /etc/nsswitch.conf 367for network information, such as 368.Tn NIS 369and DNS. You must create or get a valid copy of this file 370and put it in 371.Pa /emul/linux/etc . 372.Ss Finding the necessary files 373.Em Note : 374the information below is valid as of the time this 375document was first written (March, 1995), but certain details 376such as names of ftp sites, directories and distribution names 377may have changed by the time you read this. 378.Pp 379Linux is distributed by several groups that make their own set 380of binaries that they distribute. Each distribution has its own 381name, like 382.Dq Slackware 383or 384.Dq Yggdrasil . 385The distributions are 386available on a lot of ftp sites. Sometimes the files are unpacked, 387and you can get the individual files you need, but mostly they 388are stored in distribution sets, usually consisting of subdirectories 389with gzipped tar files in them. The primary ftp sites for the 390distributions are: 391.Bl -item -compact -offset indent 392.It 393.Pa sunsite.unc.edu:/pub/Linux/distributions 394.It 395.Pa tsx-11.mit.edu:/pub/linux/distributions 396.El 397.Pp 398Some European mirrors: 399.Bl -item -compact -offset indent 400.It 401.Pa ftp.luth.se:/pub/linux/distributions 402.It 403.Pa ftp.demon.co.uk:/pub/linux/distributions 404.It 405.Pa src.doc.ic.ac.uk:/packages/linux/distributions 406.El 407.Pp 408For simplicity, let's concentrate on Slackware here. This distribution 409consists of a number of subdirectories, containing separate packages. 410Normally, they're controlled by an install program, but you can 411retrieve files 412.Dq by hand 413too. First of all, you will need to look 414in the 415.Pa contents 416subdir of the distribution. You will find 417a lot of small textfiles here describing the contents of the separate 418packages. The fastest way to look something up is to retrieve all 419the files in the contents subdirectory, and grep through them for the file 420you need. Here is an example of a list of files that you might need, and 421in which contents-file you will find it by grepping through them: 422.Pp 423.Bd -literal -offset indent 424Needed Package 425 426ld.so ldso 427ldconfig ldso 428ldd ldso 429libc.so.4 shlibs 430libX11.so.6.0 xf_lib 431libXt.so.6.0 xf_lib 432libX11.so.3 oldlibs 433libXt.so.3 oldlibs 434.Ed 435.Pp 436So, in this case, you will need the packages ldso, shlibs, xf_lib and oldlibs. 437In each of the contents-files for these packages, look for a line saying 438.Dq PACKAGE LOCATION , 439it will tell you on which 440.Sq disk 441the package is, 442in our case it will tell us in which subdirectory we need to look. 443For our example, we would find the following locations: 444.Pp 445.Bd -literal -offset indent 446Package Location 447 448ldso diska2 449shlibs diska2 450oldlibs diskx6 451xf_lib diskx9 452.Ed 453.Pp 454The locations called 455.Pa diskXX 456refer to the 457.Pa slakware/XX 458subdirectories 459of the distribution, others may be found in the 460.Pa contrib 461subdirectory. 462In this case, we could now retrieve the packages we need by retrieving 463the following files (relative to the root of the Slackware distribution 464tree): 465.Bl -item -compact 466.It 467.Pa slakware/a2/ldso.tgz 468.It 469.Pa slakware/a2/shlibs.tgz 470.It 471.Pa slakware/x6/oldlibs/tgz 472.It 473.Pa slakware/x9/xf_lib.tgz 474.El 475.Pp 476Extract the files from these gzipped tarfiles in your /emul/linux directory 477(possibly omitting or afterwards removing files you don't need), and you 478are done. 479.Ss Programs using SVGAlib 480SVGAlib binaries require some extra care. You need to have 481.Cd options WSDISPLAY_COMPAT_USL 482in your kernel (see 483.Xr wscons 4 ) , 484and you will also have to create 485some symbolic links in the 486.Pa /emul/linux/dev 487directory, namely: 488.Bl -item -compact 489.It 490.Pa /emul/linux/dev/console 491-\*[Gt] 492.Pa /dev/tty 493.It 494.Pa /emul/linux/dev/mouse 495-\*[Gt] whatever device your mouse is connected to 496.It 497.Pa /emul/linux/dev/ttyS0 498-\*[Gt] 499.Pa /dev/tty00 500.It 501.Pa /emul/linux/dev/ttyS1 502-\*[Gt] 503.Pa /dev/tty01 504.El 505.Pp 506Be warned: the first link mentioned here makes SVGAlib binaries 507work, but may confuse others, so you may have to remove it again at 508some point. 509.Sh BUGS 510The information about Linux distributions may become outdated. 511.Pp 512Pathnames pointed to by symbolic links are not looked up in the 513shadow root when running a Linux executable. This is not consistent. 514.Pp 515Linux executables can not handle directory offset cookies \*[Gt] 32 bits. 516Should such an offset occur, you will see the message 517.Dq linux_getdents: dir offset too large for emulated program . 518Currently, this can only 519happen on NFS mounted filesystems, mounted from servers that return 520offsets with information in the upper 32 bits. These errors should 521rarely happen, but can be avoided by mounting this filesystem with offset 522translation enabled. See the 523.Fl X 524option to 525.Xr mount_nfs 8 . 526The 527.Fl 2 528option to 529.Xr mount_nfs 8 530will also have the desired effect, but is less preferable. 531