			  omirr, version 0.3
			  ==================

		Andreas Luik <luik@pharao.s.bawue.de>

IN SHORT

omirr - online mirror daemon:
    duplicates directory hierarchies between serveral machines.

Installation:
    uses GNU autoconf. Therefore, after unpacking the tar file, and
    optionally installing the kernel patch, the commands "configure",
    "make" and "make install" should do it.

Usage:
    see the manual page in.omirrd(8).

Bug reports:
    using GNATS: <bugs@pharao.s.bawue.de>, category "omirr"
    otherwise: e-mail to <omirr-bugs@pharao.s.bawue.de>



WARNING

This software is still in early beta state. DO NOT USE OUTSIDE OF TEST
ENVIRONMENTS AND DO NOT USE WITH ANY USEFUL, SERIOUS OR EVEN IMPORTANT
DATA.



INTRODUCTION

The omirr package consists of the online mirror daemon in.omirrd and a
kernel patch.  The daemon supports mirroring of directory hierarchies
between several machines.  It distributes files, file contents and
file attributes to remote machines, comparable to the rdist(1)
program, but it has several differences compared to rdist.

Firstly, it synchronizes the files online, usually immediately, using
an interface to the local kernel which notifies the daemon about all
file system modifications. This results in equivalent file system
contents of the mirrored hierarchies on all machines. The daemon is
started once, usually at boot time and then runs continuously. In
contrast, the rdist program is started manually or from cron, then
distributes its files and terminates.

Secondly, it allows symmetric mirroring. With rdist, one file system
hierarchy is the master version used to update the others. The
hierarchies synchronized by in.omirrd are all treated equally,
i.e. there is no master copy. The file system modifications are
time-stamped and in.omirrd uses the latest version of each file. This
is the same as concurrently modifying the same file from two Unix
processes: the last modification takes effect. But, since in.omirrd
does not support file (or even record) locking, it should not be used
for file system hierarchies with a lot of concurrent updates on
several machines or for files usually accessed using locking
mechanisms, like database files.

Thirdly, it can synchronize several remote machines concurrently.
rdist updates multiple hosts sequentially.

When in.omirrd is started, it initializes and performs the initial
file system synchronization. Each file specified in the config file is
checked for whether it is up-to-date compared to the other servers and
updated if required. After that, in.omirrd switches to online
synchronization, processing the notifications from and sending the
kernel notifications to the remote daemons.

If an in.omirrd process terminates or its machine crashes, the daemons
on other machines continue to run. If the machine comes back and the
daemon is restarted, the file system state is brought to a consistent
state during the initial synchronization phase.

