408 lines
14 KiB
Groff
408 lines
14 KiB
Groff
.\" $NetBSD: compat_linux.8,v 1.14 1999/03/17 20:31:19 garbled Exp $
|
|
.\"
|
|
.\" Copyright (c) 1995 Frank van der Linden
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed for the NetBSD Project
|
|
.\" by Frank van der Linden
|
|
.\" 4. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd January 16, 1999
|
|
.Dt COMPAT_LINUX 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm compat_linux
|
|
.Nd setup procedure for running Linux binaries
|
|
.Sh DESCRIPTION
|
|
.Nx
|
|
supports running Linux binaries. This only applies to i386 systems
|
|
for now. Both the a.out and ELF binary formats are supported. Most programs
|
|
should work, including the ones that use the Linux SVGAlib. Programs that
|
|
will not work include the Linux /proc filesystem (which is different from
|
|
the optional
|
|
.Nx
|
|
/proc filesystem), and i386-specific calls, such as
|
|
enabling virtual 8086 mode. Currently, sound is only partially
|
|
supported for Linux binaries (they will probably run, depending on
|
|
what Linux sound support features are used).
|
|
|
|
The Linux compatibility feature is active
|
|
for kernels compiled with the
|
|
.Dv COMPAT_LINUX
|
|
option enabled.
|
|
If support for Linux a.out executables is desired, the
|
|
.Dv EXEC_AOUT
|
|
option should be enabled in addition to
|
|
.Dv COMPAT_LINUX .
|
|
Similarly, if support for Linux 32-bit and/or 64-bit ELF executables
|
|
is desired, the
|
|
.Dv EXEC_ELF32
|
|
and/or
|
|
.Dv EXEC_ELF64
|
|
options (respectively) should be enabled in addition to
|
|
.Dv COMPAT_LINUX .
|
|
.Pp
|
|
A lot of programs are dynamically linked. This means, that you will
|
|
also need the Linux shared libraries that the program depends on, and
|
|
the runtime linker. Also, you will need to create a "shadow root"
|
|
directory for Linux binaries on your
|
|
.Nx
|
|
system. This directory
|
|
is named /emul/linux. Any file operations done by Linux programs
|
|
run under
|
|
.Nx
|
|
will look in this directory first. So, if a Linux
|
|
program opens, for example, /etc/passwd,
|
|
.Nx
|
|
will
|
|
first try to open /emul/linux/etc/passwd, and if that does not exist
|
|
open the 'real' /etc/passwd file. It is recommended that you install
|
|
Linux packages that include configuration files, etc under /emul/linux,
|
|
to avoid naming conflicts with possible
|
|
.Nx
|
|
counterparts. Shared
|
|
libraries should also be installed in the shadow tree.
|
|
.Pp
|
|
Generally, you will need to look for the shared libraries that Linux
|
|
binaries depend on only the first few times that you install a Linux
|
|
program on your
|
|
.Nx
|
|
system. After a while, you will have a sufficient
|
|
set of Linux shared libraries on your system to be able to run newly
|
|
imported Linux binaries without any extra work.
|
|
|
|
.Ss Setting up shared libraries
|
|
How to get to know which shared libraries Linux binaries need, and where
|
|
to get them? Basically, there are 2 possibilities (when following
|
|
these instructions: you will need to be root on your
|
|
.Nx
|
|
system to
|
|
do the necessary installation steps).
|
|
|
|
.Bl -tag -width 123 -compact
|
|
.It 1.
|
|
You have access to a Linux system. In this case you can
|
|
temporarily install the binary there, see what shared libraries
|
|
it needs, and copy them to your
|
|
.Nx
|
|
system. Example: you have
|
|
just ftp-ed the Linux binary of Doom. Put it on the Linux
|
|
system you have access to, and check which shared libraries it
|
|
needs by running `ldd linuxxdoom':
|
|
.Pp
|
|
.Bl -tag -width 123 -compact -offset indent
|
|
.It (me@linux) ldd linuxxdoom
|
|
.nf
|
|
libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
|
|
libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
|
|
libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29
|
|
.fi
|
|
.El
|
|
.Pp
|
|
You would need go get all the files from the last column, and
|
|
put them under /emul/linux, with the names in the first column
|
|
as symbolic links pointing to them. This means you eventually have
|
|
these files on your
|
|
.Nx
|
|
system:
|
|
.Pp
|
|
.nf
|
|
/emul/linux/usr/X11/lib/libXt.so.3.1.0
|
|
/emul/linux/usr/X11/lib/libXt.so.3 (symbolic link to the above)
|
|
/emul/linux/usr/X11/lib/libX11.so.3.1.0
|
|
/emul/linux/usr/X11/lib/libX11.so.3 (symbolic link to the above)
|
|
/emul/linux/lib/libc.so.4.6.29
|
|
/emul/linux/lib/libc.so.4 (symbolic link to the above)
|
|
.fi
|
|
.Pp
|
|
Note that if you already have a Linux shared library with a
|
|
matching major revision number to the first column of the 'ldd'
|
|
output, you won't need to copy the file named in the last column
|
|
to your system, the one you already have should work. It is
|
|
advisable to copy the shared library anyway if it is a newer version,
|
|
though. You can remove the old one, as long as you make the symbolic
|
|
link point to the new one. So, if you have these libraries
|
|
on your system:
|
|
.Pp
|
|
.nf
|
|
/emul/linux/lib/libc.so.4.6.27
|
|
/emul/linux/lib/libc.so.4 -> /emul/linux/lib/libc.so.4.6.27
|
|
.fi
|
|
.Pp
|
|
and you find that the ldd output for a new binary you want to
|
|
install is:
|
|
.nf
|
|
.Pp
|
|
libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29
|
|
.fi
|
|
.Pp
|
|
you won't need to worry about copying /lib/libc.so.4.6.29 too,
|
|
because the program should work fine with the slightly older version.
|
|
You can decide to replace the libc.so anyway, and that should leave
|
|
you with:
|
|
.Pp
|
|
.nf
|
|
/emul/linux/lib/libc.so.4.6.29
|
|
/emul/linux/lib/libc.so.4 -> /emul/linux/lib/libc.so.4.6.29
|
|
.fi
|
|
.Pp
|
|
Please note that the symbolic link mechanism is
|
|
.Em only
|
|
needed for Linux binaries, the
|
|
.Nx
|
|
runtime linker takes care of
|
|
looking for matching major revision numbers itself, you
|
|
don't need to worry about that.
|
|
.Pp
|
|
Finally, you must make sure that you have the Linux runtime linker
|
|
and its config files on your system. You should copy these
|
|
files from the Linux system to their appropriate place on your
|
|
.Nx
|
|
system (in the /emul/linux tree):
|
|
.Pp
|
|
.nf
|
|
/lib/ld.so
|
|
/etc/ld.so.cache
|
|
/etc/ld.so.config
|
|
.fi
|
|
.Pp
|
|
.It 2.
|
|
You don't have access to a Linux system. In that case, you
|
|
should get the extra files you need from various ftp sites.
|
|
Information on where to look for the various files is appended
|
|
below. For now, let's assume you know where to get the files.
|
|
.Pp
|
|
Retrieve the following files (from _one_ ftp site to avoid
|
|
any version mismatches), and install them under /emul/linux
|
|
(i.e. /foo/bar is installed as /emul/linux/foo/bar):
|
|
.Pp
|
|
.nf
|
|
/sbin/ldconfig
|
|
/usr/bin/ldd
|
|
/lib/libc.so.x.y.z
|
|
/lib/ld.so
|
|
.fi
|
|
.Pp
|
|
ldconfig and ldd don't necessarily need to be under /emul/linux,
|
|
you can install them elsewhere in the system too. Just make sure
|
|
they don't conflict with their
|
|
.Nx
|
|
counterparts. A good idea
|
|
would be to install them in /usr/local/bin as ldconfig-linux and
|
|
ldd-linux.
|
|
.Pp
|
|
Create the file /emul/linux/etc/ld.so.conf, containing the
|
|
directories in which the Linux runtime linker should look
|
|
for shared libs. It is a plain text file, containing a directory
|
|
name on each line. /lib and /usr/lib are standard, you could
|
|
add the following:
|
|
.Pp
|
|
.nf
|
|
/usr/X11/lib
|
|
/usr/local/lib
|
|
.fi
|
|
.Pp
|
|
Note that these are mapped to /emul/linux/XXXX by
|
|
.Nx Ns 's
|
|
compat
|
|
code, and should exist as such on your system.
|
|
|
|
Run the Linux ldconfig program. It should be statically
|
|
linked, so it doesn't need any shared libraries by itself.
|
|
It will create the file /emul/linux/etc/ld.so.cache
|
|
You should rerun the Linux version of the ldconfig program
|
|
each time you add a new shared library.
|
|
.Pp
|
|
You should now be set up for Linux binaries which only need
|
|
a shared libc. You can test this by running the Linux ldd
|
|
on itself. Suppose that you have it installed as ldd-linux, it
|
|
should produce something like:
|
|
.Pp
|
|
.Bl -tag -width 123 -compact -offset indent
|
|
.It (me@netbsd) ldd-linux `which ldd-linux`
|
|
libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29
|
|
.El
|
|
.Pp
|
|
This being done, you are ready to install new Linux binaries.
|
|
Whenever you install a new Linux program, you should check
|
|
if it needs shared libraries, and if so, whether you have
|
|
them installed in the /emul/linux tree. To do this, you run
|
|
the Linux version ldd on the new program, and watch its output.
|
|
ldd (see also the manual page for
|
|
.Xr ldd 1 )
|
|
will print a list
|
|
of shared libraries that the program depends on, in the
|
|
form <majorname> (<jumpversion>) => <fullname>.
|
|
.Pp
|
|
If it prints "not found" in stead of <fullname> it means that
|
|
you need an extra library. Which library this is, is shown
|
|
in <majorname>, which will be of the form libXXXX.so.<N>
|
|
You will need to find a libXXXX.so.<N>.<mm> on a Linux ftp site,
|
|
and install it on your system. The XXXX (name) and <N> (major
|
|
revision number) should match; the minor number(s) <mm> are
|
|
less important, though it is advised to take the most
|
|
recent version.
|
|
.El
|
|
|
|
.Ss Setting up other files
|
|
Newer version of Linux use /etc/nsswitch.conf for network information,
|
|
such as
|
|
.Tn NIS
|
|
and DNS. You must create or get a valid copy of this file
|
|
and put it in /emul/linux/etc.
|
|
|
|
.Ss Finding the necessary files.
|
|
[
|
|
.Em Note:
|
|
As of October, 1998, a reasonable set of Linux libraries and other files
|
|
needed for Linux emulation may be obtained from
|
|
.Dl ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/linux_lib-2.5.tar.gz
|
|
It is recommended you try to retrieve this file (or a more recent
|
|
version) from ftp.freebsd.org first as this tar file contains
|
|
everything one typically needs and is is very simple to use for this
|
|
application. Failing that, see the instructions below.
|
|
]
|
|
.Pp
|
|
.Em Note:
|
|
the information below is valid as of the time this
|
|
document was written (March, 1995), but certain details
|
|
such as names of ftp sites, directories and distribution names
|
|
may have changed by the time you read this.
|
|
.Pp
|
|
Linux is distributed by several groups that make their own set
|
|
of binaries that they distribute. Each distribution has its own
|
|
name, like "Slackware" or "Yggdrasil". The distributions are
|
|
available on a lot of ftp sites. Sometimes the files are unpacked,
|
|
and you can get the individual files you need, but mostly they
|
|
are stored in distribution sets, usually consisting of subdirectories
|
|
with gzipped tar files in them. The primary ftp sites for the
|
|
distributions are:
|
|
.Pp
|
|
.nf
|
|
sunsite.unc.edu:/pub/Linux/distributions
|
|
tsx-11.mit.edu:/pub/linux/distributions
|
|
.fi
|
|
.Pp
|
|
Some European mirrors:
|
|
.Pp
|
|
.nf
|
|
ftp.luth.se:/pub/linux/distributions
|
|
ftp.demon.co.uk:/pub/linux/distributions
|
|
src.doc.ic.ac.uk:/packages/linux/distributions
|
|
.fi
|
|
.Pp
|
|
For simplicity, let's concentrate on Slackware here. This distribution
|
|
consists of a number of subdirectories, containing separate packages.
|
|
Normally, they're controlled by an install program, but you can
|
|
retrieve files "by hand" too. First of all, you will need to look
|
|
in the "contents" subdir of the distribution. You will find
|
|
a lot of small textfiles here describing the contents of the seperate
|
|
packages. The fastest way to look something up is to retrieve all
|
|
the files in the contents subdirectory, and grep through them for the file
|
|
you need. Here is an example of a list of files that you might need, and
|
|
in which contents-file you will find it by grepping through them:
|
|
.Pp
|
|
.Bd -unfilled -offset indent
|
|
Needed Package
|
|
|
|
ld.so ldso
|
|
ldconfig ldso
|
|
ldd ldso
|
|
libc.so.4 shlibs
|
|
libX11.so.6.0 xf_lib
|
|
libXt.so.6.0 xf_lib
|
|
libX11.so.3 oldlibs
|
|
libXt.so.3 oldlibs
|
|
.Ed
|
|
.Pp
|
|
So, in this case, you will need the packages ldso, shlibs, xf_lib and oldlibs.
|
|
In each of the contents-files for these packages, look for a line saying
|
|
"PACKAGE LOCATION", it will tell you on which 'disk' the package is,
|
|
in our case it will tell us in which subdirectory we need to look.
|
|
For our example, we would find the following locations:
|
|
.Pp
|
|
.Bd -unfilled -offset indent
|
|
Package Location
|
|
|
|
ldso diska2
|
|
shlibs diska2
|
|
oldlibs diskx6
|
|
xf_lib diskx9
|
|
.Ed
|
|
.Pp
|
|
The locations called "diskXX" refer to the "slakware/XX" subdirectories
|
|
of the distribution, others may be found in the "contrib" subdirectory.
|
|
In this case, we could now retrieve the packages we need by retrieving
|
|
the following files (relative to the root of the Slackware distribution
|
|
tree):
|
|
.Pp
|
|
.nf
|
|
slakware/a2/ldso.tgz
|
|
slakware/a2/shlibs.tgz
|
|
slakware/x6/oldlibs/tgz
|
|
slakware/x9/xf_lib.tgz
|
|
.fi
|
|
.Pp
|
|
Extract the files from these gzipped tarfiles in your /emul/linux directory
|
|
(possibly omitting or afterwards removing files you don't need), and you
|
|
are done.
|
|
|
|
.Ss Programs using SVGAlib
|
|
SVGAlib binaries require some extra care. The pcvt virtual console driver
|
|
has to be in the kernel for them to work, and you will also have to create
|
|
some symbloic links in the /emul/linux/dev directory, namely:
|
|
.Pp
|
|
.nf
|
|
/emul/linux/dev/console -> /dev/tty
|
|
/emul/linux/dev/mouse -> whatever device your mouse is connected to
|
|
/emul/linux/dev/ttyS0 -> /dev/tty00
|
|
/emul/linux/dev/ttyS1 -> /dev/tty01
|
|
.fi
|
|
.Pp
|
|
Be warned: the first link mentioned here makes SVGAlib binaries
|
|
work, but may confuse others, so you may have to remove it again at
|
|
some point.
|
|
.Sh BUGS
|
|
The information about Linux distributions may become outdated.
|
|
.Pp
|
|
Pathnames pointed to by symbolic links are not looked up in the
|
|
shadow root when running a Linux executable. This is not consistent.
|
|
.Pp
|
|
Linux executables can not handle directory offset cookies > 32 bits.
|
|
Should such an offset occur, you will see the message "linux_getdents:
|
|
dir offset too large for emulated program". Currently, this can only
|
|
happen on NFS mounted filesystems, mounted from servers that return
|
|
offsets with information in the upper 32 bits. These errors should
|
|
rarely happen, but can be avoided by mounting this filesystem with offset
|
|
translation enabled. See the
|
|
.Fl X
|
|
option to
|
|
.Xr mount_nfs 8 .
|
|
The
|
|
.Fl 2
|
|
option to
|
|
.Xr mount_nfs 8
|
|
will also have the desired effect, but is less preferable.
|