<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="linuxemu">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured and parts updated by </contrib>
      </author>
      <!-- 22 Mar 2000 -->
    </authorgroup>
    <authorgroup>
      <author>
	<firstname>Brian N.</firstname>
	<surname>Handy</surname>
	<contrib>Originally contributed by </contrib>
      </author>
      <author>
	<firstname>Rich</firstname>
	<surname>Murphey</surname>
      </author>
    </authorgroup>
  </chapterinfo>

  <title>Linux Binary Compatibility</title>

  <sect1>
    <title>Synopsis</title>
    <indexterm><primary>Linux binary compatibility</primary></indexterm>
    <indexterm>
      <primary>binary compatibility</primary>
      <secondary>Linux</secondary>
    </indexterm>

    <para>FreeBSD provides binary compatibility with several other
      Unix-like operating systems, including Linux.  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 <application>Star Office</application>, 
      the Linux version of <application>Netscape</application>, 
      <application>Adobe Acrobat</application>, 
      <application>RealPlayer</application>
      5 and 7, <application>VMWare</application>, 
      <application>Oracle</application>,
      <application>WordPerfect</application>, <application>Doom</application>, 
      <application>Quake</application>, 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>After reading this chapter, you will know:</para>
    <itemizedlist>
      <listitem><para>How to enable Linux binary compatibility on your
        system.</para></listitem>
      <listitem><para>How to install additional Linux shared
        libraries.</para></listitem>
      <listitem><para>How to install Linux applications on your
        FreeBSD system.</para></listitem>
      <listitem><para>The implementation details of Linux
        compatibility in FreeBSD.</para></listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem><para>Know how to install additional third-party
        software (<xref linkend="ports">).</para></listitem>
    </itemizedlist>

  </sect1>

  <sect1 id="linuxemu-lbc-install">
    <title>Installation</title>

    <indexterm><primary>KLD (kernel loadable object)</primary></indexterm>

    <para>Linux binary compatibility is not turned on by default.  The
      easiest way to enable this functionality is to load the
      <literal>linux</literal> KLD object (<quote>Kernel LoaDable
      object</quote>).  You can load this module by simply typing
      <command>linux</command> at the command prompt.</para>

    <para>If you would like Linux compatibility to always be enabled,
      then you should add the following line to
      <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 &gt; /dev/null 2&gt;&amp;1
	;;
esac</programlisting>

    <para>The &man.kldstat.8; command can be used to verify that the
      KLD is loaded:</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 Linux binary compatibility into the kernel
      by adding <literal>options LINUX</literal> to your kernel
      configuration file.  Then install your new kernel as described in
      <xref linkend="kernelconfig">.</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>

      <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="file://localhost/usr/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 <username>root</username> 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) =&gt; /usr/X11/lib/libXt.so.3.1.0
libX11.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libX11.so.3.1.0
libc.so.4 (DLL Jump 4.5pl26) =&gt; /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 -&gt; libXt.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3 -&gt; libX11.so.3.1.0
/compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -&gt; 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 -&gt; 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) -&gt; 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 -&gt; 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 Hostname 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">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Murray</firstname>
	  <surname>Stokely</surname>
	  <contrib>Updated for Mathematica 4.X by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Bojan</firstname>
	  <surname>Bistrovic</surname>
	  <contrib>Merged with work by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Installing Mathematica</title>

    <indexterm>
      <primary>applications</primary>
      <secondary><application>Mathematica</application></secondary>
    </indexterm>

    <para>This document describes the process of installing the Linux
      version of <application>Mathematica 4.X</application> onto
      a FreeBSD system.</para>

    <para>The Linux version of <application>Mathematica</application>
      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 <application>Mathematica</application>
      or <application>Mathematica for Students</application> 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 <application>Mathematica</application> 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 <application>Mathematica</application>
	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 <application>Mathematica</application>
	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 <application>Mathematica</application> for the first time
	exactly as you would for any other 
	<application>Mathematica</application> platform.</para>
    </sect2>

    <sect2>
      <title>Running the Mathematica Frontend over a Network</title>

      <para><application>Mathematica</application> 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 
	<application>Mathematica</application>
	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-maple">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Aaron</firstname>
	  <surname>Kaplan</surname>
<!--	  <address><email>aaron@lo-res.org</email></address>-->
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Robert</firstname>
	  <surname>Getschmann</surname>
