in.omirrd(8)

NAME

in.omirrd, omirrd - online file system mirror daemon

SYNOPSIS

in.omirrd [ -b ] [ -c ] [ -d [facilities] ] [ -oopts ] [ -f configfile ]

in.omirrd [ -V ]

in.omirrd [ --help ]

DESCRIPTION

in.omirrd is a daemon that mirrors and synchronizes directory hierarchies between several machines. It distributes files, file contents and file attributes to remote machines, comparable to the rdist(1) program.

in.omirrd usually uses its interface to the kernel of the local machine to receive notifications about file system state modifications. This allows the daemon to synchronize the hierarchies on the remote machines online, usually immediately.

in.omirrd allows symmetric mirroring, so you don't need to define the file system of one machine as the master version. Instead, all instances of the file system hierarchies on the different hosts are treated equally. 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.

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 the kernel and sending them to the remote daemons. The remote daemons use the notifications to update the state of their local filesystems.

OPTIONS

-b

Set kernel omirr module to blocking mode. This prevents kernel ring buffer overflows because if the ring buffer is full, the kernel puts the process to sleep that generates the new log message. It is woken up when the ring buffer has enough space again, i.e. after in.omirrd has read some messages.

-c

Clear the kernel ring buffer containing the file system log after open of the kernel omirr log device (e.g. /proc/omirr on Linux) and before starting the initial update phase.

-d

Set debugging mode. Debugging mode prevents the daemon from going into background and releasing the controlling terminal. It stays in the foreground instead.

-d facilities

In addition to setting debugging mode, enable debugging messages for the comma separated list of facilities. The current facilities are:

cf

display debugging messages about config file parsing and data structures.

config

same as cf

conn

display debugging messages about the socket connections to other slave servers.

daemon

display general debugging messages, e.g. about the process structure.

dprot

log the protocol messages between master and slave daemon. These notifications are filtered according to the config file specifications.

iname

display debugging messages of the inode-to-name cache and inode-to-name resolver.

kprot

log the protocol messages between the kernel and the omirrk sub-daemon. These are the raw notifications.

op

log the file system operations performed by the slave daemon.

prot

log the protocol messages between the omirrk sub-daemon and the master. These notifications display pathnames resolved from inodes.

sock

display debugging messages of the socket module.

Note that this option is only available if in.omirrd was compiled with the DEBUG symbol defined.

-o opts

Specify the file system synchronization options to enable or disable. opts is a comma-separated list of options. Legal values are:

whole

Whole mode. The whole file name is appended to the destination directory name. Normally, only the last component of a name is used when renaming files. This will preserve the directory structure of the files being copied instead of flattening the directory structure. For example, distributing a list of files such as /path/dir1/f1 and /path/dir2/f2 to /tmp/dir would create files /tmp/dir/path/dir1/f1 and /tmp/dir/path/dir2/f2 instead of /tmp/dir/dir1/f1 and /tmp/dir/dir2/f2.

nowhole (default)

Disables whole mode. See description of whole.

numchkgroup

Use the numeric group id (gid) to check and set group ownership instead of the group name.

nonumchkgroup (default)

Use the group name to check and set group ownership. If the group name is not found on a remote machine, a warning is logged and the numeric value is used.

numchkowner

Use the numeric user id (uid) to check and set ownership instead of the user name.

nonumchkowner (default)

Use the user name to check and set ownership. If the user name is not found on a remote machine, an warning is logged and the numeric value is used.

-f configfile

Use configfile as the config file. The default file name is /etc/omirrd.conf.

-V

Print current version number to stdout and exit.

--help

Print long usage message including the GNU-specific long word options to stdout and exit.

CONFIG FILE

The configuration file contains a sequence of entries that specify the files or directories to be synchronized, the destination hosts, and what operations to perform to do the updating. Each entry has one of the following formats:

<variable name> `=' <name list>
[ label: ] <source list> `->' <destination list> <command list>

