diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml index 517e5c2c02..d3f9315c46 100644 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml @@ -1,1283 +1,1244 @@ Jim Mock Restructured and parts updated by Brian N. Handy Originally contributed by Rich Murphey &linux; Binary Compatibility Synopsis Linux binary compatibility binary compatibility Linux &os; provides binary compatibility with &linux;, allowing users to install and run &linux; binaries on a &os; system. Many companies and developers develop only for &linux;, and binary compatibility allows &os; users to run about 90% of all &linux; applications without modification. This includes productivity applications, games, and more. It has even been reported that, in some situations, &linux; binaries perform better on &os; than they do on &linux;. However, some &linux;-specific operating system features are not supported under &os;. For example, &linux; binaries will not work on &os; if they overly use &i386; specific calls, such as enabling virtual 8086 mode. After reading this chapter, you will know: How to enable &linux; binary compatibility on a &os; system. How to install additional &linux; shared libraries. How to install &linux; applications on a &os; system. The implementation details of &linux; compatibility in &os;. Before reading this chapter, you should: Know how to install additional third-party software. Installation Ports Collection &linux; libararies are not installed on &os; by default and &linux; binary compatibility is not enabled by default. &linux; libraries can be installed using the &os; Ports Collection. Alternately, &linux; libraries can be installed manually. Using the Ports Collection is by far the easiest way to install &linux; libraries: &prompt.root; cd /usr/ports/emulators/linux_base-f10 &prompt.root; make install distclean Once the port is installed, enable &linux; binary compatibility by loading the linux module. Type the following as root: &prompt.root; kldload linux In order for &linux; compatibility to always be enabled at boot time, add the following line to /etc/rc.conf: linux_enable="YES" To verify that the module is loaded, use &man.kldstat.8;: &prompt.user; kldstat Id Refs Address Size Name 1 2 0xc0100000 16bdb8 kernel 7 1 0xc24db000 d000 linux.ko kernel options COMPAT_LINUX Users who prefer to statically link &linux; binary compatibility into the kernel should add options COMPAT_LINUX to the custom kernel configuration file. Compile and install the new kernel as described in . Installing Libraries Manually While using the Ports Collection is recommended, &linux; libraries can be installed manually. The &linux; shared libraries required by a program and the runtime linker should be copied to /compat/linux. Any shared libraries opened by &linux; programs run under &os; will look in this directory first. For example, if a &linux; program loads /lib/libc.so, &os; will first try to open /compat/linux/lib/libc.so, and if that does not exist, it will then try /lib/libc.so. Shared libraries should be installed to /compat/linux/lib rather than to the paths that the &linux; ld.so reports. Generally, one will need to look for the shared libraries that &linux; binaries depend on only the first few times that a &linux; program is installed on &os;. After a while, there will be a sufficient set of &linux; shared libraries on the system to be able to run newly imported &linux; binaries without any extra work. How to Install Additional Shared Libraries shared libraries If the linux_base port is installed and an application still complains about missing shared libraries, there are two methods root can use to determine which shared libraries the &linux; binaries need. If a &linux; system is available, determine which shared libraries the application needs, and copy them to the &os; system. In this example, FTP was used to download the &linux; binary of Doom on a &linux; system . To check which shared libraries it needs, run ldd linuxdoom: &prompt.user; ldd linuxdoom 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 symbolic links Copy all the files in the last column into /compat/linux on the &os; system, with the names in the first column as symbolic links pointing to them. This example will result in the following files on the &os; system: /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
If a &linux; shared library already exists with a matching major revision number to the first column of the ldd output, it does not need to be copied to the file named in the last column, as the existing library should work. It is advisable to copy the shared library if it is a newer version, though. The old one can be removed, as long as the symbolic link points to the new one. For example, these libraries exist on the system: /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 and a binary claims to require a later version according to the output of ldd: libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 If it is only one or two versions out of date in the trailing digit, do not worry about copying /lib/libc.so.4.6.29, because the program should work fine with the slightly older version. However, it is safe to replace the libc.so: /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
The symbolic link mechanism is only needed for &linux; binaries as the &os; runtime linker takes care of looking for matching major revision numbers.
Installing &linux; ELF Binaries Linux ELF binaries ELF binaries sometimes require an extra step of branding. If an unbranded ELF binary is executed, it will generate an error message like the following: &prompt.user; ./my-linux-elf-binary ELF binary type not known Abort To help the &os; kernel distinguish between a &os; ELF binary and a &linux; binary, use &man.brandelf.1;: &prompt.user; brandelf -t Linux my-linux-elf-binary GNU toolchain Since the GNU toolchain places the appropriate branding information into ELF binaries automatically, this step is usually not necessary. Installing a &linux; RPM Based Application &os; uses its own package database to track all software installed from the Ports Collection. However, the &linux; RPM database is not supported. In order to install a &linux; RPM-based application, first install the archivers/rpm2cpio package or port. Once installed, root can use this command to install a .rpm as follows: &prompt.root; cd /compat/linux &prompt.root; rpm2cpio -q < /path/to/linux.archive.rpm | cpio -id If necessary, brandelf the installed ELF binaries, but not the libraries. Note that this will prevent a clean uninstall. Configuring the Hostname Resolver If DNS does not work or this error appears: resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword Configure /compat/linux/etc/host.conf as follows: order hosts, bind multi on This order specifies that /etc/hosts is searched first and DNS is searched second. When /compat/linux/etc/host.conf does not exist, &linux; applications use /etc/host.conf and complain about the incompatible &os; syntax. Remove bind if a name server is not configured using /etc/resolv.conf. + Aaron Kaplan Contributed by Robert Getschmann Thanks to Installing &maple; applications Maple &maple; is a commercial mathematics program similar to &mathematica;. This software must be purchased and licensed from Maplesoft. To install the &linux; version of this software on &os;, follow these steps. Execute the INSTALL shell script from the product distribution. Choose the RedHat option when prompted by the installation program. A typical installation directory might be /usr/local/maple. Copy the license to /usr/local/maple/license/license.dat. Install the FLEXlm license manager by running the INSTALL_LIC install shell script that comes with &maple;. Specify the primary hostname for the machine for the license server. Patch /usr/local/maple/bin/maple.system.type with the following: ----- snip ------------------ *** maple.system.type.orig Sun Jul 8 16:35:33 2001 --- maple.system.type Sun Jul 8 16:35:51 2001 *************** *** 72,77 **** --- 72,78 ---- # the IBM RS/6000 AIX case MAPLE_BIN="bin.IBM_RISC_UNIX" ;; + "FreeBSD"|\ "Linux") # the Linux/x86 case # We have two Linux implementations, one for Red Hat and ----- snip end of patch ----- Note that no whitespace should be present after "FreeBSD"|\. This patch instructs &maple; to recognize &os; as a type of &linux; system. The bin/maple shell script calls the bin/maple.system.type shell script which in turn calls uname -a to find out the operating system name. Depending on the OS name it will find out which binaries to use. Start the license server. The following script, installed as /usr/local/rtc/rc.d/lmgrd is a convenient way to start up lmgrd: ----- snip ------------ #! /bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX export PATH LICENSE_FILE=/usr/local/maple/license/license.dat LOG=/var/log/lmgrd.log case "$1" in start) lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2 echo -n " lmgrd" ;; stop) lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2 ;; *) echo "Usage: `basename $0` {start|stop}" 1>&2 exit 64 ;; esac exit 0 ----- snip ------------ Test that &maple; starts: &prompt.user; cd /usr/local/maple/bin &prompt.user; ./xmaple Once everything is working, consider writing Maplesoft to let them know you would like a native &os; version! Common Pitfalls lmgrd is known to be picky about the license file and to dump core if there are any problems. A correct license file should look like this: # ======================================================= # License File for UNIX Installations ("Pointer File") # ======================================================= SERVER chillig ANY #USE_SERVER VENDOR maplelmg FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \ ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \ SN=XXXXXXXXX In this example, the serial number and key were replaced with X. chillig is the hostname. Editing the license file works as long as the FEATURE line is not edited. That line is protected by the license key. Dan Pelleg Contributed by Installing &matlab; applications MATLAB This document describes the process of installing the &linux; version of &matlab; version 6.5 onto a &os; system. It works quite well, with the exception of the &java.virtual.machine; which is described further in . The &linux; version of &matlab; can be purchased and licensed from MathWorks. Consider letting the company know that you would like a native &os; version of this software. Installing &matlab; To install &matlab;: Become root, as recommended by the installation script. Insert the installation CD and mount it. To start the installation script type: &prompt.root; /compat/linux/bin/sh /cdrom/install The installer is graphical. If it is not able to open a display, type setenv HOME ~USER, where USER is the user who ran &man.su.1;. When asked for the &matlab; root directory, type: /compat/linux/usr/local/matlab. For easier typing on the rest of the installation process, type this at the shell prompt: set MATLAB=/compat/linux/usr/local/matlab. Edit the license file as instructed when obtaining the &matlab; license. This file can be prepared in advance using an editor, and copied to $MATLAB/license.dat before the installer asks to edit it. Complete the installation process. At this point the &matlab; installation is complete. The following steps apply glue to connect it to the &os; system. License Manager Startup Create symlinks for the license manager scripts: &prompt.root; ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW &prompt.root; ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW Create a startup file named /usr/local/etc/rc.d/flexlm. The example below is a modified version of the distributed $MATLAB/etc/rc.lm.glnx86. The changes are file locations and startup of the license manager under &linux; emulation. #!/bin/sh case "$1" in start) if [ -f /usr/local/etc/lmboot_TMW ]; then /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u username && echo 'MATLAB_lmgrd' fi ;; stop) if [ -f /usr/local/etc/lmdown_TMW ]; then /compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1 fi ;; *) echo "Usage: $0 {start|stop}" exit 1 ;; esac exit 0 The file must be made executable: &prompt.root; chmod +x /usr/local/etc/rc.d/flexlm Replace username with the name of a valid user on the system which is not root. Start the license manager with the command: &prompt.root; service flexlm start Linking the &java; Runtime Environment Change the &java; Runtime Environment (JRE) link to one working under &os;: &prompt.root; cd $MATLAB/sys/java/jre/glnx86/ &prompt.root; unlink jre; ln -s ./jre1.1.8 ./jre Creating a &matlab; Startup Script Place the following startup script in /usr/local/bin/matlab: #!/bin/sh /compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@" Then, type the command chmod +x /usr/local/bin/matlab. Depending on the version of emulators/linux_base, running this script may result in errors. To avoid errors, edit /compat/linux/usr/local/matlab/bin/matlab, and change the line that says: if [ `expr "$lscmd" : '.*->.*'` -ne 0 ]; then to this line: if test -L $newbase; then Creating a &matlab; Shutdown Script The following is needed to solve a problem with &matlab; not exiting correctly. Create $MATLAB/toolbox/local/finish.m containing the single line: ! $MATLAB/bin/finish.sh The $MATLAB is literal. The same directory contains finishsav.m and finishdlg.m, which allow the workspace to be saved before quitting. If either file is used, insert the line above immediately after the save command. Create $MATLAB/bin/finish.sh which contains the following: #!/compat/linux/bin/sh (sleep 5; killall -1 matlab_helper) & exit 0 Make the file executable: &prompt.root; chmod +x $MATLAB/bin/finish.sh Using &matlab; At this point, matlab is ready for use. Marcel Moolenaar Contributed by Installing &oracle; applications Oracle This document describes the process of installing &oracle; 8.0.5 and &oracle; 8.0.5.1 Enterprise Edition for &linux; onto a &os; machine. Installing the &linux; Environment Make sure emulators/linux_base has been installed from the Ports Collection. To run the intelligent agent, install the Red Hat Tcl package: tcl-8.0.3-20.i386.rpm. The general command for installing RPMs with the archivers/rpm port is: &prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package This command should not generate any errors. Creating the &oracle; Environment Before installing &oracle;, set up a proper environment. This section only describes how to install &oracle; for &linux; on &os;, not what has been described in the &oracle; installation guide. Kernel Tuning kernel tuning As described in the &oracle; installation guide, the maximum size of shared memory needs to be set. Do not use SHMMAX under &os; as it is calculated from SHMMAXPGS and PGSIZE. Therefore, define SHMMAXPGS. All other options can be used as described in the guide. For example: options SHMMAXPGS=10000 options SHMMNI=100 options SHMSEG=10 options SEMMNS=200 options SEMMNI=70 options SEMMSL=61 Set these options to suit the intended use of &oracle;. Also, make sure the following options are in the kernel configuration file: options SYSVSHM #SysV shared memory options SYSVSEM #SysV semaphores options SYSVMSG #SysV interprocess communication &oracle; Account Create a user account to be used as the oracle account. Add /compat/linux/bin/bash to /etc/shells and set the shell for the oracle account to /compat/linux/bin/bash. Environment Besides the normal &oracle; variables, such as ORACLE_HOME and ORACLE_SID set the following environment variables: Variable Value LD_LIBRARY_PATH $ORACLE_HOME/lib CLASSPATH $ORACLE_HOME/jdbc/lib/classes111.zip PATH /compat/linux/bin /compat/linux/sbin /compat/linux/usr/bin /compat/linux/usr/sbin /bin /sbin /usr/bin /usr/sbin /usr/local/bin $ORACLE_HOME/bin It is advised to set all the environment variables in ~/.profile as follows: ORACLE_BASE=/oracle; export ORACLE_BASE ORACLE_HOME=/oracle; export ORACLE_HOME LD_LIBRARY_PATH=$ORACLE_HOME/lib export LD_LIBRARY_PATH ORACLE_SID=ORCL; export ORACLE_SID ORACLE_TERM=386x; export ORACLE_TERM CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip export CLASSPATH PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin export PATH Installing &oracle; Before starting the installer, create a directory named /var/tmp/.oracle which is owned by the oracle user. The installation of &oracle; should work without any problems. If errors are encountered, check the &oracle; distribution and configuration. Once &oracle; is installed, apply the patches described in the next two subsections. A frequent error is that the TCP protocol adapter is not installed correctly. As a consequence, no TCP listeners can be started. The following actions help to solve this problem: &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk ntcontab.o &prompt.root; cd $ORACLE_HOME/lib &prompt.root; ar r libnetwork.a ntcontab.o &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk install Do not forget to run root.sh again. Patching <filename>root.sh</filename> When installing &oracle;, some actions, which need to be performed as root, are recorded in a shell script called root.sh. This script is found in orainst. Apply the following patch to root.sh so that it can find the &os; location of chown. Alternatively, run the script under a &linux; native shell. *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 --- orainst/root.sh Mon Dec 28 15:58:53 1998 *************** *** 31,37 **** # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/bin/chown # # Define variables to be used in this script --- 31,37 ---- # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/usr/sbin/chown # # Define variables to be used in this script If &oracle; is not installed from CD, patch the source for root.sh. It is called rthd.sh and is located in orainst in the source tree. Patching <filename>genclntsh</filename> The script genclntsh is used to create a single shared client library when building the demos. Apply the following patch to comment out the definition of PATH: *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 --- bin/genclntsh Tue Dec 22 15:36:49 1998 *************** *** 32,38 **** # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! PATH=/usr/local/bin:/bin:/usr/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst --- 32,38 ---- # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! #PATH=/usr/local/bin:/bin:/usr/bin: export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst Running &oracle; After following these instructions, &oracle; should run as if it was running on &linux;. Advanced Topics This section describes how &linux; binary compatibility works and is based on an email written to &a.chat; by Terry Lambert tlambert@primenet.com (Message ID: <199906020108.SAA07001@usr09.primenet.com>). execution class loader &os; has an abstraction called an execution class loader. This is a wedge into the &man.execve.2; system call. Historically, the &unix; loader examined the magic number (generally the first 4 or 8 bytes of the file) to see if it was a binary known to the system, and if so, invoked the binary loader. If it was not the binary type for the system, the &man.execve.2; call returned a failure, and the shell attempted to start executing it as shell commands. The assumption was a default of whatever the current shell is. Later, a hack was made for &man.sh.1; to examine the first two characters, and if they were :\n, it invoked the &man.csh.1; shell instead. &os; has a list of loaders, instead of a single loader, with a fallback to the #! loader for running shell interpreters or shell scripts. ELF Solaris For the &linux; ABI support, &os; sees the magic number as an ELF binary. The ELF loader looks for a specialized brand, which is a comment section in the ELF image, and which is not present on SVR4/&solaris; ELF binaries. For &linux; binaries to function, they must be branded as type Linux using &man.brandelf.1;: &prompt.root; brandelf -t Linux file ELF branding When the ELF loader sees the Linux brand, the loader replaces a pointer in the proc structure. All system calls are indexed through this pointer. In addition, the process is flagged for special handling of the trap vector for the signal trampoline code, and several other (minor) fix-ups that are handled by the &linux; kernel module. The &linux; system call vector contains, among other things, a list of sysent[] entries whose addresses reside in the kernel module. When a system call is called by the &linux; binary, the trap code dereferences the system call function pointer off the proc structure, and gets the &linux;, not the &os;, system call entry points. &linux; mode dynamically reroots lookups. This is, in effect, equivalent to the option to file system mounts. First, an attempt is made to lookup the file in /compat/linux/original-path. If that fails, the lookup is done in /original-path. This makes sure that binaries that require other binaries can run. For example, the &linux; toolchain can all run under &linux; ABI support. It also means that the &linux; binaries can load and execute &os; binaries, if there are no corresponding &linux; binaries present, and that a &man.uname.1; command can be placed in the /compat/linux directory tree to ensure that the &linux; binaries can not tell they are not running on &linux;. In effect, there is a &linux; kernel in the &os; kernel. The various underlying functions that implement all of the services provided by the kernel are identical to both the &os; system call table entries, and the &linux; system call table entries: file system operations, virtual memory operations, signal delivery, and System V IPC. The only difference is that &os; binaries get the &os; glue functions, and &linux; binaries get the &linux; glue functions. The &os; glue functions are statically linked into the kernel, and the &linux; glue functions can be statically linked, or they can be accessed via a kernel module. Technically, this is not really emulation, it is an ABI implementation. It is sometimes called &linux; emulation because the implementation was done at a time when there was no other word to describe what was going on. Saying that &os; ran &linux; binaries was not true, since the code was not compiled in.