<!--	  <address><email>rob@getschmann.org</email></address>-->
	  <contrib>Thanks to </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Installing Maple</title>

    <indexterm>
      <primary>applications</primary>
      <secondary><application>Maple</application></secondary>
    </indexterm>

    <para>Maple is a commercial mathematics program similar to
      Mathematica.  You must purchase this software from <ulink
      url="http://www.maplesoft.com/"></ulink> and then register there
      for a license file.  To install this software on FreeBSD, please
      follow these simple steps.</para>

      <procedure>
	<step><para>Execute the <filename>INSTALL</filename> shell
	  script from the product distribution.  Choose the
	  <quote>RedHat</quote> option when prompted by the
	  installation program.  A typical installation directory
	  might be <filename
	  class="directory">/usr/local/maple</filename></para></step>

        <step><para>If you have not done so, order a license for Maple
	  from Maple Waterloo Software (http://register.maplesoft.com)
	  and copy it to
	  <filename>/usr/local/maple/license/license.dat</filename></step>

        <step><para>Install the <application>FLEXlm</application>
	  license manager by running the
	  <filename>INSTALL_LIC</filename> install shell script that
	  comes with <application>Maple</application>.  Specify the
	  primary hostname for your machine for the license
	  server.</para>

        <step><para>Patch the
          <filename>usr/local/maple/bin/maple.system.type</filename>
          file with the following:</para>
<programlisting>   ----- 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 -----</programlisting>

	<para>Please note that after the "FreeBSD"|\ no other
	  whitespace should be present.</para>

	<para>This patch instructs <application>Maple</application> to
	  recognize <quote>FreeBSD</quote> as a type of Linux system.
	  The <filename>bin/maple</filename> shell script calls the
	  <filename>bin/maple.system.type</filename> 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.</para></step>

      <step><para>Start the license server.</para>

	<para>The following script, installed as
	  <filename>/usr/local/etc/rc.d/lmgrd.sh</filename> is a
	  convenient way to start up lmgrd:</para>

	<programlisting>   ----- snip ------------

#! /bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/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 ------------</programlisting></step>


      <step><para>Test-start maple:</para>
	<screen>&prompt.user; cd /usr/local/maple/bin
&prompt.user; ./xmaple</screen>

	<para>You should be up and running. Make sure to write
	  Maplesoft to let them know you would like a native FreeBSD
	  version!</para></step>
    </procedure>

    <sect2>
      <title>Common Pitfalls</title>

      <itemizedlist>
	<listitem><para>The FLEXlm license manager can be a difficult
	  tool to work with.  Additional documentation on the subject
	  can be found at <ulink
	  url="http://www.globetrotter.com/"></ulink>.</para></listitem>

	<listitem><para><command>lmgrd</command> is known to be very picky
	  about the license file and to core dump if there are any
	  problems.  A correct license file should look like this:</para>

<programlisting># =======================================================
# 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</programlisting>
 
	  <note><para>Serial number and key 'X''ed out. "chillig" is a
	    hostname.</para></note>

  	  <para>Editing the license file works as long as you do not
 	    touch the "FEATURE" line (which is protected by the
 	    license key).</para></listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="linuxemu-oracle">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Marcel</firstname>
	  <surname>Moolenaar</surname>
	  <contrib>Contributed by </contrib>
	</author>
	<!-- marcel@cup.hp.com -->
      </authorgroup>
    </sect1info>
    <title>Installing Oracle</title>

    <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 will
	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.  Do not 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
PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
PATH=$PATH:/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>Do not 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
	  <command>chown</command> 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 do not 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 <command>genclntsh</command> 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
	<application>Oracle</application> as if it was run on Linux 
	itself.</para>
    </sect2>
  </sect1>
  
  <sect1 id="sapr3">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Holger</firstname>
	  <surname>Kipp</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <!-- holger.kipp@alogis.com -->
      <authorgroup>
	<author>
	  <firstname>Valentino</firstname>
	  <surname>Vaschetto</surname>
	  <contrib>Original version converted to SGML by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Installing SAP R/3</title>

    <indexterm>
      <primary>applications</primary>
      <secondary><application>SAP R/3</application></secondary>
    </indexterm>

    <para>Installations of SAP Systems using FreeBSD will not be
      supported by the SAP support team &mdash; they only offer support
      for certified platforms.</para>

    <sect2 id="preface">
      <title>Preface</title>

      <para>This document describes a possible way of installing a 
	<application>SAP R/3-System</application>
	with <application>Oracle Database</application>
	for Linux onto a FreeBSD machine, including the installation
	of FreeBSD and <application>Oracle</application>. Two different
	configurations will be described:</para>

      <itemizedlist>
	<listitem>
	  <para><application>SAP R/3 4.6B (IDES)</application> with
	  <application>Oracle 8.0.5</application> on FreeBSD 4.3-STABLE</para>
	</listitem>

	<listitem>
	  <para><application>SAP R/3 4.6C</application> with
	  <application>Oracle 8.1.7</application> on FreeBSD 4.5-STABLE</para>
	</listitem>
      </itemizedlist>

      <para>Even though this document tries to describe all important
        steps in a greater detail, it is not intended as a replacement
        for the <application>Oracle</application> and 
	<application>SAP R/3</application> installation guides.</para>

      <para>Please see the documentation that comes with the 
	<application>SAP R/3</application>
        Linux edition for <application>SAP-</application> and 
	<application>Oracle</application>-specific questions, as well
        as resources from <application>Oracle</application> and 
	<application>SAP OSS</application>.</para>
    </sect2>

    <sect2 id="software">
      <title>Software</title>

      <para>The following CD-ROMs have been used for SAP-installations:</para>

      <sect3 id="software-46b">
	<title>SAP R/3 4.6B, Oracle 8.0.5</title>

      <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 /
            Disc 3 of 6</entry>
        </row>
        <row>
          <entry>EXPORT4</entry> <entry>51010211</entry> <entry>IDES / DB-Export /
            Disc 4 of 6</entry>
        </row>
        <row>
          <entry>EXPORT5</entry> <entry>51010212</entry> <entry>IDES / DB-Export /
            Disc 5 of 6</entry>
        </row>
        <row>
          <entry>EXPORT6</entry> <entry>51010213</entry> <entry>IDES / DB-Export /
             Disc 6 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>

      </sect3>
      <sect3 id="software-46c">
        <title>SAP R/3 4.6C SR2, Oracle 8.1.7</title>

        <informaltable>
          <tgroup cols=3>
          <thead>
          <row>
            <entry>Name</entry> <entry>Number</entry> <entry>Description</entry>
          </row>
          </thead>
          <tbody>
          <row>
            <entry>KERNEL</entry> <entry>51014004</entry> <entry>SAP Kernel Oracle /
            SAP Kernel Version 4.6D / DEC, Linux</entry>
          </row>
          <row>
            <entry>RDBMS</entry> <entry>51012930</entry> <entry>Oracle 8.1.7/ RDBMS /
            Linux</entry>
          </row>
          <row>
            <entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export 
	    / Disc 1 of 4</entry>
          </row>
          <row>
            <entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export 
	    / Disc 2 of 4</entry>
          </row>
          <row>
            <entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export 
	    / Disc 3 of 4</entry>
          </row>
          <row>
            <entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export 
	    / Disc 4 of 4</entry>
          </row>
          <row>
            <entry>LANG1</entry> <entry>51013954</entry> <entry>Release 4.6C SR2 /
	    Language / DE, EN, FR / Disc 1 of 3</entry>
          </row>
          </tbody>
          </tgroup>
        </informaltable>

        <para>Depending on the languages you would like to install, additional
	  language CDs might be necessary. Here we're just using DE and EN, so
	  the first Language-CD is the only one needed. As a little note, the
	  numbers for all four export CDs are identical. All three language CDs
	  also have the same number (this is different from the 4.6B IDES
	  release CD numbering). At the time of writing this installation is
	  running on FreeBSD 4.5-STABLE (20.03.2002).</para>
      </sect3>
    </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>

      <sect3 id="sap-notes-46b">
	<title>SAP R/3 4.6B, Oracle 8.0.5</title>

      <informaltable>
        <tgroup cols="2">
        <thead>
        <row>
          <entry>Number</entry>
          <entry>Title</entry>
        </row>
        </thead>
        <tbody>
        <row>
            <entry>0171356</entry> <entry>SAP Software on Linux: Essential
            Comments</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>
      </sect3>

      <sect3 id="sap-notes-46c">
	<title>SAP R/3 4.6C, Oracle 8.1.7</title>

	<informaltable>
	  <tgroup cols="2">
	  <thead>
	  <row>
	    <entry>Number</entry>
	    <entry>Title</entry>
	  </row>
	  </thead>
	  <tbody>
	  <row>
	    <entry>0015023</entry> <entry>Initializing table TCPDB (RSXP0004)
	    (EBCDIC)</entry>
	  </row>
	  <row>
	    <entry>0045619</entry> <entry>R/3 with several languages or
	    typefaces</entry>
	  </row>
	  <row>
	    <entry>0171356</entry> <entry>SAP Software on Linux: Essential
	    Comments</entry>
	  </row>
	  <row>
	    <entry>0195603</entry> <entry>RedHat 6.1 Enterprise version:
	    Known problems</entry>
	  </row>
	  <row>
	    <entry>0212876</entry> <entry>The new archiving tool SAPCAR</entry>
	  </row>
	  <row>
	    <entry>0300900</entry> <entry>Linux: Released DELL Hardware</entry>
	  </row>
	  <row>
	    <entry>0377187</entry> <entry>RedHat 6.2: important remarks</entry>
	  </row>
	  <row>
	    <entry>0387074</entry> <entry>INST: R/3 4.6C SR2 Installation on 
	    UNIX</entry>
	  </row>
	  <row>
	    <entry>0387077</entry> <entry>INST: R/3 4.6C SR2 Inst. on UNIX - 
	    Oracle</entry>
	  </row>
	  <row>
	    <entry>0387078</entry> <entry>SAP Software on UNIX: OS Dependencies
	    4.6C SR2</entry>
	  </row>
	  </tbody>
	  </tgroup>
	</informaltable>
      </sect3>
    </sect2>

    <sect2 id="hardware-requirements">
      <title>Hardware-Requirements</title>

      <para>The following equipment is sufficient for the installation
	of a <application>SAP R/3 System</application>. For production
	use, a more exact sizing is of course needed:</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 Disk 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 disk access (SCSI, RAID hardware controller), USV
	and ECC-RAM is recommended.  The large amount of hard disk
        space is due to the preconfigured IDES System, which creates
	27 GB of database files during installation. This space is
	also sufficient for initial production systems and application
	data.</para>

      <sect3 id="hardware-46b">
        <title>SAP R/3 4.6B, Oracle 8.0.5</title>

      <para>The following off-the-shelf hardware was 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 CDROM), 
	Mylex AcceleRAID (2 channels, firmware 6.00-1-00 with 32MB RAM).
	To the Mylex Raid-controller are attached two 17GB hard disks 
	(mirrored) and four 36GB hard disks (RAID level 5).</para>
      </sect3>

      <sect3 id="hardware-46c">
	<title>SAP R/3 4.6C, Oracle 8.1.7</title>

      <para>For this installation a DELL PowerEdge 2500 was used: a
	dual processor board with two 1000MHz Pentium III processors
	(256kB Cache), 2GB PC133 ECC SDRAM, PERC/3 DC PCI Raid Controller
	with 128MB, and an EIDE DVD-ROM drive. To the RAID-controller are
	attached two 18GB hard disks (mirrored) and four 36GB hard disks
	(RAID level 5).</para>
      </sect3>
    </sect2>

    <sect2 id="installation">
      <title>Installation of FreeBSD</title>

      <para>First you have to install FreeBSD. There are several ways to do
	this (FreeBSD 4.3 was installed via FTP, FreeBSD 4.5 directly from
        release-CD).</para>

      <sect3 id="disk-layout">
	<title>Disk Layout</title>

	<para>To keep it simple, the same disk layout both for the
	  <application>SAP R/3 46B-</application> and <application>SAP R/3 46C
	  SR2-</application>installation was used. Only the device names
	  changed, as the installations were on different hardware (/dev/da 
	  and /dev/amr respectively, so if using an AMI MegaRAID, one will see
	  /dev/amr0s1a instead of /dev/da0s1a):</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>&lt;swap&gt;</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>Configure and initialize the two logical drives
          with the Mylex- or PERC/3 RAID software beforehand.
	  The software can be started during the 
	  bios boot phase.</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="makeworldandnewkernel">
        <title><command>make world</command> and a New Kernel</title>

	<para>Download the latest stable-sources. Rebuild world and your
	  custom kernel after configuring your kernel configuration file.
	  Here you should also include the
	  <link linkend="kerneltuning">kernel parameters</link> 
	  which are required for both <application>SAP R/3</application>
	  and <application>Oracle</application>.</para>
      </sect3>
    </sect2>

    <sect2 id="installingthelinuxenviornment">
      <title>Installing the Linux Environment</title>

      <para>During the first installation with FreeBSD 4.3-STABLE I had some
	trouble downloading the required RPM-files (for 4.3 stable, 2nd May 
	2001), but with FreeBSD 4.5-STABLE, everything went very smooth.
	Should you encounter some problems, try to download those files by
	hand. For a list of RPM-Mirrors and required files, see the
	corresponding makefile.</para>

      <sect3 id="installinglinuxbase-system">
        <title>Installing Linux Base-system</title>

        <para>First the <link linkend="linuxemu-libs-port">linux_base</link> 
	  port needs to be installed (as <username>root</username>). This is
	  currently <filename>linux_base-6</filename>.</para>

        <screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
