openMosix Files

$Id: README,v 1.17 2003/10/22 15:10:59 mcaserta Exp $


1. CONTENT OF THE PACKAGE

The openmosix-tools includes all the userspace-tools necessary to
utilise the power of openMosix. Since version 0.2.4 this also includes
the auto-discovery daemon omdiscd, which makes the map-file
/etc/openmosix.map obsolete. Since version 0.3 the package also
includes the mps-package, which has openMosix-aware versions of ps and
top (mps and mtop), showing which node each process is running on.

The package also includes a SysV init-script that can be used to start
and stop openMosix.

We use the terms openmosix-tools and userspace-tools interchangeably:
they both refer to the same thing: this package. However, the
openmosix-tools name is the preferred one for packaging so you're more
likely to see this name floating around.


2. INSTALLATION OF PRECOMPILED RPM

When installing the openmosix-tools.rpm, the .rpm will automatically
make some changes to the system's configuration-files,
(e.g. /etc/inittab) that is necessary for openMosix to operate
properly. See the %post and %preun sections of openmosix-tools.spec
for details. The changes are undone if you decide to uninstall the
.rpm.

The automatic changes performed will prevent migration of any process
started from the system rc scripts and it's child processes, unless
specifically allowed to. The SSH daemon startup script is modified to
allow tasks started from an SSH session to migrate.

The only manual configuration needed is to edit /etc/openmosix.map to
add the machines in your cluster. Documentation and an example is
included in a skeleton /etc/openmosix.map. If you leave the map-file
without a valid configuration, the openMosix auto-discovery daemon
will be started instead. All nodes running this daemon will be
automatically configured and joined together in a common cluster.

It is strongly suggested to use the autodiscovery daemon intead of the
map file since it tends to make the file... oops, life of the sysadm 
easier :)

If you want to force autodiscovery mode even with a valid
openmosix.map file, you can edit the openmosix.config file which is
found in the /etc/openmosix directory. Just uncomment the line where
AUTODISC is and set it to 1. The autodiscovery daemon uses by default
the eth0 device but you can override that too with the AUTODISCIF
config variable.

The .rpms have been reported to work with both RedHat 7-8.x, SuSE and
Mandrake. However, for a glibc 2.1.3 system you need the
-RH73.i386.rpm while for glibc2.3 systems you need the -RH80.i386.rpm.



3. MANUAL COMPILATION

The userspace-tools are now using the GNU autotools suite thanks to
Cristiano De Michele. By the way, the defaults for the configure
script might not be the right ones for you. We also added a lot of
--with-...  config switches in order to give you the freedom of
choosing where all the files are installed. This freedom has a small
cost: you have to understand what they mean. It isn't rocket science
by the way, so don't feel scared by the above statement ;)

First of all, for the configure script not to fail you need to have
the ncurses packages/libraries and headers installed in your
system. You can easily check if you have them by looking for the
existance of the /usr/include/ncurses.h file and
/usr/lib/libncurses*.so

On any RedHat version, your should only install the ncurses-devel rpm
while on Debian you need the libncurses5-dev package. On Gentoo, your
build system (portage) will probably take care of telling you which
are the right ebuilds ;)

Then you need to have the openMosix kernel source tree. The default
location for this dir is /usr/src/linux-openmosix. It is not enough to
simply untar the vanilla kernel and patch it with openMosix: you need
to run at least

# make menuconfig

into the kernel source tree in order to have properly configured
header files for use by the userspace-tools.

Once you're done with the kernel config stuff (which you have probably
already made since you're recompiling these tools manually), it is
time to run the configure script. The following extra switches/options
can be used:

  --with-kerneldir        use specified kernel path (default is
                          /usr/src/linux-openmosix)
  --with-configdir        install openMosix config file into the specified
                          directory (default is /etc/openmosix)
  --with-sysvdir          install openMosix script in the specified directory
                          (default is /etc/init.d)
  --with-mapdir           install openMosix map file in the specified
                          directory (default is /etc)
  --with-mosrundir        install the mosrun command in the specified
                          directory (default is /bin)

These defaults should be okay for most distibutions. It is by the way
not sufficient to specify --prefix=/ to do a real install because most
distributions have very different filesystem hierarchies and it is our
hope that the LSB (Linux Standard Base) efforts and statements will be
taken in higher consideration from the distribution makers.

On a RedHat/LSB compatible system the following options should be
specified:

./configure --bindir=/bin --sbindir=/sbin --includedir=/usr/include \
            --mandir=/usr/share/man --libdir=/lib

while on a Debian system you might want to add:
            --with-configdir=/etc/defaults

The rest is part of the usual GNU/Linux mantra we all know very well:

# make
# make install

To create a tar-file for distribution, edit the version numbers in the
top-level configure.in and run "make dist". The tarfile is placed in
the same directory as the configure.in file (top dir of the
userspace-tools tree).

To create an RPM, edit Version and Release in the top-level
openmosix-tools.spec, run "make dist", then "rpmbuild -ta
openmosix-tools-....tar.gz".

During the installation, a SysV-initialisation script
(scripts/openmosix) is copied to /etc/init.d. Run "chkconfig --add
openmosix" (or the equivalent for you distribution) to activate
it. Under Debian the tool is update-rc.d while on Gentoo it is
rc-update.



4. MANUAL INSTALLATION

If you prefer to install the openMosix-tools without using the RPM,
you'll have to do some editing by yourself. Note: Even if you install
the tools with an RPM, you can still roll your own kernel, so even for
the developer there's no need to install the tools by hand. After
running "make install", you should perform the following steps:

- /etc/inittab:
  The lines that starts /etc/rc.d/rc*, /sbin/update and /sbin/shutdown
  should be changed so they're instead started with /bin/mosrun -h.
  Example:
    si::sysinit:/etc/rc.d/rc.sysinit
  should be changed to
    si::sysinit:/bin/mosrun -h /etc/rc.d/rc.sysinit
  If you installed mosrun in a directory other than /bin, please make
  sure that directory gets mounted at boot time or your system might
  not be able to find the mosrun executable while it's in the early
  init stage (which basically means that your system would hang shortly
  after the kernel starts up).
  
- /etc/rc.d/init.d/sshd
  Since now all daemons are locked from migration, all their children
  will be too. This makes all processes started from a ssh-login also
  being locked from migration. Solution: In the beginning of the
  start() function, put this line:
  test -f /proc/$$/lock && echo 0 > /proc/$$/lock

- /etc/cron.daily/slocate.cron
  You don't want slocate to look in the MFS-filesystem (if you choose
  to try that). Put mfs in there with nfs and the others.

- /etc/openmosix.map
  This file must be the same on all nodes, and tells openMosix which
  machines are part of the cluster. Each line should contain 3 fields,
  mapping IP addresses to openMosix node-numbers: 
  1) First openMosix node-number in range.
  2) IP address of the above node (or node-name from /etc/hosts).
  3) Number of nodes in this range.
  Example: 10 machines with IP 192.168.1.50 - 192.168.1.59
  1        192.168.1.50     10

- If you decide to use the auto-discovery daemon, the
  /etc/openmosix.map file is not needed. You can either remove it, or
  just comment out the configuration-lines. You can also force the use
  of the auto-discovery daemon by setting AUTODISC=1 in
  /etc/openmosix/openmosix.config



Martin Høy (martin.hoy@pvv.ntnu.no)
Mirko Caserta (mirko@mcaserta.com)