                  Installing MOSIX for Linux 2.2.16
                  ----------------------------------

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


1.   All  MOSIX  designated  computers  (nodes)  must first have Linux
     installed.  MOSIX was tested with RedHat 5.1, 5.2, 6.0, 6.1,  6.2
     and  SuSE  6.0,  6.1, 6.2, 6.3 distributions.  Although we see no
     reason why it should not work with most other Linux releases,  we
     were  already  informed  that  MOSIX  did not install properly on
     Slackware without significant hacking.  We will  appreciate  com-
     ments about installing MOSIX on other Linux releases.

2.   Obtain  and  untar  the  Linux  Kernel  sources of version 2.2.16
     (unpredictable results may occur if attempting to use  any  other
     version  of  the  Linux kernel). We recommend to untar the kernel
     sources in the directory '/usr/src/linux-2.2.16'.

3    It is highly recomended that all the nodes in the cluster run the
     same  kernel  and  MOSIX versions: occassionally, if not too many
     changes were made, MOSIX will be able to run alongside older ver-
     sions  -  but if significant changes were made between those ver-
     sions, process-migrations will be automatically disabled.

4    Always make sure that you conform to the  "minimal  requirements"
     of the particular Linux kernel version, as found in the 'Documen-
     tation/Changes' file, especially with regard to Modutils,  GNU  C
     and Binutils.

5.   There  are  two different methods to adjust a cluster of nodes so
     it can use MOSIX: The first method is  recommended  if  all  your
     nodes  have  a similar hardware configuration. In this method you
     first adjust one node, hereafter called the "MAIN" node, then you
     perform  a  "short" adjustment in the remaining nodes by skipping
     the kernel compilation.

     The second method is to adjust each node separately.

     Note that it is also possible to mix those two methods by  divid-
     ing the cluster into sub-clusters of nodes with similar hardware.

     If you selected the first method, then make sure that the  kernel
     is configured to run correctly on all relevant nodes.  It is rec-
     ommended that the kernel-sources directory on the "MAIN" node  is
     visible  to  all the other nodes, either via NFS or by copying it
     across.

5.   Although the changes to Linux files  made  by  this  installation
     script  are  reversible, we recommend that you backup your system
     before running it.  See below the  instructions  for  uninstalla-
     tion.

6    If  your  installation  contains Pentium MMX processor(s), please
     read the section on Pentium-MMX.


B. Upgrading MOSIX:
   ----------------