&prompt.root; <userinput>make package</userinput></screen>

      </sect3>


      <sect3 id="installinglinuxdevelopment">
        <title>Installing Linux Development</title>

        <para>The Linux development is needed, if you want to install 
	  <application>Oracle</application> on FreeBSD according to the
	  corresponding description in the handbook:</para>

        <screen>&prompt.root; <userinput>cd /usr/ports/devel/linux_devtools</userinput>
&prompt.root; <userinput>make package</userinput></screen>

        <para>Linux Development has only been installed for the <application>SAP
	  R/3 46B IDES-</application> installation. It is not needed, if
	  the <application>Oracle DB</application> is not relinked on the
	  FreeBSD system. This is the case if you are using the
	  <application>Oracle</application> tarball from a linux system.</para> 

      </sect3>


      <sect3 id="installingnecessaryrpms">
        <title>Installing Necessary RPMs</title>
	<indexterm><primary>RPMs</primary></indexterm>

        <para>To start the R3SETUP-Program, pam support is needed. 
	  During the first SAP-Installation on FreeBSD 4.3-STABLE I
	  tried to install pam with all the required packages and
	  finally forced the installation of the pam package, which
	  worked. For <application>SAP R/3 4.6C SR2</application> I
	  directly forced the installation of pam rpm, which also 
	  works, so it seems the dependend packages are not needed:</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 8.0.5</application> to run the
	  intelligent agent, I also had to install the RedHat Tcl package 
          <filename>tcl-8.0.5-30.i386.rpm</filename> (otherwise the
          relinking during <application>Oracle</application> install
          will not work).  There are some other issues regarding
          relinking of <application>Oracle</application>, but that is
	  a Oracle-Linux issue, not FreeBSD specific.</para>

      </sect3>

      <sect3 id="linuxprocandfallbackelfbrand">
	<title>Some additional hints</title>
	<para>It might also be a good idea to add <filename>linprocfs</filename>
	  to <filename>/etc/fstab</filename>. See <command>man linprocfs</command>.
	  Another parameter to set is <emphasis>kern.fallback_elf_brand=3</emphasis>
	  which is done in file <filename>/etc/sysctl.conf</filename>.
      </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>It is also necessary to created some links. Otherwise
	  the SAP-Installer will complain, as it is checking the
	  created links:</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>

	<para>Possible error message during installation (here with
	  System <emphasis>PRD</emphasis> and the
	  <application>SAP R/3 4.6C SR2</application>
	  installation):</para>

	<screen>INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200	
    Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to
    /sapmnt/PRD/exe. Creating if it does not exist...

WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400
    Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file
    /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The
    program cannot go on as long as this link exists at this
    location. Move the link to another location.

ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0
    can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content
    '/sapmnt/PRD/exe'</screen>
      </sect3>

      <sect3 id="creatingusersanddirectories">
        <title>Creating Users and Directories</title>

        <para><application>SAP R/3</application> needs two users and
	  three groups. The usernames depend on the
	  <application>SAP</application> system id (SID) which consists
	  of three letters. Some of these SIDs are reserved
	  by <application>SAP</application> (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>, for the
	  4.6C SR2 installation <emphasis>PRD</emphasis>, as that system
	  is intended for production use.  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/prdadm</entry>
            <entry>&lt;sid&gt;adm</entry>
            <entry>sapsys</entry>
            <entry>oper</entry>
            <entry>SAP Administrator</entry>
          </row>
          <row>
            <entry>1002</entry>
            <entry>oraids/oraprd</entry>
            <entry>ora&lt;sid&gt;</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: &lt;sid&gt;adm
Password: ******
Fullname: SAP Administrator &lt;SID&gt;
Uid: 1000
Gid: 101 (sapsys)
Class:
Groups: sapsys dba
HOME: /home/&lt;sid&gt;adm
Shell: bash  (/compat/linux/bin/bash)</programlisting>

        <para>and for Database-Administrator:</para>

        <programlisting>Name: ora&lt;sid&gt; 
Password: ****** 
Fullname: Oracle Administrator &lt;SID&gt;
Uid: 1002 
Gid: 100 (dba) 
Class: 
Groups: dba 
HOME: /oracle/&lt;sid&gt; 
Shell: bash  (/compat/linux/bin/bash)</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 will set owners and rights 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 &lt;sid&gt;adm:sapsys /compat/linux/usr/sap</userinput>
&prompt.root; <userinput>chmod 775 /compat/linux/usr/sap</userinput></screen>

        <para>Second we will create directories as user 
	  <username>ora&lt;sid&gt;</username>. These
          will all be subdirectories of 
	  <filename>/oracle/&lt;SID&gt;</filename>:</para>

        <screen>&prompt.root; <userinput>su - ora&lt;sid&gt;</userinput>
&prompt.root; <userinput>cd /oracle/&lt;SID&gt;</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>For the <application>Oracle 8.1.7-</application>installation
	  some additional directories are needed:</para>

	<screen>&prompt.root; <userinput>su - ora&lt;sid&gt;</userinput>
&prompt.root; <userinput>cd /oracle</userinput>
&prompt.root; <userinput>mkdir 805_32</userinput>
&prompt.root; <userinput>mkdir client stage</userinput>
&prompt.root; <userinput>mkdir client/80x_32</userinput>
&prompt.root; <userinput>mkdir stage/817_32</userinput>
&prompt.root; <userinput>cd /oracle/&lt;SID&gt;</userinput>
&prompt.root; <userinput>mkdir 817_32</userinput></screen>

	<note><para>The directory <filename>client/80x_32</filename> is used
	  with exactly this name. Don't replace the <emphasis>x</emphasis>
	  with some number or anything.</para></note>

        <para>In the third step we create directories as user 
	  <username>&lt;sid&gt;adm</username>:</para>

        <screen>&prompt.root; <userinput>su - &lt;sid&gt;adm</userinput>
&prompt.root; <userinput>cd /usr/sap</userinput>
&prompt.root; <userinput>mkdir &lt;SID&gt;</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 will 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>). If you are going to use a saprouter
	  or need to access SAP OSS, you also need <emphasis>99</emphasis>,
	  as port 3299 is usually used for the saprouter process on the
	  target system:</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
