diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
index 7a6feef5bf..daa4c89c55 100644
--- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
@@ -1,2194 +1,2248 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD: doc/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml,v 1.38 2001/06/06 20:14:38 chris Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml,v 1.39 2001/06/26 15:40:22 phantom Exp $
-->
<chapter id="linuxemu">
<title>Linux Binary Compatibility</title>
<para><emphasis>Restructured and parts updated by &a.jim;, 22 March
2000. Originally contributed by &a.handy; and
&a.rich;</emphasis></para>
<sect1>
<title>Synopsis</title>
+ <indexterm><primary>Linux binary compatibility</primary></indexterm>
+ <indexterm>
+ <primary>binary compatibility</primary>
+ <secondary>Linux</secondary>
+ </indexterm>
<para>The following chapter will cover FreeBSD's Linux binary
compatibility features, how to install it, and how it works.</para>
<para>At this point, you may be asking yourself why exactly, does
FreeBSD need to be able to run Linux binaries? The answer to that
question is quite simple. Many companies and developers develop
only for Linux, since it is the latest <quote>hot thing</quote> in
the computing world. That leaves the rest of us FreeBSD users
bugging these same companies and developers to put out native
FreeBSD versions of their applications. The problem is, that most
of these companies do not really realize how many people would use
their product if there were FreeBSD versions too, and most continue
to only develop for Linux. So what is a FreeBSD user to do? This
is where the Linux binary compatibility of FreeBSD comes into
play.</para>
<para>In a nutshell, the compatibility allows FreeBSD users to run
about 90% of all Linux applications without modification. This
includes applications such as Star Office, the Linux version of
Netscape, Adobe Acrobat, RealPlayer 5 and 7, VMWare, Oracle,
WordPerfect, Doom, Quake, and more. It is also reported that in
some situations, Linux binaries perform better on FreeBSD than they
do under Linux.</para>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary><filename>/proc</filename> filesystem</secondary>
+ </indexterm>
<para>There are, however, some Linux-specific operating system
features that are not supported under FreeBSD. Linux binaries will
not work on FreeBSD if they overly use the Linux
<filename>/proc</filename> filesystem (which is different from
FreeBSD's <filename>/proc</filename> filesystem), or i386-specific
calls, such as enabling virtual 8086 mode.</para>
<para>For information on installing the Linux binary compatibility
mode, see the <link linkend="linuxemu-lbc-install">next section</link>.</para>
</sect1>
<sect1 id="linuxemu-lbc-install">
<title>Installation</title>
<para>With the advent of 3.0-RELEASE, it is no longer necessary to
specify <literal>options LINUX</literal> or
<literal>options COMPAT_LINUX</literal> in your kernel
configuration.</para>
+ <indexterm><primary>KLD (kernel loadable object)</primary></indexterm>
<para>The Linux binary compatibility is now done via a KLD object
(<quote>Kernel LoaDable object</quote>), so it can be installed
<quote>on-the-fly</quote> without having to reboot. You will,
however, need to have the following in
<filename>/etc/rc.conf</filename>:</para>
<programlisting>linux_enable=<quote>YES</quote></programlisting>
<para>This, in turn, triggers the following action in
<filename>/etc/rc.i386</filename>:</para>
<programlisting># Start the Linux binary compatibility if requested.
#
case ${linux_enable} in
[Yy][Ee][Ss])
echo -n ' linux'; linux > /dev/null 2>&1
;;
esac</programlisting>
<para>If you wish to verify that the KLD is loaded,
<command>kldstat</command> will do that:</para>
<screen>&prompt.user; <userinput>kldstat</userinput>
Id Refs Address Size Name
1 2 0xc0100000 16bdb8 kernel
7 1 0xc24db000 d000 linux.ko</screen>
+ <indexterm>
+ <primary>kernel options</primary>
+ <secondary>LINUX</secondary>
+ </indexterm>
<para>If for some reason you do not want to or cannot load the KLD,
then you may statically link the binary compatibility in the kernel
by adding <literal>options LINUX</literal> to your kernel
configuration file. Then install your new kernel as described in
the <link linkend="kernelconfig">kernel configuration</link> section
of this handbook.</para>
<sect2>
<title>Installing Linux Runtime Libraries</title>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>installing Linux libraries</secondary>
+ </indexterm>
- <para>This can be done one of two ways, either by using the <link
- linkend="linuxemu-libs-port">linux_base</link> port, or by installing them
- <link linkend="linuxemu-libs-manually">manually</link>.</para>
+ <para>This can be done one of two ways, either by using the
+ <link linkend="linuxemu-libs-port">linux_base</link> port, or
+ by installing them <link
+ linkend="linuxemu-libs-manually">manually</link>.</para>
<sect3 id="linuxemu-libs-port">
<title>Installing using the linux_base port</title>
+ <indexterm><primary>ports collection</primary></indexterm>
<para>This is by far the easiest method to use when installing the
runtime libraries. It is just like installing any other port
from the <ulink url="/ports/">ports collection</ulink>.
Simply do the following:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
&prompt.root; <userinput>make install distclean</userinput></screen>
<para>You should now have working Linux binary compatibility.
Some programs may complain about incorrect minor versions of the
system libraries. In general, however, this does not seem to be
a problem.</para>
</sect3>
<sect3 id="linuxemu-libs-manually">
<title>Installing libraries manually</title>
<para>If you do not have the <quote>ports</quote> collection
installed, you can install the libraries by hand instead. You
will need the Linux shared libraries that the program depends on
and the runtime linker. Also, you will need to create a
<quote>shadow root</quote> directory,
<filename>/compat/linux</filename>, for Linux libraries on your
FreeBSD system. Any shared libraries opened by Linux programs
run under FreeBSD will look in this tree first. So, if a Linux
program loads, for example, <filename>/lib/libc.so</filename>,
FreeBSD will first try to open
<filename>/compat/linux/lib/libc.so</filename>, and if that does
not exist, it will then try <filename>/lib/libc.so</filename>.
Shared libraries should be installed in the shadow tree
<filename>/compat/linux/lib</filename> rather than the paths
that the Linux <command>ld.so</command> reports.</para>
<para>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 FreeBSD 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.</para>
</sect3>
<sect3>
<title>How to install additional shared libraries</title>
+ <indexterm><primary>shared libraries</primary></indexterm>
<para>What if you install the <filename>linux_base</filename> port
and your application still complains about missing shared
libraries? How do you 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 FreeBSD system).</para>
<para>If you have access to a Linux system, see what shared
libraries the application needs, and copy them to your FreeBSD
system. Look at the following example:</para>
<informalexample>
<para>Let us assume you used FTP to get the Linux binary of
Doom, and put it on a Linux system you have access to. You
then can check which shared libraries it needs by running
<command>ldd linuxdoom</command>, like so:</para>
<screen>&prompt.user; <userinput>ldd linuxdoom</userinput>
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</screen>
+ <indexterm><primary>symbolic links</primary></indexterm>
<para>You would need to get all the files from the last column,
and put them under <filename>/compat/linux</filename>, with
the names in the first column as symbolic links pointing to
them. This means you eventually have these files on your
FreeBSD system:</para>
<screen>/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</screen>
<blockquote>
<note>
<para>Note that if you already have a Linux shared library
with a matching major revision number to the first column
of the <command>ldd</command> output, you will not 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:</para>
<screen>/compat/linux/lib/libc.so.4.6.27
/compat/linux/lib/libc.so.4 -> libc.so.4.6.27</screen>
<para>and you find a new binary that claims to require a
later version according to the output of
<command>ldd</command>:</para>
<screen>libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29</screen>
<para>If it is only one or two versions out of date in the
in the trailing digit then do not worry about copying
<filename>/lib/libc.so.4.6.29</filename> too, because the
program should work fine with the slightly older version.
However, if you like, you can decide to replace the
<filename>libc.so</filename> anyway, and that should leave
you with:</para>
<screen>/compat/linux/lib/libc.so.4.6.29
/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen>
</note>
</blockquote>
<blockquote>
<note>
<para>The symbolic link mechanism is
<emphasis>only</emphasis> needed for Linux binaries. The
FreeBSD runtime linker takes care of looking for matching
major revision numbers itself and you do not need to worry
about it.</para>
</note>
</blockquote>
</informalexample>
</sect3>
</sect2>
<sect2>
<title>Installing Linux ELF binaries</title>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>ELF binaries</secondary>
+ </indexterm>
<para>ELF binaries sometimes require an extra step of
<quote>branding</quote>. If you attempt to run an unbranded ELF
binary, you will get an error message like the following;</para>
<screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
ELF binary type not known
Abort</screen>
<para>To help the FreeBSD kernel distinguish between a FreeBSD ELF
binary from a Linux binary, use the &man.brandelf.1;
utility.</para>
<screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
+ <indexterm><primary>GNU toolchain</primary></indexterm>
<para>The GNU toolchain now places the appropriate branding
information into ELF binaries automatically, so you this step
should become increasingly more rare in the future.</para>
</sect2>
<sect2>
<title>Configuring the host name resolver</title>
<para>If DNS does not work or you get this message:</para>
<screen>resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keyword</screen>
<para>You will need to configure a
<filename>/compat/linux/etc/host.conf</filename> file
containing:</para>
<programlisting>order hosts, bind
multi on</programlisting>
<para>The order here specifies that <filename>/etc/hosts</filename>
is searched first and DNS is searched second. When
<filename>/compat/linux/etc/host.conf</filename> is not
installed, linux applications find FreeBSD's
<filename>/etc/host.conf</filename> and complain about the
incompatible FreeBSD syntax. You should remove
<literal>bind</literal> if you have not configured a name server
using the <filename>/etc/resolv.conf</filename> file.</para>
</sect2>
</sect1>
<sect1 id="linuxemu-mathematica">
<title>Installing Mathematica</title>
<para><emphasis>Updated for Mathematica version 4.x by &a.murray
and merged with work by Bojan Bistrovic
<email>bojanb@physics.odu.edu</email>.</emphasis></para>
+ <indexterm>
+ <primary>applications</primary>
+ <secondary><application>Mathematica</application></secondary>
+ </indexterm>
<para>This document describes the process of installing the Linux
version of Mathematica 4.X onto a FreeBSD system.</para>
<para>The Linux version of Mathematica runs perfectly under FreeBSD
however the binaries shipped by Wolfram need to be branded so that
FreeBSD knows to use the Linux ABI to execute them.</para>
<para>The Linux version of Mathematica or Mathematica for Students can
be ordered directly from Wolfram at <ulink
url="http://www.wolfram.com/">http://www.wolfram.com/</ulink>.</para>
<sect2>
<title>Branding the Linux binaries</title>
<para>The Linux binaries are located in the <filename>Unix</filename>
directory of the Mathematica CDROM distributed by Wolfram. You
need to copy this directory tree to your local hard drive so that
you can brand the Linux binaries with &man.brandelf.1; before
running the installer:</para>
<screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cp -rp /cdrom/Unix/ /localdir/</userinput>
&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*</userinput>
&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*</userinput>
&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*</userinput>
&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*</userinput>
&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*</userinput>
&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm</userinput>
&prompt.root; <userinput>cd /localdir/Installers/Linux/</userinput>
&prompt.root; <userinput>./MathInstaller</userinput></screen>
<para>Alternatively, you can simply set the default ELF brand
to Linux for all unbranded binaries with the command:</para>
<screen>&prompt.root; <userinput>sysctl -w kern.fallback_elf_brand=3</userinput>
</screen>
<para>This will make FreeBSD assume that unbranded ELF binaries
use the Linux ABI and so you should be able to run the
installer straight from the CDROM.</para>
</sect2>
<sect2>
<title>Obtaining your Mathematica Password</title>
<para>Before you can run Mathematica you will have to obtain a
password from Wolfram that corresponds to your <quote>machine
ID</quote>.</para>
+ <indexterm>
+ <primary>Ethernet</primary>
+ <secondary>MAC address</secondary>
+ </indexterm>
<para>Once you have installed the Linux compatibility runtime
libraries and unpacked Mathematica you can obtain the
<quote>machine ID</quote> by running the program
<command>mathinfo</command> in the Install directory. This
machine ID is based solely on the MAC address of your first
ethernet card.</para>
<screen>&prompt.root; <userinput>cd /localdir/Files/SystemFiles/Installation/Binaries/Linux</userinput>
&prompt.root; <userinput>mathinfo</userinput>
disco.example.com 7115-70839-20412</screen>
<para>When you register with Wolfram, either by email, phone or fax,
you will give them the <quote>machine ID</quote> and they will
respond with a corresponding password consisting of groups of
numbers. You can then enter this information when you attempt to
run Mathematica for the first time exactly as you would for any
other Mathematica platform.</para>
</sect2>
<sect2>
<title>Running the Mathematica front end over a network</title>
<para>Mathematica uses some special fonts to display characters not
present in any of the standard font sets (integrals, sums, greek
letters, etc.). The X protocol requires these fonts to be install
<emphasis>locally</emphasis>. This means you will have to copy
these fonts from the CDROM or from a host with Mathematica
installed to your local machine. These fonts are normally stored
in <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on the
CDROM, or
<filename>/usr/local/mathematica/SystemFiles/Fonts</filename> on
your hard drive. The actual fonts are in the subdirectories
<filename>Type1</filename> and <filename>X</filename>. There are
several ways to use them, as described below.</para>
<para>The first way is to copy them into one of the existing font
directories in <filename>/usr/X11R6/lib/X11/fonts</filename>.
This will require editing the <filename>fonts.dir</filename> file,
adding the font names to it, and changing the number of fonts on
the first line. Alternatively, you should also just be able to
run <command>mkfontdir</command> in the directory you have copied
them to.</para>
<para>The second way to do this is to copy the directories to
<filename>/usr/X11R6/lib/X11/fonts</filename>:</para>
<screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts</userinput>
&prompt.root; <userinput>mkdir X</userinput>
&prompt.root; <userinput>mkdir MathType1</userinput>
&prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput>
&prompt.root; <userinput>cp X/* /usr/X11R6/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput>
&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>mkfontdir</userinput>
&prompt.root; <userinput>cd ../MathType1</userinput>
&prompt.root; <userinput>mkfontdir</userinput</screen>
<para>Now add the new font directories to your font path:</para>
<screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput>
&prompt.root; <userinput>xset fp rehash</userinput></screen>
<para>If you are using the XFree86 server, you can have these font
directories loaded automatically by adding them to your
<filename>XF86Config</filename> file.</para>
+ <indexterm><primary>fonts</primary></indexterm>
<para>If you <emphasis>do not</emphasis> already have a directory
called <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you
can change the name of the <filename>MathType1</filename>
directory in the example above to
<filename>Type1</filename>.</para>
</sect2>
</sect1>
<sect1 id="linuxemu-oracle">
<title>Installing Oracle</title>
<para><emphasis>Contributed by Marcel Moolenaar
<email>marcel@cup.hp.com</email></emphasis></para>
-
+ <indexterm>
+ <primary>applications</primary>
+ <secondary><application>Oracle</application></secondary>
+ </indexterm>
+
<sect2>
<title>Preface</title>
<para>This document describes the process of installing Oracle 8.0.5 and
Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD
machine</para>
</sect2>
<sect2>
<title>Installing the Linux environment</title>
<para>Make sure you have both <filename>linux_base</filename> and
<filename>linux_devtools</filename> from the ports collection
installed. These ports are added to the collection after the release
of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for
that matter, update your ports collection. You may want to consider
updating your FreeBSD version too. If you run into difficulties with
<filename>linux_base-6.1</filename> or
<filename>linux_devtools-6.1</filename> you may have to use version
5.2 of these packages.</para>
<para>If you want to run the intelligent agent, you'll
also need to install the Red Hat TCL package:
<filename>tcl-8.0.3-20.i386.rpm</filename>. The general command
for installing packages with the official RPM port is :</para>
<screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>
<para>Installation of the package should not generate any errors.</para>
</sect2>
<sect2>
<title>Creating the Oracle environment</title>
<para>Before you can install Oracle, you need to set up a proper
environment. This document only describes what to do
<emphasis>specially</emphasis> to run Oracle for Linux on FreeBSD, not
what has been described in the Oracle installation guide.</para>
<sect3 id="linuxemu-kernel-tuning">
<title>Kernel Tuning</title>
+ <indexterm><primary>kernel tuning</primary></indexterm>
<para>As described in the Oracle installation guide, you need to set
the maximum size of shared memory. Don't use
<literal>SHMMAX</literal> under FreeBSD. <literal>SHMMAX</literal>
is merely calculated out of <literal>SHMMAXPGS</literal> and
<literal>PGSIZE</literal>. Therefore define
<literal>SHMMAXPGS</literal>. All other options can be used as
described in the guide. For example:</para>
<programlisting>options SHMMAXPGS=10000
options SHMMNI=100
options SHMSEG=10
options SEMMNS=200
options SEMMNI=70
options SEMMSL=61</programlisting>
<para>Set these options to suit your intended use of Oracle.</para>
<para>Also, make sure you have the following options in your kernel
config-file:</para>
<programlisting>options SYSVSHM #SysV shared memory
options SYSVSEM #SysV semaphores
options SYSVMSG #SysV interprocess communication</programlisting>
</sect3>
<sect3 id="linuxemu-oracle-account">
<title>Oracle account</title>
<para>Create an Oracle account just as you would create any other
account. The Oracle account is special only that you need to give
it a Linux shell. Add <literal>/compat/linux/bin/bash</literal> to
<filename>/etc/shells</filename> and set the shell for the Oracle
account to <filename>/compat/linux/bin/bash</filename>.</para>
</sect3>
<sect3 id="linuxemu-environment">
<title>Environment</title>
<para>Besides the normal Oracle variables, such as
<envar>ORACLE_HOME</envar> and <envar>ORACLE_SID</envar> you must
set the following environment variables:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Variable</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>LD_LIBRARY_PATH</envar></entry>
<entry><literal>$ORACLE_HOME/lib</literal></entry>
</row>
<row>
<entry><envar>CLASSPATH</envar></entry>
<entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry>
</row>
<row>
<entry><envar>PATH</envar></entry>
<entry><literal>/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</literal></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>It is advised to set all the environment variables in
<filename>.profile</filename>. A complete example is:</para>
<programlisting>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:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:$ORACLE_HOME/bin
export PATH</programlisting>
</sect3>
</sect2>
<sect2>
<title>Installing Oracle</title>
<para>Due to a slight inconsistency in the Linux emulator, you need to
create a directory named <filename>.oracle</filename> in
<filename>/var/tmp</filename> before you start the installer. Either
make it world writable or let it be owner by the oracle user. You
should be able to install Oracle without any problems. If you have
problems, check your Oracle distribution and/or configuration first!
After you have installed Oracle, apply the patches described in the
next two subsections.</para>
<para>A frequent problem is that the TCP protocol adapter is not
installed right. As a consequence, you cannot start any TCP listeners.
The following actions help solve this problem:</para>
<screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
&prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput>
&prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput>
&prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput>
&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
&prompt.root; <userinput>make -f ins_network.mk install</userinput></screen>
<para>Don't forget to run <filename>root.sh</filename> again!</para>
<sect3 id="linuxemu-patch-root">
<title>Patching root.sh</title>
<para>When installing Oracle, some actions, which need to be performed
as <username>root</username>, are recorded in a shell script called
<filename>root.sh</filename>. <filename>root.sh</filename> is
written in the <filename>orainst</filename> directory. Apply the
following patch to root.sh, to have it use to proper location of
chown or alternatively run the script under a Linux native
shell.</para>
<programlisting>*** 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</programlisting>
<para>When you don't install Oracle from CD, you can patch the source
for <filename>root.sh</filename>. It is called
<filename>rthd.sh</filename> and is located in the
<filename>orainst</filename> directory in the source tree.</para>
</sect3>
<sect3 id="linuxemu-patch-tcl">
<title>Patching genclntsh</title>
<para>The script genclntsh is used to create a single shared client
library. It is used when building the demos. Apply the following
patch to comment out the definition of PATH:</para>
<programlisting>*** 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:/usr/X11R6/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:/usr/X11R6/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
</sect3>
</sect2>
<sect2>
<title>Running Oracle</title>
<para>When you have followed the instructions, you should be able to run
Oracle as if it was run on Linux itself.</para>
</sect2>
</sect1>
<sect1 id="sapr3">
<title>Installing SAP R/3 (4.6B - IDES)</title>
<para><emphasis>Contributed by Holger Kipp</emphasis> <email>holger.kipp@alogis.com</email></para>
<para><emphasis>Converted to SGML by &a.logo;</emphasis></para>
-
+ <indexterm>
+ <primary>applications</primary>
+ <secondary><application>SAP R/3</application></secondary>
+ </indexterm>
<sect2 id="preface">
<title>Preface</title>
<para>This document describes a possible way of installing a SAP
R/3 4.6B IDES-System with Oracle 8.0.5 for Linux onto a
FreeBSD 4.3 machine, including the installation of FreeBSD 4.3
stable and Oracle 8.0.5.</para>
<para>Even though this document tries to describe all important
steps in a greater detail, it is not intended as a replacement
for the Oracle and SAP R/3 installation guides.</para>
<para>Please see the documentation that comes with the SAP R/3
Linux edition for SAP- and Oracle-specific questions, as well
as resources from Oracle and SAP OSS.</para>
</sect2>
<sect2 id="software">
<title>Software</title>
<para>The following CD-ROMs have been used for
SAP-installation:</para>
<informaltable>
<tgroup cols=3>
<thead>
<row>
<entry>Name</entry> <entry>Number</entry> <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>KERNEL</entry> <entry>51009113</entry> <entry>SAP Kernel Oracle /
Installation / AIX, Linux, Solaris</entry>
</row>
<row>
<entry>RDBMS</entry> <entry>51007558</entry> <entry>Oracle / RDBMS 8.0.5.X /
Linux</entry>
</row>
<row>
<entry>EXPORT1</entry> <entry>51010208</entry> <entry>IDES / DB-Export / Disc
1 of 6</entry>
</row>
<row>
<entry>EXPORT2</entry> <entry>51010209</entry> <entry>IDES / DB-Export / Disc
2 of 6</entry>
</row>
<row>
<entry>EXPORT3</entry> <entry>51010210</entry> <entry>IDES / DB-Export /
Disc3 of 6</entry>
</row>
<row>
<entry>EXPORT4</entry> <entry>51010211</entry> <entry>IDES / DB-Export /
Disc4 of 6</entry>
</row>
<row>
<entry>EXPORT5</entry> <entry>51010212</entry> <entry>IDES / DB-Export /
Disc5 of 6</entry>
</row>
<row>
<entry>EXPORT6</entry> <entry>51010213</entry> <entry>IDES / DB-Export /
Disc6 of 6</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Additionally, I used the <application>Oracle 8
Server</application> (Pre-production version 8.0.5 for Linux,
Kernel Version 2.0.33) CD which is not really necessary, and
of course FreeBSD 4.3 stable (it was only a few days past 4.3
RELEASE).</para>
</sect2>
<sect2 id="sap-notes">
<title>SAP-Notes</title>
<para>The following notes should be read before installing
<application>SAP R/3</application> or proved to be useful
during installation:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Number</entry>
<entry>Title</entry>
</row>
</thead>
<tbody>
<row>
<entry>0171356</entry> <entry>SAP Software auf Linux: grundlegenden
Anmerkungen</entry>
</row>
<row>
<entry>0201147</entry> <entry>INST: 4.6C R/3 Inst. on UNIX -
Oracle</entry>
</row>
<row>
<entry>0373203</entry> <entry>Update / Migration Oracle 8.0.5 -->
8.0.6/8.1.6 LINUX</entry>
</row>
<row>
<entry>0072984</entry> <entry>Release of Digital UNIX 4.0B for
Oracle</entry>
</row>
<row>
<entry>0130581</entry> <entry>R3SETUP step DIPGNTAB terminates</entry>
</row>
<row>
<entry>0144978</entry> <entry>Your system has not been installed
correctly</entry>
</row>
<row>
<entry>0162266</entry> <entry>Questions and tips for R3SETUP on Windows
NT / W2K</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="hardware-requirements">
<title>Hardware-Requirements</title>
<para>The following equipment is sufficient for a
<application>SAP R/3 System</application> (4.6B):</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Component</entry>
<entry>4.6B</entry>
<entry>4.6C</entry>
</row>
</thead>
<tbody>
<row>
<entry>Processor</entry>
<entry>2 x 800MHz Pentium III</entry>
<entry>2 x 800MHz Pentium III</entry>
</row>
<row>
<entry>Memory</entry>
<entry>1GB ECC</entry>
<entry>2GB ECC</entry>
</row>
<row>
<entry>Hard Disc Space</entry>
<entry>50-60GB (IDES)</entry>
<entry>50-60GB (IDES)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>For use in production, Xeon-Processors with large cache,
high-speed disc access (SCSI, RAID hardware controller), USV
and ECC-RAM is recommended. The large amount of Hard disc
space is due to the preconfigured IDES System, which creates
27 GB of database files during installation. Usually after
installation it is then necessary to extend some
tablespaces.</para>
<para>I used a dual processor board with 2 800MHz Pentium III
processors, Adaptec 29160 Ultra160 SCSI adapter (for accessing
a 40/80 GB DLT tape drive and CD-ROM), Mylex AcelleRAID (2
channels, firmware 6.00-1-00 with 32MB RAM). To the Mylex
Raid-controller are attached two 17GB hard discs (mirrored)
and four 36GB hard discs (RAID level 5).</para>
</sect2>
<sect2 id="installation">
<title>Installation of FreeBSD 4.3 stable</title>
<para>First I installed FreeBSD 4.3 stable. I did the
default-installation via ftp.</para>
<sect3 id="install-via-ftp">
<title>Installation via FTP</title> <para>Get the diskimages
kern.flp and mfsroot.flp and put them on floppy disks (I got
mine from ftp7.de.freebsd.org. Please choose the appropriate
mirror).</para>
<screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput>
&prompt.root; <userinput>dd if=mfsroot.flp of=/dev/fd0</userinput> </screen>
<para>Don't forget to use different disks for the two images
:-), then boot from the floppy with the kern.flp-image on it
and follow instructions. I used the following disk
layout:</para>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Filesystem</entry>
<entry>Size (1k-blocks)</entry>
<entry>Size (GB)</entry>
<entry>Mounted on</entry>
</row>
</thead>
<tbody>
<row>
<entry>/dev/da0s1a</entry>
<entry>1.016.303</entry>
<entry>1</entry>
<entry>/</entry>
</row>
<row>
<entry>/dev/da0s1b</entry>
<entry> </entry>
<entry>6</entry>
<entry><swap></entry>
</row>
<row>
<entry>/dev/da0s1e</entry>
<entry>2.032.623</entry>
<entry>2</entry>
<entry>/var</entry>
</row>
<row>
<entry>/dev/da0s1f</entry>
<entry>8.205.339</entry>
<entry>8</entry>
<entry>/usr</entry>
</row>
<row>
<entry>/dev/da1s1e</entry>
<entry>45.734.361</entry>
<entry>45</entry>
<entry>/compat/linux/oracle</entry>
</row>
<row>
<entry>/dev/da1s1f</entry>
<entry>2.032.623</entry>
<entry>2</entry>
<entry>/compat/linux/sapmnt</entry>
</row>
<row>
<entry>/dev/da1s1g</entry>
<entry>2.032.623</entry>
<entry>2</entry>
<entry>/compat/linux/usr/sap</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>I had to configure and initialise the two logical drives
with the Mylex software beforehand. It is located on the
board itself and can be started during the boot phase of the
pc.</para>
<para> Please note that this disk layout differs slightly from
the SAP recommendations, as SAP suggests mounting the
oracle-subdirectories (and some others) separately - I
decided to just create them as real subdirectories for
simplicity.</para>
</sect3>
<sect3 id="getlatestsources">
<title>Get the latest stable-sources</title>
<para>For FreeBSD 4.3 stable onwards, it is quite easy to get
the latest stable sources. With the older versions of
FreeBSD, I had my own script located in /etc/cvsup. Setting
up cvsup for FreeBSD 4.3 is quite easy. As user
<username>root</username> do the following:</para>
<screen>&prompt.root; <userinput>cp /etc/defaults/make.conf /etc/make.conf</userinput>
&prompt.root; <userinput>vi /etc/make.conf</userinput> </screen>
<para>The file <filename>/etc/make.conf</filename> requires the
following entries to be active:</para>
<programlisting>SUP_UPDATE= yes
SUP= /usr/local/bin/cvsup
SUPFLAGS= -g -L 2
SUPHOST= cvsup8.FreeBSD.org
SUPFILE= /usr/share/examples/cvsup/stable-supfile
PORTSSUPFILE= /usr/share/examples/cvsup/ports-supfile
DOCSUPFILE= /usr/share/examples/cvsup/doc-supfile</programlisting>
<para>Change the <emphasis>SUPHOST</emphasis>-value
appropriately. The supfiles in
<filename>/usr/share/examples/cvsup</filename> should be
fine. If you don't want to load all the docfiles, leave the
corresponding <emphasis>DOCSUPFILE</emphasis>-entry
inactive. Starting cvsup to get the latest stable-sources
is then very easy:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make update</userinput> </screen>
</sect3>
<sect3 id="makeworldandnewkernel">
<title>Make world and a new kernel</title>
<para>The first thing to do is to install the sources.
As user root, do the following:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make world</userinput> </screen>
<para>If this goes through, one can then continue creating and
configuring the new kernel. Usually this is where to
customize the kernel configuration file. As the computer is
named troubadix, the natural name for the config file also
is troubadix:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
&prompt.root; <userinput>cp GENERIC TROUBADIX</userinput>
&prompt.root; <userinput>vi TROUBADIX</userinput> </screen>
<para>At this stage one can define the drivers to use and not
to use, etc. See the appropriate documentation or have a
look at file <filename>LINT</filename> for some additional
explanations.</para>
<para>One can then also include the parameters as described
below Creating the new kernel then requires:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
&prompt.root; <userinput>config TROUBADIX</userinput>
&prompt.root; <userinput>cd /usr/src/sys/compile/TROUBADIX</userinput>
&prompt.root; <userinput>make depend</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput> </screen>
<para>After <command>make install</command> finished
successfully, one should reboot the computer to have the new
kernel available.</para>
</sect3>
</sect2>
<sect2 id="installingthelinuxenviornment">
<title>Installing the Linux environment</title>
<para>I had some trouble downloading the required RPM-files (for
4.3 stable, 2nd May 2001), so you might try one of the
following locations (if all the others fail and the following
aren't out of date):</para>
<itemizedlist>
<listitem><para>ftp7.de.freebsd.org/pub/FreeBSD/distfiles/rpm</para></listitem>
<listitem><para>ftp.redhat.com/pub/redhat/linux/6.1/en/os/i386/RedHat/RPMS</para></listitem>
</itemizedlist>
<sect3 id="installinglinuxbase-system">
<title>Installing Linux base-system</title>
<para>First the linux base-system needs to be installed (as root):
<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
&prompt.root; <userinput>make package</userinput> </screen></para>
</sect3>
<sect3 id="installinglinuxdevelopment">
<title>Installing Linux development</title>
<para>Next, the linux development is needed:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/devel/linux_devtools</userinput>
&prompt.root; <userinput>make package</userinput> </screen>
</sect3>
<sect3 id="installingnecessaryrpms">
<title>Installing necessary RPMs</title>
+ <indexterm><primary>RPMs</primary></indexterm>
<para>To start the R3SETUP-Program, pam support is needed. As
this also requires some other packages, I ended up
installing several packages. After that, pam still
complained about a missing package, so I forced the
installation and it worked. I wonder if the other packages
are really needed or if it would have been sufficient to
install the pam-package.</para>
<para>Anyway, here is the list of packages I installed:</para>
<itemizedlist>
<listitem><para>cracklib-2.7-5.i386.rpm</para></listitem>
<listitem><para>cracklib-dicts-2.7-5.i386.rpm</para></listitem>
<listitem><para>pwdb-0.60-1.i386.rpm</para></listitem>
<listitem><para>pam-0.68-7.i386.rpm</para></listitem>
</itemizedlist>
<para>I installed these packages with the following
command:</para>
<screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <package_name></userinput> </screen>
<para>except for the pam package, which I forced with</para>
<screen>&prompt.root; <userinput>rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm pam-0.68-7.i386.rpm</userinput> </screen>
<para>For <application>Oracle</application> to run the
intelligent agent, I also had to install the following
RedHat TCL package (as is stated in the FreeBSD Handbook):
<filename>tcl-8.0.5-30.i386.rpm</filename> (otherwise the
relinking during <application>Oracle</application> install
won't work). There are some other issues regarding
relinking of <application>Oracle</application>, but that is
a Oracle-Linux issue, not FreeBSD specific as far as I
understand it.</para>
</sect3>
</sect2>
<sect2 id="creatingsapr3env">
<title>Creating the SAP/R3 environment</title>
<sect3 id="filesystemsandmountpoints">
<title>Creating the necessary filesystems and mountpoints</title>
<para>For a simple installation, it is sufficient to create the
following filesystems:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>mountpoint</entry>
<entry>size in GB</entry>
</row>
</thead>
<tbody>
<row>
<entry>/compat/linux/oracle</entry>
<entry>45 GB</entry>
</row>
<row>
<entry>/compat/linux/sapmnt</entry>
<entry>2 GB</entry>
</row>
<row>
<entry>/compat/linux/usr/sap</entry>
<entry>2 GB</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>I also created some links, so FreeBSD will also find the
correct path:</para>
<screen>&prompt.root; <userinput>ln -s /compat/linux/oracle /oracle</userinput>
&prompt.root; <userinput>ln -s /compat/linux/sapmnt /sapmnt</userinput>
&prompt.root; <userinput>ln -s /compat/linux/usr/sap /usr/sap</userinput> </screen>
</sect3>
<sect3 id="creatingusersanddirectories">
<title>Creating users and directories</title>
<para>SAP R/3 needs two users and three groups. The usernames
depend on the SAP system id (SID) which consists of three
letters. Some of these SIDs are reserved by SAP (for example
<emphasis>SAP</emphasis> and <emphasis>NIX</emphasis>. For
a complete list please see the SAP documentation). For the
IDES installation I used <emphasis>IDS</emphasis>. We have
therefore the following groups (group ids might differ,
these are just the values I used with my installation):</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>group id</entry>
<entry>group name</entry>
<entry>description</entry>
</row>
</thead>
<tbody>
<row>
<entry>100</entry>
<entry>dba</entry>
<entry>Data Base Administrator</entry>
</row>
<row>
<entry>101</entry>
<entry>sapsys</entry>
<entry>SAP System</entry>
</row>
<row>
<entry>102</entry>
<entry>oper</entry>
<entry>Data Base Operator</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>For a default Oracle-Installation, only group
<groupname>dba</groupname> is used. As
<groupname>oper</groupname>-group, one also uses group
<groupname>dba</groupname> (see Oracle- and
SAP-documentation for further information).</para>
<para>We also need the following users:</para>
<informaltable>
<tgroup cols="6">
<thead>
<row>
<entry>user id</entry>
<entry>username</entry>
<entry>generic name</entry>
<entry>group</entry>
<entry>additional groups</entry>
<entry>description</entry>
</row>
</thead>
<tbody>
<row>
<entry>1000</entry>
<entry>idsadm</entry>
<entry><sid>adm</entry>
<entry>sapsys</entry>
<entry>oper</entry>
<entry>SAP Administrator</entry>
</row>
<row>
<entry>1002</entry>
<entry>oraids</entry>
<entry>ora<sid></entry>
<entry>dba</entry>
<entry>oper</entry>
<entry>DB Administrator</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Adding the users with <command>adduser</command>
requires the following (please note shell and home
directory) entries for SAP-Administrator:</para>
<programlisting>Name: idsadm <sid>adm
Password: ******
Fullname: SAP IDES Administrator
Uid: 1000
Gid: 101 (sapsys)
Class:
Groups: sapsys dba
HOME: /home/idsadm /home/<sid>adm
Shell: /bin/sh</programlisting>
<para>and for Database-Administrator:</para>
<programlisting>Name: oraids ora<sid>
Password: ******
Fullname: Oracle IDES Administrator
Uid: 1002
Gid: 100 (dba)
Class:
Groups: dba
HOME: /oracle/IDS /oracle/<sid>
Shell: /bin/sh</programlisting>
<para>This should also include group
<groupname>oper</groupname> in case you are using both
groups <groupname>dba</groupname> and
<groupname>oper</groupname>.</para>
</sect3>
<sect3 id="creatingdirectories">
<title>Creating directories</title>
<para>These directories are usually created as separate
filesystems. This depends entirely on your requirements. I
choose to create them as simple directories, as they are all
located on the same RAID 5 anyway:</para>
<para>First we'll set owners and right of some directories (as
user <username>root</username>):</para>
<screen>&prompt.root; <userinput>chmod 775 /oracle</userinput>
&prompt.root; <userinput>chmod 777 /sapmnt</userinput>
&prompt.root; <userinput>chown root:dba /oracle</userinput>
&prompt.root; <userinput>chown idsadm:sapsys /compat/linux/usr/sap</userinput>
&prompt.root; <userinput>chmow 775 /compat/linux/usr/sap</userinput> </screen>
<para>Second we'll create directories as user ora<sid>. These
will all be subdirectories of /oracle/IDS:</para>
<screen>&prompt.root; <userinput>su - oraids</userinput>
&prompt.root; <userinput>mkdir mirrlogA mirrlogB origlogA origlogB</userinput>
&prompt.root; <userinput>mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6</userinput>
&prompt.root; <userinput>mkdir saparch sapreorg</userinput>
&prompt.root; <userinput>exit</userinput> </screen>
<para>In the third step we create directories as user idsadm
(<sid>adm):</para>
<screen>&prompt.root; <userinput>su - idsadm</userinput>
&prompt.root; <userinput>cd /usr/sap</userinput>
&prompt.root; <userinput>mkdir IDS</userinput>
&prompt.root; <userinput>mkdir trans</userinput>
&prompt.root; <userinput>exit</userinput> </screen>
</sect3>
<sect3 id="entriesinslashetcslashservices">
<title>Entries in /etc/services</title>
<para>SAP R/3 requires some entries in file
<filename>/etc/services</filename> , which will not be set
correctly during installation under FreeBSD. Please add the
following entries (you need at least those entries
corresponding to the instance number - in this case,
<emphasis>00</emphasis>. It'll do no harm adding all
entries from <emphasis>00</emphasis> to
<emphasis>99</emphasis> for <emphasis>dp</emphasis>,
<emphasis>gw</emphasis>, <emphasis>sp</emphasis> and
<emphasis>ms</emphasis>);</para>
<programlisting>sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number
sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number
sapsp00 3400/tcp # 3400 + Instance-Number
sapms00 3500/tcp # 3500 + Instance-Number
sapmsIDS 3600/tcp # SAP Message Server. 3600 + Instance-Number</programlisting>
</sect3>
<sect3 id="necessarylocales">
<title>Necessary locales</title>
+ <indexterm><primary>locale</primary></indexterm>
<para>SAP requires at least two locales that aren't part of
the default RedHat installation. SAP offers the required
RPMs as download from their ftp-server (which is only
accessible if you are a customer with OSS-access). See note
0171356 for a list of RPMs you need.</para>
<para>It is also possible to just create appropriate links
(for example from <emphasis>de_DE</emphasis> and
<emphasis>en_US</emphasis> ), but I wouldn't recommend this
for a production system (so far it worked with the IDES
system without any problems, though). The following locales
are needed:</para>
<programlisting>de_DE.ISO-8859-1
en_US.ISO-8859-1</programlisting>
<para>If they are not present, there will be some problems
during the installation. If these are then subsequently
ignored (eg by setting the status of the offending steps to
OK in file CENTRDB.R3S), it will be impossible to log onto
the SAP-system without some additional effort.</para>
</sect3>
<sect3 id="kerneltuning">
<title>Kernel Tuning</title>
+ <indexterm><primary>kernel tuning</primary></indexterm>
<para>SAP R/3 Systems need a lot of resources. I therefore
added the following parameters to my kernel config-file:
<programlisting># Set these for memory pigs (SAP and Oracle):
options MAXDSIZ="(1024*1024*1024)"
options DFLDSIZ="(1024*1024*1024)" # System V options needed.
options SYSVSHM #SYSV-style shared memory
options SHMMAXPGS=262144 #max amount of shared mem. pages
options SHMMNI=256 #max number of shared memory ident if.
options SHMSEG=100 #max shared mem.segs per process
options SYSVMSG #SYSV-style message queues
options MSGSEG=32767 #max num. of mes.segments in system
options MSGSSZ=32 #size of msg-seg. MUST be power of 2
options MSGMNB=65535 #max char. per message queue
options MSGTQL=2046 #max amount of msgs in system
options SYSVSEM #SYSV-style semaphores
options SEMMNU=256 #number of semaphore UNDO structures
options SEMMNS=1024 #number of semaphores in system
options SEMMNI=520 #number of semaphore indentifiers
options SEMUME=100 #number of UNDO keys</programlisting></para>
<para>The minimum values are specified in the documentation that
comes from SAP. As there is no description for Linux, see the
HP-UX-section (32-bit) for further information.
</para>
</sect3>
</sect2>
<sect2 id="installingsapr3">
<title>Installing SAP R/3</title>
<sect3 id="preparingsapcdroms">
<title>Preparing SAP CD-ROMs</title>
<para>There are lots of CD-ROMs to mount and unmount during
installation. Assuming you have enough CD-ROM-drives, you
can just mount them all. I decided to copy the CD-ROM
contents to corresponding directories:</para>
<programlisting>/oracle/IDS/sapreorg/<cd-name></programlisting>
<para>where <cd-name> was one of KERNEL, RDBMS, EXPORT1,
EXPORT2, EXPORT3, EXPORT4, EXPORT5 and EXPORT6. All the
filenames should be in capital letters, otherwise use the -g
option for mounting. So use the following commands:</para>
<screen>&prompt.root; <userinput>mount_cd9660 -g /dev/cd0a /mnt</userinput>
&prompt.root; <userinput>cp -R /mnt/* /oracle/IDS/sapreorg/<cd-name></userinput>
&prompt.root; <userinput>umount /mnt</userinput> </screen>
</sect3>
<sect3 id="runningtheinstall-script">
<title>Running the install-script</title>
<para>First we need to prepare an install-directory:</para>
<screen>&prompt.root; <userinput>cd /oracle/IDS/sapreorg</userinput>
&prompt.root; <userinput>mkdir install</userinput>
&prompt.root; <userinput>cd install</userinput> </screen>
<para>Then the install-script is started, which will copy nearly
all the relevant files into the install-directory:</para>
<para><filename>/oracle/IDS/sapreorg/KERNEL/UNIX/INSTTOOL.SH</filename></para>
<para>As this is an IDES-Installation with a fully customized
SAP R/3 Demo-System, we have six instead of just three
EXPORT-CDs. At this point the installation template
CENTRDB.R3S is for installing a standard central instance
(R/3 and Database), not an IDES central instance, so copy
the corresponding CENTRDB.R3S from the EXPORT1 directory,
otherwise R3SETUP will only ask for three EXPORT-CDs.</para>
</sect3>
<sect3 id="startr3setup">
<title>Start R3SETUP</title>
<para>Make sure LD_LIBRARY_PATH is set correctly:</para>
<screen>&prompt.root; <userinput>export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib</userinput> </screen>
<para>Start R3SETUP as user root from installation
directory:</para>
<screen>&prompt.root; <userinput>cd /oracle/IDS/sapreorg/install</userinput>
&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput> </screen>
<para>The script then asks some questions (defaults in brackets,
followed by actual input):</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Question</entry>
<entry>Default</entry>
<entry>Input</entry>
</row>
</thead>
<tbody>
<row>
<entry>Enter SAP System ID</entry>
<entry>[C11]</entry>
<entry>IDS<ret></entry>
</row>
<row>
<entry>Enter SAP Instance Number</entry>
<entry>[00]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter SAPMOUNT Directory</entry>
<entry>[/sapmnt]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter name of SAP central host</entry>
<entry>[troubadix.domain.de]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter name of SAP db host</entry>
<entry>[troubadix]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Select character set</entry>
<entry>[1] (WE8DEC)</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6</entry>
<entry> </entry>
<entry>1<ret></entry>
</row>
<row>
<entry>Extract Oracle Client archive</entry>
<entry>[1] (Yes, extract)</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter path to KERNEL CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/KERNEL</entry>
</row>
<row>
<entry>Enter path to RDBMS CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/RDBMS</entry>
</row>
<row>
<entry>Enter path to EXPORT1 CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/EXPORT1</entry>
</row>
<row>
<entry>Directory to copy EXPORT1 CD</entry>
<entry>[/oracle/IDS/sapreorg/CD4_DIR]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter path to EXPORT2 CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/EXPORT2</entry>
</row>
<row>
<entry>Directory to copy EXPORT2 CD</entry>
<entry>[/oracle/IDS/sapreorg/CD5_DIR]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter path to EXPORT3 CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/EXPORT3</entry>
</row>
<row>
<entry>Directory to copy EXPORT3 CD</entry>
<entry>[/oracle/IDS/sapreorg/CD6_DIR]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter path to EXPORT4 CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/EXPORT4</entry>
</row>
<row>
<entry>Directory to copy EXPORT4 CD</entry>
<entry>[/oracle/IDS/sapreorg/CD7_DIR]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter path to EXPORT5 CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/EXPORT5</entry>
</row>
<row>
<entry>Directory to copy EXPORT5 CD</entry>
<entry>[/oracle/IDS/sapreorg/CD8_DIR]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter path to EXPORT6 CD</entry>
<entry>[/sapcd]</entry>
<entry>/oracle/IDS/sapreorg/EXPORT6</entry>
</row>
<row>
<entry>Directory to copy EXPORT6 CD</entry>
<entry>[/oracle/IDS/sapreorg/CD9_DIR]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter amount of RAM for SAP + DB</entry>
<entry> </entry>
<entry>850<ret> (in Megabytes)</entry>
</row>
<row>
<entry>Service Entry Message Server</entry>
<entry>[3600]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter Group-ID of sapsys</entry>
<entry>[101]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter Group-ID of oper</entry>
<entry>[102]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter Group-ID of dba</entry>
<entry>[100]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter User-ID of <sid>adm</entry>
<entry>[1000]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Enter User-ID of ora<sid></entry>
<entry>[1002]</entry>
<entry><ret></entry>
</row>
<row>
<entry>Number of parallel procs</entry>
<entry>[2]</entry>
<entry><ret></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>If I had not copied the CDs to the different locations,
then the SAP-Installer can't find the CD needed (identified
by the <filename>LABEL.ASC</filename>-File on CD) and would
then ask you to insert / mount the CD and confirm or enter
the mountpath.</para>
<para>The <filename>CENTRDB.R3S</filename> might not be
error-free. In my case, it requested EXPORT4 again (but
indicated the correct key (6_LOCATI ON, then 7_LOCATION
etc.), so one can just continue with entering the correct
values. Don't get irritated.</para>
<para>Apart from some problems mentioned below, everything
should go straight throught up to the point where the Oracle
database software needs to be installed.</para>
</sect3>
</sect2>
<sect2 id="installingoracle805">
<title>Installing Oracle 8.0.5</title>
<para>Please see the corresponding SAP-Notes and Oracle Readmes
regarding Linux and Oracle DB for possible problems. Most if
not all problems stem from incompatible libraries</para>
<para>For more information on installing Oracle, refer to <ulink
url="linuxemu-oracle.html">the Installing Oracle
chapter.</ulink></para>
<sect3 id="installingtheoracle805withorainst">
<title>Installing the Oracle 8.0.5 with orainst</title>
<para>If <application>Oracle 8.0.5</application> is to be
used, some additional libraries are needed for successfully
relinking, as Oracle 8.0.5 was linked with an old glibc
(RedHat 6.0), but RedHat 6.1 already uses a new glibc. So
you have to install the following additional packages to
ensure that linking will work:</para>
<para><filename>compat-libs-5.2-2.i386.rpm</filename></para>
<para><filename>compat-glibc-5.2-2.0.7.2.i386.rpm</filename></para>
<para><filename>compat-egcs-5.2-1.0.3a.1.i386.rpm</filename></para>
<para><filename>compat-egcs-c++-5.2-1.0.3a.1.i386.rpm</filename></para>
<para><filename>compat-binutils-5.2-2.9.1.0.23.1.i386.rpm</filename></para>
<para>See the corresponding SAP-Notes or Oracle Readmes for
further information. If this is no option (at the time of
installation I didn't have enough time to check this), one
could use the original binaries, or use the relinked
binaries from an original RedHat System.</para>
<para>For compiling the intelligent agent, the RedHat TCL
package must be installed. If you can't get
<filename>tcl-8.0.3-20.i386.rpm</filename>, a newer one like
<filename>tcl-8.0.5-30.i386.rpm</filename> for RedHat 6.1
should also do.</para>
<para>Apart from relinking, the installation is
straightforward:</para>
<screen>&prompt.root; <userinput>su - oraids</userinput>
&prompt.root; <userinput>export TERM=xterm</userinput>
&prompt.root; <userinput>export ORACLE_TERM=xterm</userinput>
&prompt.root; <userinput>export ORACLE_HOME=/oracle/IDS</userinput>
&prompt.root; <userinput>cd /ORACLE_HOME/orainst_sap</userinput>
&prompt.root; <userinput>./orainst</userinput> </screen>
<para>Confirm all Screens with Enter until the software is
installed, except that one has to deselect the
<emphasis>Oracle On-Line Text Viewer</emphasis> , as this is
not currently available for Linux. Oracle then wants to
relink with <command>i386-glibc20-linux-gcc</command>
instead of the available <command>gcc</command>,
<command>egcs</command> or <command>i386-redhat-linux-gcc
</command>.</para>
<para>Due to time constrains I decided to use the binaries
from an Oracle 8.0.5 PreProduction release, after the first
attempt at getting the version from the RDBMS-CD working,
failed, and finding / accessing the correct RPMs was a
nightmare at that time.</para>
</sect3>
<sect3 id="installingtheoracle805preproduction">
<title>Installing the Oracle 8.0.5 Pre-Production release for
Linux (Kernel 2.0.33)</title>
<para>This installation is quite easy. Mount the CD, start the
installer. It will then ask for the location of the Oracle
home directory, and copy all binaries there. I did not
delete the remains of my previous RDBMS-installation tries,
though.</para>
<para>Afterwards, Oracle Database could be started with no
problems.</para>
</sect3>
</sect2>
<sect2 id="continuewithsapr4installation">
<title>Continue with SAP R/3 installation</title>
<para>First check the environment settings of users idsamd
(<sid>adm) and oraids (ora<sid>). They should now
both have the files <filename>.profile</filename> ,
<filename>.login</filename> and <filename>.cshrc</filename>
which are all using <command>hostname</command>. In case the
system's hostname is the fully qualified name, you need to
change <command>hostname</command> to <command>hostname
-s</command> within all three files.</para>
<sect3 id="databaseload">
<title>Database load</title>
<para>Afterwards, R3SETUP can either be restarted or continued
(depending on whether exit was chosen or not). R3SETUP then
creates the tablespaces and loads the data from EXPORT1 to
EXPORT6 (remember, it is an IDES system, otherwise it would
only be EXPORT1 to EXPORT3) with R3load into the
database.</para>
<para>When the database load is finished (might take a few
hours), some passwords are requested. For test
installations, one can use the well known default passwords
(use different ones if security is an issue!):</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Question</entry>
<entry>Input</entry>
</row>
</thead>
<tbody>
<row>
<entry>Enter Password for sapr3</entry>
<entry>sap<ret></entry>
</row>
<row>
<entry>Confirum Password for sapr3</entry>
<entry>sap<ret></entry>
</row>
<row>
<entry>Enter Password for sys</entry>
<entry>change_on_install<ret></entry>
</row>
<row>
<entry>Confirm Password for sys</entry>
<entry>change_on_install<ret></entry>
</row>
<row>
<entry>Enter Password for system</entry>
<entry>manager<ret></entry>
</row>
<row>
<entry>Confirm Password for system</entry>
<entry>manager<ret></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>At this point I had a few problems with dipgntab.</para>
</sect3>
<sect3 id="listener">
<title>Listener</title>
<para>Start the Oracle-Listener as user oraids (ora<sid>) as
follows:</para>
<programlisting>umask 0; lsnrctl start</programlisting>
<para>Otherwise you might get ORA-12546 as the sockets won't
have the correct permissions. See SAP note 072984.</para>
</sect3>
</sect2>
<sect2 id="postinstallationsteps">
<title>Post-installation steps</title>
<sect3 id="requestsapr3licensekey">
<title>Request SAP R/3 license key</title>
<para>This is needed, as the temporary license is only valid for
four weeks. Don't forget to enter the correct Operating System:
(X) Other: <emphasis>FreeBSD 4.3 Stable</emphasis>. First get
the hardware key. Log on as user <username>idsadm</username> and
call <command>saplicense</command>:</para>
<screen>&prompt.root; <userinput>/sapmnt/IDS/exe/saplicense -get</userinput></screen>
<para>Calling <command>saplicense</command> without options
gives a list of options. Upon receiving the license key, it can
be installed using</para>
<screen>&prompt.root; <userinput>/sapmnt/IDS/exe/saplicense -install</userinput></screen>
<para>You are then required to enter the following
values:</para>
<programlisting>SAP SYSTEM ID = <SID, 3 chars>
CUSTOMER KEY = <hardware key, 11 chars>
INSTALLATION NO = <installation, 10 digits>
EXPIRATION DATE = <yyyymmdd, usually "99991231">
LICENSE KEY = <license key, 24 chars></programlisting>
</sect3>
<sect3 id="creatingusers">
<title>Creating Users</title>
<para>Create a user within client 000 (for some tasks required
to be done within client 000, but with a user different from
users <username>sap*</username> and
<username>ddic</username>). As a username, I usually choose
<replaceable>wartung</replaceable> (or
<replaceable>service</replaceable> in English). Profiles
required are <emphasis>sap_new</emphasis> and
<emphasis>sap_all</emphasis>. For additional safety the
passwords of default users within all clients should be
changed (this includes users <username>sap*</username> and
<username>ddic</username>).</para>
</sect3>
<sect3 id="configtranssysprofileopermodesetc">
<title>Configure Transport System, Profile, Operation Modes, etc.</title>
<para>Within client 000, user different from ddic and sap*, do
at least the following:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Task</entry>
<entry>Transaction</entry>
</row>
</thead>
<tbody>
<row>
<entry>Configure Transport System, eg as <emphasis>Stand-Alone
Transport Domain Entity</emphasis></entry>
<entry>STMS</entry>
</row>
<row>
<entry>Create / Edit Profile for System</entry>
<entry>RZ10</entry>
</row>
<row>
<entry>Maintain Operation Modes and Instances</entry>
<entry>RZ04</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>These and all the other post-installation steps are
thoroughly described in SAP installation guides.</para>
</sect3>
<sect3 id="editintsidsap">
<title>Edit init<sid>.sap (initIDS.sap)</title>
<para>The file
<filename>/oracle/IDS/dbs/initIDS.sap</filename> contains
the SAP backup profile. Here the size of the tape to be
used, type of compression and so on need to be defined. To
get this running with <command>sapdba</command> /
<command>brbackup</command>, I changed the following
values:</para>
<programlisting>compress = hardware
archive_function = copy_delete_save
cpio_flags = "-ov --format=newc --block-size=128 --quiet"
cpio_in_flags = "-iuv --block-size=128 --quiet"
tape_size = 38000M
tape_address = /dev/nsa0
tape_address_rew = /dev/sa0</programlisting>
<para>Explanations:</para>
<para><emphasis>compress</emphasis> The tape I use is a HP DLT1
which does hardware compression.</para>
<para><emphasis>archive_function</emphasis> This defines the
default behaviour for saving Oracle archive logs: New logfiles
are saved to tape, already saved logfiles are saved again and
are then deleted. This prevents lots of trouble if one needs to
recover the database, and one of the archive-tapes has gone
bad.</para>
<para><emphasis>cpio_flags</emphasis> Default is to use -B which
sets blocksize to 5120 Bytes. For DLT-Tapes, HP recommends at
least 32K blocksize, so I used --block-size=128 for
64K. --format=newc is needed I have inode numbers greater than
65535. The last option --quiet is needed as otherwise brbackup
complains as soon as cpio outputs the numbers of blocks
saved.</para>
<para><emphasis>cpio_in_flags</emphasis> Flags needed for
loading data back from tape. Format is reckognized
automagically.</para>
<para><emphasis>tape_size</emphasis> This usually gives the raw
storage capability of the tape. For security reason (we use
hardware compression), the</para>
<para><emphasis>value</emphasis> is slightly lower than the
actual value.</para>
<para><emphasis>tape_address</emphasis> The non-rewindable
device to be used with cpio.</para>
<para><emphasis>tape_address_rew The rewindable device to be
used with cpio.</emphasis></para>
</sect3>
</sect2>
<sect2 id="problemsduringinstallation">
<title>Problems during installation</title>
<sect3 id="indoraduringduringr3setup">
<title>OSUSERSIDADM_IND_ORA during R3SETUP</title>
<para>If R3SETUP complains at this stage, edit file
CENTRDB.R3S. Locate [OSUSERSIDADM_IND_ORA] and edit the
following values:</para>
<programlisting>HOME=/home/idsadm (was empty)
STATUS=OK (had status ERROR)
</programlisting>
<para>Then you can restart R3SETUP with:</para>
<screen>&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
</sect3>
<sect3 id="indoraduringr3setup">
<title>OSUSERDBSID_IND_ORA during R3SETUP</title>
<para>Possibly R3SETUP also complains at this stage. Just edit
CENTRDB.R3S. Locate [OSUSERDBSID_IND_ORA] and edit the
following value in that section:</para>
<programlisting>STATUS=OK</programlisting>
<para>Then just restart R3SETUP again:</para>
<screen>&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
</sect3>
<sect3 id="oraviewvrffilenotfound">
<title>oraview.vrf FILE NOT FOUND during Oracle installation</title>
<para>You haven't deselected <emphasis>Oracle On-Line Text Viewer</emphasis>
before starting the installation. This is marked for installation even
though this option is currently not available for Linux. Deselect this
product inside the Oracle installation menu and restart installation.</para>
</sect3>
<sect3 id="textenvincalid">
<title>TEXTENV_INVALID during R3SETUP, RFC or SAPGUI start</title>
<para>If this error is encountered, the correct locale is
missing. SAP note 0171356 lists the necessary RPMs that
need be installed (eg <emphasis>saplocales-1.0-3</emphasis>,
<emphasis>saposcheck-1.0-1</emphasis> for RedHat 6.1). In
case you ignored all the related errors and set the
corresponding status from ERROR to OK (in CENTRDB.R3S) every
time R3SETUP complained and just restarted R3SETUP, the
SAP-System will not be properly configured and you will then
not be able to connect to the system with a sapgui, even
though the system can be started. Trying to connect with the
old Linux sapgui gave the following messages:</para>
<programlisting>Sat May 5 14:23:14 2001
*** ERROR => no valid userarea given [trgmsgo. 0401]
Sat May 5 14:23:22 2001
*** ERROR => ERROR NR 24 occured [trgmsgi. 0410]
*** ERROR => Error when generating text environment. [trgmsgi. 0435]
*** ERROR => function failed [trgmsgi. 0447]
*** ERROR => no socket operation allowed [trxio.c 3363]
Speicherzugriffsfehler</programlisting>
<para>This behaviour is due to SAP R/3 being unable to
correctly assign a locale and also not being properly
configured itself (missing entries in some database
tables). To be able to connect to SAP, add the following
entries to file DEFAULT.PFL (see note 0043288):</para>
<programlisting>abap/set_etct_env_at_new_mode =0
install/collate/active =0
rscp/TCP0B =TCP0B
</programlisting>
<para>Restart the SAP system. Now one can connect to the
system, even though country-specific language settings might
not work as expected. After correcting country-settings
(and providing the correct locales), these entries can be
removed from DEFAULT.PFL and the SAP system can be
restarted.</para>
</sect3>
<sect3 id="ora-12546">
<title>ORA-12546. Start Listener with correct permissions</title>
<para>Start the Oracle Listener as user
<username>oraids</username> with the following commands:</para>
<screen>&prompt.root; <userinput>umask 0; lsnrctl start</userinput></screen>
<para>Otherwise one might get ORA-12546 as the sockets won't
have the correct permissions. See SAP note 0072984.</para>
</sect3>
<sect3 id="dipgntabindind">
<title>[DIPGNTAB_IND_IND] during R3SETUP</title>
<para>In general, see SAP note 0130581 (R3SETUP step DIPGNTAB
terminates). During this specific installation, for some
reasons the installation process was not using the proper
SAP system name "IDS", but the empty string "" instead. This
lead to some minor problems with accessing directories, as
the paths are generated dynamically using <sid> (in
this case IDS). So instead of accessing:</para>
<programlisting>/usr/sap/IDS/SYS/...
/usr/sap/IDS/DVMGS00</programlisting>
<para>the following path were used:</para>
<programlisting>/usr/sap//SYS/...
/usr/sap/D00i</programlisting>
<para>To continue with the installation, I created a link and an
additional directory:</para>
<screen>&prompt.root; pwd
/compat/linux/usr/sap
&prompt.root; ls -l
total 4
drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00
drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS
lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS
drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp
drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans </screen>
<para>I also found SAP notes (0029227 and 0008401) describing
this behaviour.</para>
</sect3>
<sect3 id="rfcrswboiniindind">
<title>[RFCRSWBOINI_IND_IND] during R3SETUP</title>
<para>Set STATUS of the offending step from ERROR to OK (file
<filename>CENTRDB.R3S</filename>) and restart R3SETUP. After
installation, you have to execute the report RSWBOINS from
transaction SE38. See SAP note 0162266 for additional
information about phase RFCRSWBOINI and RFCRADDBDIF.</para>
</sect3>
<sect3 id="rfcraddbdifindind">
<title>[RFCRADDBDIF_IND_IND] during R3SETUP</title>
<para>Set STATUS of the offending step from ERROR to OK (file
<filename>CENTRDB.R3S</filename>) and restart R3SETUP. After
installation, you have to execute the report RADDBDIF from
transaction SE38. See SAP note 0162266 for further
information.</para>
</sect3>
</sect2>
</sect1>
<sect1>
<title>Advanced Topics</title>
<para>If you are curious as to how the Linux binary compatibility
works, this is the section you want to read. Most of what follows
is based heavily on an email written to &a.chat; by Terry Lambert
<email>tlambert@primenet.com</email> (Message ID:
<literal><199906020108.SAA07001@usr09.primenet.com></literal>).</para>
<sect2>
<title>How Does It Work?</title>
+ <indexterm><primary>execution class loader</primary></indexterm>
<para>FreeBSD has an abstraction called an <quote>execution class
loader</quote>. This is a wedge into the &man.execve.2; system
call.</para>
<para>What happens is that FreeBSD has a list of loaders, instead of
a single loader with a fallback to the <literal>#!</literal>
loader for running any shell interpreters or shell scripts.</para>
<para>Historically, the only loader on the UNIX platform 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.</para>
<para>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.</para>
<para>The assumption was a default of <quote>whatever the current
shell is</quote>.</para>
<para>Later, a hack was made for &man.sh.1; to examine the first two
characters, and if they were <literal>:\n</literal>, then it
invoked the &man.csh.1; shell instead (we believe SCO first made
this hack).</para>
<para>What FreeBSD does now is go through a list of loaders, with a
generic <literal>#!</literal> loader that knows about interpreters
as the characters which follow to the next whitespace next to
last, followed by a fallback to
<filename>/bin/sh</filename>.</para>
+ <indexterm><primary>ELF</primary></indexterm>
<para>For the Linux ABI support, FreeBSD sees the magic number as an
ELF binary (it makes no distinction between FreeBSD, Solaris,
Linux, or any other OS which has an ELF image type, at this
point).</para>
+ <indexterm><primary>Solaris</primary></indexterm>
<para>The ELF loader looks for a specialized
<emphasis>brand</emphasis>, which is a comment section in the ELF
image, and which is not present on SVR4/Solaris ELF
binaries.</para>
<para>For Linux binaries to function, they must be
<emphasis>branded</emphasis> as type <literal>Linux</literal>;
from &man.brandelf.1;:</para>
<screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
<para>When this is done, the ELF loader will see the
<literal>Linux</literal> brand on the file.</para>
+ <indexterm>
+ <primary>ELF</primary>
+ <secondary>branding</secondary>
+ </indexterm>
<para>When the ELF loader sees the <literal>Linux</literal> brand,
the loader replaces a pointer in the <literal>proc</literal>
structure. All system calls are indexed through this pointer (in
a traditional UNIX system, this would be the
<literal>sysent[]</literal> structure array, containing the system
calls). In addition, the process flagged for special handling of
the trap vector for the signal trampoline code, and sever other
(minor) fix-ups that are handled by the Linux kernel
module.</para>
<para>The Linux system call vector contains, among other things, a
list of <literal>sysent[]</literal> entries whose addresses reside
in the kernel module.</para>
<para>When a system call is called by the Linux binary, the trap
code dereferences the system call function pointer off the
<literal>proc</literal> structure, and gets the Linux, not the
FreeBSD, system call entry points.</para>
<para>In addition, the Linux mode dynamically
<emphasis>reroots</emphasis> lookups; this is, in effect, what the
<literal>union</literal> option to FS mounts
(<emphasis>not</emphasis> the unionfs!) does. First, an attempt
is made to lookup the file in the
<filename>/compat/linux/<replaceable>original-path</replaceable></filename>
directory, <emphasis>then</emphasis> only if that fails, the
lookup is done in the
<filename>/<replaceable>original-path</replaceable></filename>
directory. This makes sure that binaries that require other
binaries can run (e.g., the Linux toolchain can all run under
Linux ABI support). It also means that the Linux binaries can
load and exec FreeBSD binaries, if there are no corresponding
Linux binaries present, and that you could place a &man.uname.1;
command in the <filename>/compat/linux</filename> directory tree
to ensure that the Linux binaries could not tell they were not
running on Linux.</para>
<para>In effect, there is a Linux kernel in the FreeBSD kernel; the
various underlying functions that implement all of the services
provided by the kernel are identical to both the FreeBSD system
call table entries, and the Linux system call table entries: file
system operations, virtual memory operations, signal delivery,
System V IPC, etc… The only difference is that FreeBSD
binaries get the FreeBSD <emphasis>glue</emphasis> functions, and
Linux binaries get the Linux <emphasis>glue</emphasis> functions
(most older OS's only had their own <emphasis>glue</emphasis>
functions: addresses of functions in a static global
<literal>sysent[]</literal> structure array, instead of addresses
of functions dereferenced off a dynamically initialized pointer in
the <literal>proc</literal> structure of the process making the
call).</para>
<para>Which one is the native FreeBSD ABI? It does not matter.
Basically the only difference is that (currently; this could
easily be changed in a future release, and probably will be after
this) the FreeBSD <emphasis>glue</emphasis> 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.</para>
<para>Yeah, but is this really emulation? No. It is an ABI
implementation, not an emulation. There is no emulator (or
simulator, to cut off the next question) involved.</para>
<para>So why is it sometimes called <quote>Linux emulation</quote>?
To make it hard to sell FreeBSD! <!-- smiley -->8-). Really, it
is because the historical implementation was done at a time when
there was really no word other than that to describe what was
going on; saying that FreeBSD ran Linux binaries was not true, if
you did not compile the code in or load a module, and there needed
to be a word to describe what was being loaded—hence
<quote>the Linux emulator</quote>.</para>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->