1.   If you upgrade your cluster from one version of MOSIX to another,
     then  you  first  need  to uninstall this package (see the "Unin-
     stall" section below), then upgrade Linux if necessary. Only then
     install  the  new  version of this package.  You must repeat this
     procedure in all the nodes of your cluster.

C. Installation - step by step:
   ---------------------------


1.   Backup your system.

2.   Untar the MOSIX-2.2.16.tar.gz file into  a  directory  where  you
     will be carrying out the installation.

          cd /tmp        (assuming unpack is done in /tmp)
          tar xzf MOSIX-2.2.16.tar.gz
     (note: do not unpack any of the resulting files).

     Then,    as    a    Super-User,    run   from   that   directory:
     "./mosix.install".  "mosix.install" will guide  you  through  the
     installation.  Alternately, you may choose to install MOSIX manu-
     ally (read the section on manual installation).

3.   To prepare a new kernel, you must have a local writable directory
     ready with the Linux-2.2.16 kernel sources.  Alternately, you may
     wish to obtain a copy from the "MAIN" node.

     If you choose to compile the kernel, the script  will  run  "make
     config"  (or  "menuconfig" or "xconfig", if you prefer), allowing
     you to configure the kernel.  Answer "Yes" for CONFIG_MOSIX, CON-
     FIG_BINFMT_ELF  and CONFIG_PROC_FS (these are also the defaults).
     It is also strongly recommended to answer "Yes"  to  CONFIG_KMOD,
     so  that  the MOSIX load-balancing module can be loaded automati-
     cally (otherwise, the automatic load-balancing  module  will  not
     start without manually running "insmod mosix").

     If  you  choose  to  obtain  a copy of the kernel from the "MAIN"
     node, the best way  to  do  so  is  by  having  the  pre-compiled
     adjusted  kernel-sources  available  online (via NFS or whatever,
     possibly even read-only).  The alternative is to bring  over  (or
     mount) a file created by the "MAIN" node installation named "ker-
     nel_files.tgz" (in the kernel  sources  directory).   As  a  last
     resort  only,  you  may ask to skip the kernel-installation, then
     copy the kernel with all its modules  manually  from  the  "MAIN"
     node.   Run "./mosix.install nokernel" to skip the kernel-instal-
     lation.

4.   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
                    - /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-adjustment changes, thus MOSIX may not run correctly.

     Changes  to  kernel  files  are logged to the "mos_uninstall.log"
     file in the kernel-source directory.

     To undo the changes of the MOSIX installation, follow the  "Unin-
     stall"  instructions  (below).  The Uninstall procedure cleans up
     only MOSIX installation changes and does not affect other changes
     made afterwards to the above configuration files.

5.   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.


D. Uninstall:
   ----------

The Uninstall procedure attempts to revert all the changes  that  were
made  during a previous MOSIX installation, as described in the previ-
ous section.

1.   To uninstall MOSIX from a node the only file you  need  from  the
     MOSIX installation package is "mosix.install".

2.   Run the command: "./mosix.install uninstall" and answer the ques-
     tions.  When asked whether to  clean  the  Linux  kernel  sources
     answer "yes" if

3.   Reboot the computer to restart plain Linux.

E. Manual Installation:
   --------------------

To  create the MOSIX kernel and module, obtain the version-2.2.16 ker-
nel sources for Linux, change to the  kernel-source  directory,  untar
the new kernel files from "{this_directory}/kernel.new.2.2.16.tar" and
patch other kernel files using:
"patch -p0 < {this_directory}/patches.2.2.16".
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.

If you want the MOSIX module to be loaded automatically, configre also
CONFIG_KMOD and run "depmod -a 2.2.16".

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 (entering
the debugger is via the <ALT-NumLock> key).

Include the resulting kernel in either "/etc/lilo.conf"  (or  whatever
other booting-system you use).
----------------------------------------------------------------------
To  obtain  the   MOSIX   manual,   untar   "manuals.tar"   into   the
/usr/local/man directory.
----------------------------------------------------------------------
To  obtain  the  user-programs,  untar  "user.tar",  preferrably  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 following
sub-directories:

"lib/moslib",    "sbin/setpe",     "sbin/tune",     "sbin/versionate",
"bin/mosrun",   "usr.bin/mon",   "usr.bin/migrate",  "usr.bin/mosctl".
("lib/moslib" must be first).
----------------------------------------------------------------------
Run  "/sbin/versionate  2.2.16-mosix"  (or "/sbin/versionate VERSION",
depending on whether or not you configured the  MOSIX_CONFIG_NOEXT  in
the  kernel) to add the particular Linux version into the MOSIX module
(the MOSIX module is kernel-version  independent,  but  "insmod"  com-
plains     when     the     kernel-version     is    not    included).
----------------------------------------------------------------------
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
alowed 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").

Some  "inet"  services  should be migratable, while others should not.
Since "inetd" itself is locked  along  with  the  other  daemons,  the
entries  in  "/etc/inetd.conf"  corresponding to those particular ser-
vices that should be allowed to migrate must  be  modified.   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

The obvious services that should be allowed to migrate are the  inter-
active  ones  that  could  result  in CPU intensive processes, such as
"telnet", "rsh", "rlogin" and "ssh"  -  the  others,  such  as  "ftp",
"talk", "time", etc.  should remain untouched.
----------------------------------------------------------------------
If you intend using 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".
----------------------------------------------------------------------
copy   the   file   "mosix.init"   to   "/etc/rc.d/init.d/mosix"   (or
"/etc/init.d", depending on the Linux installation) and make  it  exe-
cutable,  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  sim-
ply type:

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

----------------------------------------------------------------------

F. Pentium-MMX:
   ------------

The Pentium-MMX  processor  is  favourably-biased  and  displaying  an
unusually  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 pretty stable on all other processors, but for the
Pentium 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 Pentium-II at 400-MHz 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 mes-
sage:

     Processor xx's speed is nnnn/10000 of a Pentium-2 at 400MHz

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!