sapms&lt;SID&gt; 3600/tcp # SAP Message Server.  3600 + Instance-Number
sapgw00s   4800/tcp # SAP Secure Gateway   4800 + Instance-Number</programlisting>
      </sect3>

      <sect3 id="necessarylocales">
        <title>Necessary Locales</title>
	<indexterm><primary>locale</primary></indexterm>

        <para>SAP requires at least two locales that are not 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 would not 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>Create the links like this:</para>

	<screen>&prompt.root; <userinput>cd /compat/linux/usr/share/locale</userinput>
&prompt.root; <userinput>ln -s de_DE de_DE.ISO-8859-1</userinput>
&prompt.root; <userinput>ln -s en_US en_US.ISO-8859-1</userinput></screen>

        <para>If they are not present, there will be some problems
          during the installation.  If these are then subsequently
          ignored (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:</para>

        <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 SHMMAXPGS=393216 #use this for the 46C inst.parameters
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>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. As the system
	  for the 4.6C SR2 installation has more main memory, the shared
	  segments can be larger both for <application>SAP</application>
	  and <application>Oracle</application>, therefore choose a larger
	  number of shared memory pages.</para>

	<note><para>With the default installation of FreeBSD 4.5 on x386,
	  leave MAXDSIZ and DFLDSIZ at 1GB maximum. Otherwise, strange 
	  errors like <emphasis>ORA-27102: out of memory</emphasis> and 
          <emphasis>Linux Error: 12: Cannot allocate memory</emphasis>
          might happen.</para></note>
      </sect3>
    </sect2>

    <sect2 id="installingsapr3">
      <title>Installing SAP R/3</title>

      <sect3 id="preparingsapcdroms">
        <title>Preparing SAP CDROMs</title>

        <para>There are many CDROMs to mount and unmount during the
          installation.  Assuming you have enough CDROM-drives, you
          can just mount them all.  I decided to copy the CDROM
          contents to corresponding directories:</para>

	<programlisting>/oracle/&lt;SID&gt;/sapreorg/&lt;cd-name&gt;</programlisting>

        <para>where &lt;cd-name&gt; was one of <filename>KERNEL</filename>, 
	  <filename>RDBMS</filename>, <filename>EXPORT1</filename>,
	  <filename>EXPORT2</filename>, <filename>EXPORT3</filename>,
	  <filename>EXPORT4</filename>, <filename>EXPORT5</filename> and 
	  <filename>EXPORT6</filename> for the 4.6B/IDES-installation, and
	  <filename>KERNEL</filename>, <filename>RDBMS</filename>,
	  <filename>DISK1</filename>, <filename>DISK2</filename>,
	  <filename>DISK3</filename>, <filename>DISK4</filename> and
	  <filename>LANG</filename> for the 4.6C SR2-installation. All the
	  filenames on the mounted CDs 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/&lt;SID&gt;/sapreorg/&lt;cd-name&gt;</userinput>
&prompt.root; <userinput>umount /mnt</userinput></screen>
      </sect3>

      <sect3 id="runningtheinstall-script">
        <title>Running the install-script</title>

	<para>First you have to prepare an install-directory:</para>

	<screen>&prompt.root; <userinput>cd /oracle/&lt;SID&gt;/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>

	<screen>&prompt.root; /oracle/&lt;SID&gt;/sapreorg/KERNEL/UNIX/INSTTOOL.SH</screen>

	<para>The IDES-Installation (4.6B) comes with a fully customized
	  SAP R/3 Demo-System, so there are six instead of just three
          EXPORT-CDs.  At this point the installation template
	  <filename>CENTRDB.R3S</filename> is for installing a standard
	  central instance (R/3 and Database), not the IDES central
	  instance, so one needs to copy the corresponding CENTRDB.R3S
	  from the EXPORT1 directory, otherwise R3SETUP will only ask
	  for three EXPORT-CDs.</para>

	<para>The newer <application>SAP 4.6C SR2-</application>release
	  comes with four EXPORT-CDs. The parameter-file that controls
	  the installation-steps is <filename>CENTRAL.R3S</filename>.
	  Contrary to earlier releases there are no separate installation
	  templates for a central instance with or without database.
	  SAP is using a separate template for DB-installation. To restart
	  the installation later it is however sufficient to restart with
	  the original file.</para>

	<para>During and after installation, SAP requires
	  <command>hostname</command> to return the computer name
	  only, not the fully qualified domain name. So either
	  set the hostname accordingly, or set an alias with
	  <command>alias hostname='hostname -s'</command> for
	  both <username>ora&lt;sid&gt;</username> and 
	  <username>&lt;sid&gt;adm</username> (and for
	  <username>root</username> at least during installation
	  steps performed as <username>root</username>). It is also 
	  possible to adjust the installed profile- and login-scripts of
	  both users that are installed during 
	  <application>SAP-</application>installation.</para>
      </sect3>

      <sect3 id="startr3setup-46B">
        <title>Start R3SETUP 4.6B</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 <username>root</username> 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&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter SAP Instance Number</entry>
            <entry>[00]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter SAPMOUNT Directory</entry>
            <entry>[/sapmnt]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter name of SAP central host</entry>
            <entry>[troubadix.domain.de]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter name of SAP db host</entry>
            <entry>[troubadix]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Select character set</entry>
            <entry>[1] (WE8DEC)</entry>
            <entry>&lt;ret&gt;</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&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Extract Oracle Client archive</entry>
            <entry>[1] (Yes, extract)</entry>
            <entry>&lt;ret&gt;</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>&lt;ret&gt;</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>&lt;ret&gt;</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>&lt;ret&gt;</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>&lt;ret&gt;</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>&lt;ret&gt;</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>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter amount of RAM for SAP + DB</entry>
            <entry> </entry>
            <entry>850&lt;ret&gt; (in Megabytes)</entry>
          </row>
          <row>
            <entry>Service Entry Message Server</entry>
            <entry>[3600]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter Group-ID of sapsys</entry>
            <entry>[101]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter Group-ID of oper</entry>
            <entry>[102]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter Group-ID of dba</entry>
            <entry>[100]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter User-ID of &lt;sid&gt;adm</entry>
            <entry>[1000]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter User-ID of ora&lt;sid&gt;</entry>
            <entry>[1002]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Number of parallel procs</entry>
            <entry>[2]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          </tbody>
          </tgroup>
        </informaltable>
      
        <para>If you had not copied the CDs to the different locations,
          then the SAP-Installer cannot find the CD needed (identified
          by the <filename>LABEL.ASC</filename>-File on CD) and would
          then ask you to insert and mount the CD and confirm or enter
          the mount path.</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_LOCATION, then 7_LOCATION
          etc.), so one can just continue with entering the correct
          values. Do not get irritated.</para>

        <para>Apart from some problems mentioned below, everything
          should go straight through up to the point where the Oracle
          database software needs to be installed.</para>
      </sect3>

      <sect3 id="startr3setup-46C">
	<title>Start R3SETUP 4.6C SR2</title>

	<para>Make sure LD_LIBRARY_PATH is set correctly. This is a
	  different value from the 4.6B installation with
	  <application>Oracle 8.0.5</application>:</para>

	<screen>&prompt.root; <userinput>export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib</userinput></screen>

	<para>Start R3SETUP as user root from installation directory:</para>

	<screen>&prompt.root; <userinput>cd /oracle/PRD/sapreorg/install</userinput>
