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