                     Installing MOSIX for Linux 2.4.20
                    ----------------------------------

A. General:
   --------

This document explains how to install MOSIX in a single computer (node).

To create a MOSIX cluster, either install MOSIX in each node separately, or
see below about cluster installation.

It is best to have all the nodes in the cluster run the  exact  same  MOSIX
version.  The minimum requirement is that the first two digits of the MOSIX
version are the same on all nodes.  It is also required that  kernels  with
the  DFSA  option  configured  are  not mixed with kernels without the DFSA
option in the same cluster.  If  these  requirements  are  violated,  MOSIX
nodes will refuse to communicate with each other.


1.   The  MOSIX  designated  node(s)  must first have Linux installed.  The
     MOSIX installation procedure was tested with the RedHat  (up  to  8.0)
     and SuSE (up to 8.0) distributions.

2.   Obtain  the  OFFICIAL  Linux  kernel  sources  of  version 2.4.20 from
     http:/www.kernel.org/pub/linux/v2.4/linux-2.4.20.tgz:    unpredictable
     results may occur if you use any other Linux kernel sources.  With the
     automatic installation you do not need to extract the files  from  the
     Linux  kernel distribution: if you do, we recommend to place the Linux
     kernel sources in /usr/src/linux-2.4.20 (but any other directory  will
     do).