&prompt.root; <userinput>./R3SETUP -f CENTRAL.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>PRD&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter SAP Instance Number</entry>
	    <entry>[00]</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter SAPMOUNT Directory</entry>
	    <entry>[/sapmnt]</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter name of SAP central host</entry>
	    <entry>[majestix]</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter Database System ID</entry>
	    <entry>[PRD]</entry>
	    <entry>PRD&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter name of SAP db host</entry>
	    <entry>[majestix]</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Select character set</entry>
	    <entry>[1] (WE8DEC)</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter Oracle server version (2) Oracle 8.1.7</entry>
	    <entry> </entry>
	    <entry>2&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Extract Oracle Client archive</entry>
	    <entry>[1] (Yes, extract)</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter path to KERNEL CD</entry>
	    <entry>[/sapcd]</entry>
	    <entry>/oracle/PRD/sapreorg/KERNEL</entry>
	  </row>
	  <row>
	    <entry>Enter amount of RAM for SAP + DB</entry>
	    <entry>2044</entry>
	    <entry>1800&lt;ret&gt; (in Megabytes)</entry>
	  </row>
	  <row>
	    <entry>Service Entry Message Server</entry>
	    <entry>[3600]</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
	    <entry>Enter Group-ID of sapsys</entry>
	    <entry>[100]</entry>
	    <entry>&lt;ret&gt;</entry>
	  </row>
	  <row>
            <entry>Enter Group-ID of oper</entry>
            <entry>[101]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter Group-ID of dba</entry>
            <entry>[102]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter User-ID of <username>oraprd</username></entry>
            <entry>[1002]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter User-ID of <username>prdadm</username></entry>
            <entry>[1000]</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>LDAP support</entry>
            <entry> </entry>
            <entry>3&lt;ret&gt; (no support)</entry>
          </row>
          <row>
            <entry>Installation step completed</entry>
            <entry>[1] (continue)</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Choose installation service</entry>
            <entry>[1] (DB inst,file)</entry>
            <entry>&lt;ret&gt;</entry>
          </row>
          </tbody>
          </tgroup>
        </informaltable>
      
        <para>So far, creation of users gives an error during
	  installation in phases OSUSERDBSID_IND_ORA (for creating
	  user <username>ora&lt;sid&gt;</username>) and 
	  OSUSERSIDADM_IND_ORA (creating user 
	  <username>&lt;sid&gt;adm</username>).</para>
   
        <para>Apart from some problems mentioned below, everything
          should go straight through 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 <link
	  linkend="linuxemu-oracle">the Installing Oracle
	  chapter.</link></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 did not 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 cannot 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 <application>Oracle 8.0.5 PreProduction</application>
	  release, after the first
          attempt at getting the version from the RDBMS-CD working,
          failed, and finding and 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="installingoracle817">
      <title>Installing the Oracle 8.1.7 linux tarball</title>
      <para>Take the tarball <filename>oracle81732.tgz</filename> you
	produced from the installation directory on a linux system
	and untar it to <filename>/oracle/&lt;SID&gt;/817_32/</filename></para>
    </sect2>

    <sect2 id="continuewithsapr4installation">
      <title>Continue with SAP R/3 Installation</title>

      <para>First check the environment settings of users 
	<username>idsamd</username>
        (&lt;sid&gt;adm) and 
	<username>oraids</username> (ora&lt;sid&gt;). 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 (for 46B IDES, from 
	  EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) 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&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Confirum Password for sapr3</entry>
            <entry>sap&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter Password for sys</entry>
            <entry>change_on_install&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Confirm Password for sys</entry>
            <entry>change_on_install&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Enter Password for system</entry>
            <entry>manager&lt;ret&gt;</entry>
          </row>
          <row>
            <entry>Confirm Password for system</entry>
            <entry>manager&lt;ret&gt;</entry>
          </row>
          </tbody>
          </tgroup>
        </informaltable>

        <para>At this point I had a few problems with 
	  <literal>dipgntab</literal> during the 4.6B
	  installation.</para>
      </sect3>

      <sect3 id="listener">
        <title>Listener</title>

        <para>Start the Oracle-Listener as user 
	  <username>ora&lt;sid&gt;</username> as follows:</para>

        <screen>&prompt.user; <userinput>umask 0; lsnrctl start</userinput></screen>

        <para>Otherwise you might get ORA-12546 as the sockets will not
        have the correct permissions. See SAP note 072984.</para>
      </sect3>

      <sect3 id="mnlstables">
	<title>Updating MNLS Tables</title>
	<para>If you plan to import non-Latin-1 languages into the SAP-System,
	  you have to update the Multi National Language Support tables.
	  This is described in the SAP OSS-Notes 15023 and 45619. Otherwise,
	  you can skip this question during SAP installation.</para>
	<note><para>If you don't need MNLS, it is still necessary to check
	  table TCPDB and initializing it if this hasn't been done. See
	  SAP note 0015023 and 0045619 for further information.</para></note>
      </sect3>
    </sect2>

    <sect2 id="postinstallationsteps">
      <title>Post-installation Steps</title>

      <sect3 id="requestsapr3licensekey">
        <title>Request SAP R/3 License Key</title>

        <para>You have to request your SAP R/3 License Key. This is needed,
	  as the temporary license that was installed during installation
	  is only valid for four weeks. 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   = &lt;SID, 3 chars&gt;