The first format is used for defining variables. The second format is used for distributing files to other hosts. The source list specifies a list of files and/or directories on the local host which are to be synchronized. The destination list is the list of hosts to which these files are to be copied if they are out-of-date relative to the local version.

Labels are optional. Currently they are not used, but they are provided for compatibility with rdist(1) distfiles.

Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with `#' and end with a newline.

Variables to be expanded begin with `$' followed by one character or a name enclosed in curly braces (see the example, below).

The source and destination lists have the following format:

<name>
or
`(' <zero or more names separated by white-space> `)'

The source list must consist of a list of absolute pathnames. The shell meta characters `[', `]', `*', and `?' are recognized and expanded in the source list the same way as sh(1) does. They can be escaped with a backslash. Note that the `~' character is not expanded.

The destination list consists of a list of hostnames or dotted-quad IP addresses of hosts to be synchronized. The hostname of the system in.omirrd is running on can be added to the list but it will be ignored. The same config file may therefore be used on all machines. If a host appears on several destination lists, be sure to use the identical name on every list because otherwise connecting to the second and following instances will fail.

The command list consists of zero or more commands of the following format.

`install'	<options>	opt_dest_name `;'
`except'	<name list>	`;'

The install command is used to synchronize out of date files and/or directories. Each source file is copied to every host on the destination list. Directories are recursively copied in the same way. Opt_dest_name is an optional parameter to rename files. If no install command appears on the command list or the destination name is not specified, the source file name is used. Directories in the path name will be created if they do not exist on the remote host. The -o opts option as specified in the OPTIONS, section, above, has the same semantics as on the command line except they only apply to the files on the source list.

The except command is used to update all of the files on the source list except for the files listed on name list. This is usually used to synchronize everything in a directory except certain files.

The following is a small example for a config file to be used on both hosts to be synchronized.

HOSTS = ( mars venus )
FTP = ( /ftp/pub /ftp/local )
EXCEPT = ( /ftp/pub/newsarchive )
MUSERS = ( /export/users/s* )
VUSERS = ( /export/home/s* )
EXUSERS = ( smith )
${FTP} -> ${HOSTS}
	install ;
	except ${EXCEPT} ;
${MUSERS} -> ( venus )
	install -onowhole /export/home ;
	except /export/users/${EXUSERS} ;
${VUSERS} -> ( mars )
	install -onowhole /export/users ;
	except /export/home/${EXUSERS} ;

FILES

/etc/omirrd.conf

default config file, may be changed with -f option

/var/run/omirrd.pid (or /etc/omirrd.pid)

the process ID and command line used to start the daemon

/var/tmp/omirrd.run

debug output generated by SIGUSR2

/proc/omirr

interface to kernel to receive kernel notifications from (Linux only)

SEE ALSO

rdist(1), sh(1), omirr(4)

DIAGNOSTICS

The command line is parsed with GNU getopt(3). Any command line errors are printed to stderr and the program terminates.

After the daemon has moved into the background, error messages are logged via the syslog(3) mechanism, using the local7 facility, unless that was changed during compilation. If the -d option is used, these errors are also written to stderr.

WARNINGS

Since the omirrd process runs as root and accepts commands from sockets, it is potentially a major security problem. Check the README file in the source distribution for further information about security-related problems.

The superuser does not have its accustomed access privileges on NFS-mounted file systems. Using in.omirrd to copy to such a file system may fail, or the copies may be owned by the user “nobody”.

NOTES

The following signals have the specified effect when sent to the server process using the kill(1) command.

SIGHUP

Re-reads the config file, usually /etc/omirrd.conf, terminates connections to hosts removed from the config file and connects or reconnects to the hosts no connection was established yet.

SIGTERM

Terminates the in.omirrd daemon process and omirrk subprocess gracefully.

SIGUSR2

Dumps debug and status information to /var/tmp/omirrd.run provided that in.omirrd was compiled with the DEBUG symbol defined.

BUGS

See the file KNOWNBUGS in the omirr source distribution. This manual page section will be updated after beta-test.

AUTHOR

Andreas Luik <[email protected]>