The kernel notifications are read and preprocessed by a subprocess of
in.omirrd, the so called `omirrk' subdaemon. It reads the
notifications from the kernel, trying to be as fast as possible to
avoid a ring buffer overflow in the kernel. Some of the notifications
sent by the kernel define an inode-pathname association (e.g. the
notification generated by an open(2) system call). These are saved in
an inode-to-name association cache. Other notifications indicate a
file system operation. These are sent to the in.omirrd daemon after
preprocessing. The preprocessing converts dev/ino pairs in the
notification to absolute pathnames using either an association found
in the inode-to-name cache or, if that fails, using a find(1)
subprocess. The kernel protocol is defined in such a way that using
find(1) is only required if a kernel ring buffer overflow occurred and
the file/directory was accessed before this overflow happened.



GETTING THE SOFTWARE

The latest version of omirr can be retrieved via anonymous FTP from
ftp://ftp.isa.de/pub/home/luik/omirr.  Distributions are called
"omirr-1.0.tar.gz" where "1.0" is replaced by the actual version
number. The symbolic link "omirr.tar.gz" always points to the latest
version.



PLATFORMS

The following table contains an overview of the platforms which have
been tested with the specified version of omirr.

PC x86; RedHat Linux 4.0, 2.0.11 kernel		omirr-0.3
PC x86; Linux DLD 5.01, 2.0.11 kernel		omirr-0.2
PC x86; Linux Slakware 3.0, 1.2.13 kernel	omirr-0.1
Sun SPARCstation; Solaris 2.5			omirr-0.3 [without omirrk]

Compilation of omirrd without the omirrk kernel interface should be no
problem on any POSIX.1 compatible system with Berkeley sockets. It
should also be possible, probably with some tweaking of preprocessor
symbols and function prototypes, on 4.3BSD and derived systems (like
SunOS 4.x, Ultrix 4.x).

The kernel interface is currently only implemented for the Linux 1.2.x
and 2.0.x kernels (the distribution contains patches for the 1.2.13
and 2.0.11 kernel versions, but they should be easy adaptable to other
patch levels).

The code should conform to ANSI C. It uses function prototypes, so you
need an ANSI C compliant compiler like gcc. Probably compilation with
a K&R compiler will work after unprotoizing the source, but I've not
tested it.



INSTALLATION

After unpacking the distribution (what you've probably already done
because you're reading the README file :-), perform the following
steps:

1. If you want to use the kernel interface, you need to install the
kernel patch.  The kernel interface is currently only supported on
Linux. Check the "kernel" subdirectory for a kernel patch that matches
your kernel and install it using Larry Wall's patch utility, e.g.:

	% cd /usr/src/linux
	% patch -p1 < $omirrsrc/kernel/linux-1.2.13.patch

If no patch for your kernel version is available, the modifications
should be performed by hand. Do not use a patch for a different major
kernel version (e.g. a patch for linux-1.2 for a 2.0 kernel).

After applying the patch, the kernel should be re-configured (using
"make config"). Answer "yes" to the question "Include support for
omirr online mirror". Then rebuild and install the kernel. Further
information about these tasks can be found in the README file in the
kernel source directory or in the Linux documentation.

Since the configure script for the omirrd daemon checks for the kernel
interface include file <linux/omirr.h>, the kernel patch must be
completely installed before proceeding to step 2.

2. Configure and make the daemon program. This step uses GNU autoconf
and should therefore be easy. Usually the following commands will do
it:

	% cd $omirrsrc			# chdir to omirr top directory
	% ./configure
	% make

Further information about the general features of "configure" may be
found in the file INSTALL. In addition to the environment variables
described there, the omirr configure script checks the following
environment variables:

	LOG_OMIRRD	syslog(3) facility [LOG_LOCAL7]
	PATH_VARRUN	directory for the omirrd.pid file [/var/run or /etc]

To specify, for example, another syslog facility, run configure as
follows:

	% env LOG_OMIRRD=LOG_DAEMON ./configure		# csh syntax
or	$ LOG_OMIRRD=LOG_DAEMON ./configure		# sh syntax

3. Install the daemon. Unless explicitly specified in the configure
step, this will install the daemon in /usr/local/sbin/in.omirrd and
the two manual pages in /usr/local/man/man4/omirr.4
and /usr/local/man/man8/in.omirrd.8. Since these directories are
usually not writable by regular users, perfom this step as root:

	# make install

4. Add the "omirr" service to your /etc/services file, or to your
services database in case you use a naming service like NIS (YP) or
NIS+. I'm using the TCP port 808 currently, but any other privileged
port (in the range 512 to 1023) is acceptable:

	# cat >> /etc/services << EOF
	omirr           808/tcp         omirrd          # online mirror
	EOF

5. Since omirrd logs its error messages using syslog(3),
/etc/syslog.conf should be changed to write the messages of omirrd to
a file, at least these with priorities LOG_WARNING and above. Unless
explicitly specified in step 2, in.omirrd uses the LOG_LOCAL7
facility. For example, to write the message to /var/log/omirrd, use
the following line in /etc/syslog.conf:

	# cat >> /etc/syslog.conf << EOF
	local7.warning		/var/log/omirrd
	EOF

Send a HUP signal to the syslogd process so that it re-reads its
config file.

Note that these log files will grow and should therefore be purged
periodically.

6. Write the config file /etc/omirrd.conf. This file is nearly
compatible to a stripped down version of a rdist Distfile. To
distribute a directory hierarchy to a list of servers, the following
will be fine:

	# cat > /etc/omirrd.conf << \EOF
	FILES=(...)
	HOSTS=(...)
	${FILES} -> ${HOSTS}
		install;
	EOF

For security reasons this file should be owned by "root", group "root"
(or "wheel") and should be writable only by root. It need not be
readable by anyone except root:

	# chown root /etc/omirrd.conf
	# chgrp 0 /etc/omirrd.conf
	# chmod 600 /etc/omirrd.conf

7. Test it! Before starting the server, ensure that the new kernel
built in step 1 has been booted. Then start the daemon on all machines
listed in the config file:

	# /usr/local/sbin/in.omirrd

If something does not work, check the syslog log files for errors. See
the manual page for the supported debug command line options. Feel
free to send me questions or bug reports if it still doesn't work (see
below).

8. In case it works: change your system startup configuration to
automatically restart the in.omirrd daemon during the operating system
boot, if desired. The startup scripts of today's operating systems
differ considerably. BSD-based systems perhaps still use
/etc/rc.local, System-V-based systems use a script in /etc/init.d with
links in /etc/rc2.d (or /etc/rc3.d) and /etc/rc0.d. Some Linux systems
use scripts in /etc/rc.c, and so on. I hope you know for yourself
where to add the startup command.

In case you use an init.d directory, you can use the startup script in
etc/rc.omirrd as an example. You must manually copy it to /etc/init.d,
perhaps customize it and create the links.

in.omirrd should be started after syslogd and in.named (if used), but
not much later to prevent the kernel ring buffer from overflowing
before the daemon runs.



SECURITY

Since the omirrd process runs as root and accepts commands from
sockets, it is potentially a major security problem. It should
therefore only be used between systems which are under the same
administrative control and are all equally trusted. If you've listed
some systems in /.rhosts, you can probably use in.omirrd between them
as well. If you don't want to add a system to /.rhosts, you probably
shouldn't use in.omirrd with this system, either.

omirrd currently uses a host-based authentication scheme similar to
that of other Berkeley Internet daemons like rlogind(1m). First it
checks the client's address for a reserved TCP port and aborts
otherwise. Second, it looks up the client's host name and aborts if
that fails. The host name is then checked against the hosts listed in
the server's configuration file. If it is not found, the connection is
aborted. Otherwise, the client is accepted. It can then modify all
files listed in the configuration file for that host.

This host based authentication is rather weak. A stronger
authentication scheme like Kerberos would be much better.

omirrd transfers file data in plain format and is therefore sensible
against traffic snooping. Usage of an encryption module (like SSL)
should be considered for a future release.

Last but not least, other security problems may exist in the code. The
code is very new and has not yet been specially verified with regard
to security problems or security related bugs.



USAGE

See the manual page in.omirrd(8), which should be installed during
"make install", for information on how to use omirrd, command line
options, debugging, the config file etc.

If "man in.omirrd" or "man omirrd" both do not work, check your
$MANPATH environment variable. On Solaris 2.x, "man -F in.omirrd" may
help.



BUG REPORTS

I'm grateful for success/failure stories about installing/compiling
this daemon ...

Please let me know if you find any bugs, or if you have ported it to
other machines (and care to share the changes with me and the world!).

Before you e-mail any bugs, please check the file KNOWNBUGS. If your
problem is listed there, I already know about it and you may save your
efforts.

There are two ways to send bug reports.

1. Using GNATS send-pr: in case you have GNATS installed, you can use
send-pr to send a problem report to <bugs@pharao.s.bawue.de> using a
category of "omirr". A send-pr distribution with the appropriate
categories file may be retrieved via anonymous FTP from
ftp://ftp.isa.de/pub/home/luik/omirr/send-pr.tar.gz. A full
distribution of GNATS is available from the usual GNU ftp sites, in
case you are interested.

2. Without GNATS: send a regular e-mail to <omirr-bugs@pharao.s.bawue.de>.

In either case, please ensure to include the following information
that will help me analyze your bug report:

1. The version of omirr you use (try "in.omirrd -V" to determine it)
2. Machine and operating system type and version
3. How the daemon was started (command line flags, etc.)
4. The configuration used (/etc/omirrd.conf)
5. What in fact went wrong? What happened and how did that differ from
what you expected to happen? Check the syslog file for any useful
error messages. If the daemon crashed with a core dump, try to get a
traceback using your favorite debugger.

In short: include any information that may be useful to reproduce or
track down the problem.



LICENSE/LEGALESE

This program is Copyright (C) 1996-1997 by Andreas Luik and may be copied
and used only under the terms of the GNU General Public License as
published by the Free Software Foundation. See the file COPYING for
details. Some of the source files are based on or copied from BSD
source. For these files the Copyrights of The Regents of the
University of California apply. See the file COPYING.BSD for details.


Andreas Luik <luik@pharao.s.bawue.de>
16-Jan-97