CUSTOMER KEY    = &lt;hardware key, 11 chars&gt;
INSTALLATION NO = &lt;installation, 10 digits&gt;
EXPIRATION DATE = &lt;yyyymmdd, usually "99991231"&gt;
LICENSE KEY     = &lt;license key, 24 chars&gt;</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 <username>ddic</username>
	  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&lt;sid&gt;.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 behavior 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 you need 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 
	<command>brbackup</command>
        complains as soon as <command>cpio</command> outputs the 
	numbers of blocks saved.</para>

        <para><emphasis>cpio_in_flags</emphasis> Flags needed for
        loading data back from tape. Format is recognized
        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 value is slightly lower than the
        actual value.</para>

        <para><emphasis>tape_address</emphasis> The non-rewindable
        device to be used with <command>cpio</command>.</para>

        <para><emphasis>tape_address_rew The rewindable device to be
        used with cpio.</emphasis></para>
      </sect3>

      <sect3>
	<title>Configuration Issues after Installation</title>

	<para>The following SAP-parameters should be tuned after
	  installation (examples for IDES 46B, 1GB memory):</para>

	<informaltable frame="none">
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Name</entry>
		<entry>Value</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>ztta/roll_extension</entry>
		<entry>250000000</entry>
	      </row>
	      <row>
		<entry>abap/heap_area_dia</entry>
                <entry>300000000</entry>
	      </row>
	      <row>
		<entry>abap/heap_area_nondia</entry>
		<entry>400000000</entry>
	      </row>
	      <row>
		<entry>em/initial_size_MB</entry>
		<entry>256</entry>
	      </row>
	      <row>
		<entry>em/blocksize_kB</entry>
		<entry>1024</entry>
	      </row>
	      <row>
		<entry>ipc/shm_psize_40</entry>
		<entry>70000000</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>SAP-Note 0013026:</para>

	<informaltable frame="none">
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Name</entry>
		<entry>Value</entry>
	      </row>
	    <tbody>
	      <row>
		<entry>ztta/dynpro_area</entry>
		<entry>2500000</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>SAP-Note 0157246:</para>

	<informaltable frame="none">
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Name</entry>
		<entry>Value</entry>
	      </row>
	    <tbody>
	      <row>
		<entry>rdisp/ROLL_MAXFS</entry>
		<entry>16000</entry>
	      </row>
	      <row>
		<entry>rdisp/PG_MAXFS</entry>
		<entry>30000</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<note>
	  <para>With the above parameters, on a system with 1 gigabyte
	    of memory, one may find memory consumption similar to:

	  <programlisting>Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free</programlisting></para>
	</note>
      </sect3>
    </sect2>

    <sect2 id="problemsduringinstallation">
      <title>Problems During Installation</title>

      <sect3 id="restartr3setup">
	<title>Restart R3SETUP after fixing a problem</title>

	<para>R3SETUP stops if it encounters an error. If you have
	  looked at the corresponding logfiles and fixed the error,
	  you have to start R3SETUP again, usually selecting REPEAT
	  as option for the last step R3SETUP complained about.</para>

	<para>To restart R3SETUP, just start it with the corresponding
	  <emphasis>R3S-</emphasis>file:
	  <screen>&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
	  for 4.6B, or with
	  <screen>&prompt.root; <userinput>./R3SETUP -f CENTRAL.R3S</userinput></screen>
	  for 4.6C, no matter whether the error occured
	  with <filename>CENTRAL.R3s</filename> or
	  <filename>DATABASE.R3S</filename>.</para>

	<note><para>At some stages, R3SETUP assumes that both database-
	    and SAP-processes are up and running (as those were steps it
	    already completed). Should errors occur and for example the 
	    database could not be started, you have to start both database 
	    and SAP by hand after you fixed the errors and before starting 
	    R3SETUP again.</para>
	  <para>Don't forget to also start the oracle listener again (as 
	    <username>ora&lt;sid&gt</username> with
	    <command>umask 0; lsnrctl start</command>) if it was also
	    stopped (for example due to a necessary reboot of the 
	    system).</para>
	</note>
      </sect3>

      <sect3 id="indoraduringduringr3setup">
        <title>OSUSERSIDADM_IND_ORA During R3SETUP</title>

        <para>If R3SETUP complains at this stage, edit the
	  template file R3SETUP used at that time
          (<filename>CENTRDB.R3S</filename> (4.6B) or either
	  <filename>CENTRAL.R3S</filename> or
	  <filename>DATABASE.R3S</filename> (4.6C)).
	  Locate [OSUSERSIDADM_IND_ORA] or search for the
	  only <emphasis>STATUS=ERROR</emphasis>-entry
	  and edit the following values:</para>

        <programlisting>HOME=/home/&lt;sid&gt;adm (was empty)
