                   Installing MOSIX for Linux 2.4.17
                   ----------------------------------

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 ker-
nels with the DFSA option configured are not mixed with kernels  without
the  DFSA  option  in  the same cluster.  If these requirements are vio-
lated, 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 5.1, 6.0,
     6.2, 7.0, 7.1 and SuSE 6.0, 6.1, 6.2, 6.3, 7.0 distributions.

2.   Obtain the Linux kernel sources of  version  2.4.17.  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.17  (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  `Documenta-
     tion/Changes' file, especially with regard to Make, GNU C and Binu-
     tils.

     From 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+ , also gcc-2.91.66
     should still compile correctly for a little longer, but  will  miss
     some optimizations; and Binutils 2.9.1.0.25 or higher.

4.   Read  the  section  on Pentium-MMX (below) if you have such proces-
     sor(s).

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

Below are automatic and manual installation instructions.

B. Automatic installation:
   -----------------------
You must run the following as Super-User:

1.   Untar the MOSIX-1.5.7.tar.gz file:
          tar xzf MOSIX-1.5.7.tar.gz

2.   Run:
          cd MOSIX-1.5.7
          ./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.

     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, espe-
     cially 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.5.7.tar.gz file.

          cd MOSIX-1.5.7
          tar xzf MOSIX-2.4.17.tar.gz

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

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


4.   Configure  the kernel with CONFIG_MOSIX, CONFIG_BINFMT_ELF and CON-
     FIG_PROC_FS (they should be configured  by  default  anyway),  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  sup-
     ported,  but you may configure and use it AS IS if you wish (enter-
     ing the debugger is via the <ALT-NumLock> key).

To configure your system:


1.   Include the resulting kernel in either "/etc/lilo.conf"  (or  what-
     ever other booting-system you use).

2.   To   obtain   the   MOSIX  manual,  untar  "manuals.tar"  into  the
     /usr/local/man directory.

3.   To obtain the  user-programs,  untar  "user.tar",  preferably  into
     "/usr/src",  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 fol-
     lowing sub-directories:

     "lib/moslib",     "sbin/setpe",     "sbin/tune",      "bin/mosrun",
     "usr.bin/mon",  "usr.bin/migrate", "usr.bin/mosctl".  ("lib/moslib"
     must be first).

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


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  net-
     worked 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 rec-
     ommended  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  net-
     work  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.

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. Pentium-MMX:
   ------------

The Pentium-MMX processor is favorably-biased and displaying  an  unusu-
ally high speed on Linux's standard speed-measurement loop - the problem
is that it does not run nearly as fast on other tasks.

MOSIX prefers to keep using the relative processor-speeds as measured by
Linux,  which are quite stable on all other processors, but for the Pen-
tium MMX, you must include the command "mosctl  setspeed  nnnn"  in  the
boot-procedure  (probably  by  editing  "/etc/rc.d.init.d/mosix"), where
"nnnn" is the real speed of the Pentium-MMX processor relative to a Pen-
tium-III at 1GHz being 10000 units.

To  find  the relative speed, enter single-user mode on your Pentium-MMX
node and run "tune_kernel" (when asked for the "other node" number,  you
may even specify your own): at some point you will see the message:

     Processor xx's speed is nnnn/10000 of a Pentium-III at 1GHz

This  is  the number you need!  (you may wish to interrupt "tune_kernel"
at this point, but in this case, type "prep_tune stop").

Now add the line "/usr/bin/mosctl setspeed nnnn" to  the  initialization
script.


This is all: reboot and enjoy MOSIX!