3.   Make  sure  that  you  conform  to  the  "minimal requirements" of the
     particular    Linux    kernel    version,    as    found    in     the
     `Documentation/Changes'  file,  especially  with regard to Make, GNU C
     and Binutils.

     Since Linux-2.4.10, the requirements are: Make version 3.77 or higher;
     Gcc  version  2.95.3,  2.95.4  or  2.96.74+  (gcc-2.91.66 is no longer
     reliable); and Binutils 2.9.1.0.25 or higher.

4.   It is recommended to backup your  system  before  starting  the  MOSIX
     installation.

Below are automatic and manual installation instructions.

B. Automatic installation:
   -----------------------
The  automatic  installer  requires that you have Perl version 5.5 or newer
installed.
You must run the following as Super-User:

1.   Untar the MOSIX-1.9.0.tgz file:
          tar xzf MOSIX-1.9.0.tgz

2.   Untar the MOSKRN-1.9.0.tgz file:
          tar xzf MOSKRN-1.9.0.tgz

3.   Run:
          cd MOSIX-1.9.0
          ./mosix.install

     "mosix.install" will guide you through the installation.

     Note: when configuring the kernel, you must  not  remove  the  default
     options   of   CONFIG_BINFMT_ELF  and  CONFIG_PROC_FS.  It  is  highly
     recommended that users of RedHat 7.2+  also  configure  CONFIG_EXT3_FS
     (unless they are experts and know they don't need it).

     Now the script will compile and install the MOSIX kernel.

3.   During  the  installation,  "mosix.install"  modifies the files listed
     below.  To undo these modifications, the original  contents  of  those
     files  are  saved with the ".pre_mosix" extension. The following files
     are modified:

                    - /etc/inittab
                    - /etc/inetd.conf and/or /etc/xinetd.d/*
                    - /etc/lilo.conf
                    - /etc/rc.d/init.d/atd
                    - /etc/cron.daily/slocate.cron

     Note: modifying any of those files after the installation,  especially
     by  installing  a  new  version  of  Linux,  may  override  the MOSIX-
     installation, thus MOSIX may not run correctly.

     When uninstalling MOSIX (using "./mosix.install  --uninstall"),  those
     files are restored to their previous contents.

4.   For  NFS  users:  during the installation procedure, new files will be
     placed in the "/usr" and "/usr/local" directories.  If  any  of  those
     directories is shared (using NFS) then make sure that either:
     (1)  the  node  where those directories reside is part of the adjusted
     cluster,
     or,
     (2) The Super-User of at least one node using  those  directories  has
     write access to them.

     If  you  see  error-messages  with  inability  to  write to "/usr", or
     "/usr/local", you may ignore those messages - provided that  at  least
     one of the above conditions is true.


C. Manual Installation:
   --------------------

To create the MOSIX kernel:


1.   Download  and  "untar"  the  MOSIX-1.9.0.tgz  and  MOSKRN-MOSIXREL.tgz
     files.

          tar xzf MOSIX-1.9.0.tgz
          tar xzf MOSKRN-1.9.0.tgz

2.   Download   and    "untar"    the    Linux    kernel    sources    into
     /usr/src/linux-2.4.20.

3.   Patch the Linux kernel sources with the MOSIX patch:
                    cd MOSKRN-1.9.0
          sh/bash:  patches=`pwd`/patches.2.4.20
          csh/tcsh: set patches = `pwd`/patches.2.4.20
                    cd /usr/src/linux-2.4.20
                    patch -p0 < $patches


4.   Configure   the   kernel   with  CONFIG_MOSIX,  CONFIG_BINFMT_ELF  and
     CONFIG_PROC_FS (they should be configured by default  anyway).  It  is
     highly   recommended   that   users  of  RedHat  7.2+  also  configure
     CONFIG_EXT3_FS (unless they are experts and know they don't need  it).
     Then  remove  the  file "include/linux/version.h" and make and install
     the kernel and modules in the usual way.

4.1. The  MOSIX  kernel-debugger  is  used  for  development  and  is   not
     supported,  but  you  may  configure  and  use  it  AS  IS if you wish
     (entering the debugger is via the <ALT-NumLock> key).

To configure your system:


1.   Include  the  resulting   kernel   in   either   "/etc/lilo.conf"   or
     "/etc/grub.conf" (or whatever other boot loader you use).

2.   To   obtain   the   MOSIX   manual,   untar   "manuals.tar"  into  the
     /usr/share/man directory (or if this directory does not exist on  your
     ditribution, unstar it into the /usr/local/man directory).

3.   To  obtain  the  user-programs,  create  a  new  directory  and  untar
     "user.tar" there, create  symbolic-links  from  "/usr/src/linux"  into
     your  MOSIX  kernel-source  directory and from "/usr/include/mos" into
     "/usr/src/linux/include/mos", then run "make install" in the directory
     where you unpacked user.tar.

4.   To  ensure  that  critical  daemons  are  not  migrated away, edit the
     "/etc/inittab" file and prefix  all  daemon-generating  programs  with
     "/bin/mosrun  -h",  for  example,  change  "/etc/rc.d/rc.d/rc  3" into
     "/bin/mosrun -h /etc/rc.d/rc.d/rc 3", other obvious  entries  are  for
     "rc.sysinit", "update" and "shutdown".

     One  exception to the rule is the "atd" daemon that should probably be
     allowed to migrate, so that its children, the time-based "at" jobs are
     allowed to migrate.  This is done by adding the line:

     "echo 0 > /proc/$$/lock"

     At  the  beginning  of  the  file  "/etc/rc.d/init.d/atd"  (some Linux
     installations   place   this    file    elsewhere,    such    as    in
     "/etc/init.d/atd").

     Most  "inet"  services  should probably not be allowed to migrate (for
     example, "ftp", "talk", "time"), but a few services - especially those
     that produce an interactive session: "telnet", "rsh", "rlogin", "ssh",
     perhaps also "rexec", should be allowed to migrate.

     Since "inetd" (or "xinetd") itself is  locked  along  with  the  other
     daemons,  you only need to deal with the migratable services.  If your
     Linux installation uses the "inetd" daemon, you must  modify  all  the
     lines  in  "/etc/inetd.conf"  that  correspond to migratable services:
     This is  done  by  prefixing  the  "/usr/sbin/tcpd"  column  with  the
     following:

     "/bin/mosrun mosrun -l -z"

     For example,

     telnet  stream tcp nowait root /bin/mosrun mosrun -l -z /usr/sbin/tcpd
     in.telnetd

     If your Linux installation (notably RedHat 7) uses "xinetd", you  must
     modify the appropriate files, "/etc/xinetd.d/{service_name}" to prefix
     the   command   with   "/bin/mosrun   -l".     For    example,    edit
     /etc/xinetd.d/rlogin, changing:

     server = /usr/sbin/in.rlogin

     into

     server = /bin/mosrun
     server_args = -l /usr/sbin/in.rlogin

     Also,  if  you have the sshd daemon installed, you'll probably want to
     unlock it.   This  can  be  done  by  adding  the  following  line  to
     /etc/init.d/sshd, right in the beginning of the start() function:

     echo 0 >> /proc/$$/lock

5.   If  you  intend  to  use the MFS file-systems, you must edit the file:
     "/etc/cron.daily/slocate.cron" and add "mfs" to the list of  networked
     file-systems (alongside "nfs", "smbfs" and "ncpfs").

     The  "/etc/cron.daily/slocate.cron"  appears in later RedHat releases:
     For other releases, you may wish to  look  for  similar  scripts  that
     automatically call "locate" or "slocate".

6.   copy   the   file   "mosix.init"   to   "/etc/rc.d/init.d/mosix"   (or
     "/etc/init.d", depending  on  the  Linux  installation)  and  make  it
     executable,  then link it to the various run-levels (2-5) in which you
     wish to start MOSIX automatically.  You can use the  run-level  editor
     for  this  task.   MOSIX  must  be started AFTER the network is up and
     stopped BEFORE the network comes down, therefore, it is recommended to
     give  the start-script a priority of 95 and the stop-script a priority
     of 05.  To activate MOSIX in  run-level  3,  for  example,  you  could
     simply type:

          ln -s /etc/rc.d/init.d/mosix /etc/rc.d/rc3.d/S95mosix

     You  may  wish to deactivate MOSIX in certain run-levels, but you MUST
     at least deactivate MOSIX in those run-levels where the network is de-
     activated: commonly 0(halt), 1 (single-user), and 6 (reboot):

          ln -s /etc/rc.d/init.d/mosix /etc/rc.d/rc0.d/K05mosix
          ln -s /etc/rc.d/init.d/mosix /etc/rc.d/rc1.d/K05mosix
          ln -s /etc/rc.d/init.d/mosix /etc/rc.d/rc6.d/K05mosix

Note: It is possible to use the scripts in the /inst directory of the MOSIX
distribution, to do these steps automatically. The  scripts  in  the  /inst
directory require that you have Perl version 5.5 or newer installed.

D. Cluster-installation:
   ---------------------

Once  MOSIX  is  installed  on  one node, there are packages that assist in
distributing it to the remaining nodes.
Some such packages are available from LTSP (http://www.ltsp.org/) and
from ClusterNFS (http://ClusterNFS.sourceforge.net/).



E. Copyright:
   ----------

All files in this  directory  are  Copyright  (c)  2000-2002,  Amnon  BARAK
(amnon@MOSIX.org),  whether an explicit Copyright note is present or not in
individual files.

All rights are reserved, subject to the MOSIX SOFTWARE  LICENSE  AGREEMENT,
with the exception of the kernel patches
(patches.2.4.20) that are issued under the GNU General Public License (GPL)
as published by the Free Software Foundation.

THIS SOFTWARE IS PROVIDED IN  ITS  "AS  IS"  CONDITION,  WITH  NO  WARRANTY
WHATSOEVER.  NO  LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING
FROM THE USE OF THIS SOFTWARE WILL BE ACCEPTED.


This is all: reboot and enjoy MOSIX!