STATUS=OK (had status ERROR)
        </programlisting>

        <para>Then you can restart R3SETUP again.</para>
      </sect3>

      <sect3 id="indoraduringr3setup">
        <title>OSUSERDBSID_IND_ORA During R3SETUP</title>

        <para>Possibly R3SETUP also complains at this stage. The error
	  here is similar to the one in phase OSUSERSIDADM_IND_ORA. 
	  Just edit
	  the template file R3SETUP used at that time
          (<filename>CENTRDB.R3S</filename> (4.6B) or either
	  <filename>CENTRAL.R3S</filename> or
	  <filename>DATABASE.R3S</filename> (4.6C)).
	  Locate [OSUSERDBSID_IND_ORA] or search for the
	  only <emphasis>STATUS=ERROR</emphasis>-entry
	  and edit the following value in that section:</para>

        <programlisting>STATUS=OK</programlisting>

        <para>Then restart R3SETUP.</para>
      </sect3>

      <sect3 id="oraviewvrffilenotfound">
        <title>oraview.vrf FILE NOT FOUND During Oracle Installation</title>

        <para>You have not 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
	  <literal>sapgui</literal>, even though the system
	  can be started. Trying to connect with the old Linux
	  <literal>sapgui</literal> 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 behavior 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 
	  <filename>DEFAULT.PFL</filename> (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 you 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 <filename>DEFAULT.PFL</filename> and the SAP
	  system can be restarted.</para>

      </sect3>

      <sect3 id="ora-00001">
	<title>ORA-00001</title>
	<para>This error only happened with 
	  <application>Oracle 8.1.7</application> on FreeBSD 4.5.
	  The reason was that the Oracle database could not initialize itself
	  properly and crashed, leaving semaphores and shared memory on the
	  system. The next try to start the database then returned
	  <emphasis>ORA-00001</emphasis>.</para>

	<para>Find them with <command>ipcs -a</command> and remove them
	  with <command>ipcrm</command>.</para>
      </sect3>

      <sect3 id="ora-00445pmon">
	<title>ORA-00445 (background process PMON did not start)</title>
	<para>This error happened with <application>Oracle 8.1.7</application>.
	  This error is reported if the Database is started with
	  the usual startsap-script (for example
	  <filename>startsap_majestix_00</filename>) as user 
	  <username>prdadm</username>.</para>

	<para>A possible workaround is to start the database as user 
	  <username>oraprd</username> instead
	  with <command>svrmgrl</command>:</para>

	<screen>&prompt.user; <userinput>svrmgrl</userinput>
SVRMGR&gt; <userinput>connect internal;</userinput>
SVRMGR&gt; <userinput>startup</userinput>;
SVRMGR&gt; <userinput>exit</userinput></screen>

      </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 you might get ORA-12546 as the sockets will not
          have the correct permissions. See SAP note 0072984.</para>
      </sect3>

      <sect3 id="ora-27102">
	<title>ORA-27102 (out of memory)</title>

	<para>This error happend whilst trying to use values for
	  <emphasis>MAXDSIZ</emphasis> and <emphasis>DFLDSIZ</emphasis>
	  greater than 1GB (1024x1024x1024). Additionally, I got 
	  <emphasis>Linux Error 12: Cannot allocate memory</emphasis>.</para>
      </sect3>

      <sect3 id="dipgntabindind">
        <title>[DIPGNTAB_IND_IND] During R3SETUP</title>

        <para>In general, see SAP note 0130581 (R3SETUP step 
	  <literal>DIPGNTAB</literal> terminates).  During the
	  IDES-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 &lt;SID&gt; (in this case IDS).  So instead
	  of accessing:</para>

        <programlisting>/usr/sap/IDS/SYS/...
/usr/sap/IDS/DVMGS00</programlisting>

        <para>the following paths were used:</para>

        <programlisting>/usr/sap//SYS/...
/usr/sap/D00</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 behavior. I did not encounter any of these problems with
	the <application>SAP 4.6C-</application>Installation.</para>
      </sect3>

      <sect3 id="rfcrswboiniindind">
        <title>[RFCRSWBOINI_IND_IND] During R3SETUP</title>

	<para>During installation of <application>SAP 4.6C</application>,
          this error was just the result of another error happening
	  earlier during installation. In this case, you have to look
	  through the corresponding logfiles and correct the real
	  problem.</para>

        <para>If after looking through the logfiles this error is
	  indeed the correct one (check the SAP-notes), you can 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
	  <literal>RSWBOINS</literal> from transaction SE38. See SAP
	  note 0162266 for additional information about phase
	  <literal>RFCRSWBOINI</literal> and
	  <literal>RFCRADDBDIF</literal>.</para>
      </sect3>

      <sect3 id="rfcraddbdifindind">
        <title>[RFCRADDBDIF_IND_IND] During R3SETUP</title>
	<para>Here the same restrictions apply: Make sure by looking
	  through the logfiles, that this error is not caused by some
	  previous problems.</para>

        <para>If you can confirm that SAP-Note 0162266 applies, just 
	  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
	  <literal>RADDBDIF</literal> from transaction SE38.</para>
      </sect3>

      <sect3 id="sigactionsig31">
        <title>sigaction sig31: File size limit exceeded</title>

	<para>This error occured during start of SAP-processes
	  <emphasis>disp+work</emphasis>. If starting SAP with the
	  startsap-script, subprocesses are then started which
	  detach and do the dirty work of starting all other SAP 
          processes. As a result, the script itself won't notice
	  if something goes wrong.</para>

	<para>To check whether the SAP processes did start properly,
	  have a look at the process status with 
	  <command>ps ax | grep &lt;SID&gt;</command>, which will give
	  you a list of all Oracle- and SAP-processes. If it looks like
	  some processes are missing or if you can't connect to the SAP-System,
	  look at the corresponding logfiles which can be found
	  at <filename>/usr/sap/&lt;SID&gt;/DVEBMGS&lt;nr&gt;/work/</filename>.
	  The files to look at are <filename>dev_ms</filename> and 
	  <filename>dev_disp</filename>.</para>

	<para>Signal 31 happens here if the amount of shared memory used by
	  Oracle and SAP exceed the one defined within the kernel configuration
	  file and could be resolved by using a larger value:</para>

        <programlisting># larger value for 46C production systems:
options SHMMAXPGS=393216
# smaller value sufficient for 46B:
#options SHMMAXPGS=262144</programlisting>
	  
      </sect3>

      <sect3 id="saposcolfails">
        <title>Start of saposcol failed</title>
	<para>There are some problems with Program saposcol (version 4.6D).
	  The SAP-System is using saposcol to collect data about the 
	  system performance. This program is not needed to use the SAP-System,
	  so this problem can be considered a minor one. The older versions
	  (4.6B) does work, but doesn't collect all the data (many calls will
	  just return 0, for example for CPU useage).</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>&lt;199906020108.SAA07001@usr09.primenet.com&gt;</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&hellip;  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!  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&mdash;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:
-->

