mmsnfs aka. netfs - Multicasting Master-Slave Fileystem 
   Copyright (C) 2003-2004 Szymon Acedanski


Network technology evolves quickly, but available bandwidths are still
not sufficient for fast transfers of big files to a bunch of clients
(for example populating operating systems' installation images).
Multicasting Master-Slave Network Filesystem (mmsnfs) is a new method
of distributing entire filesystem among several client-machines
simultaneously and efficiently. Moreover it provides mechanisms for
modifying distibuted filesystem structure reliably and securing it
against introducing inconsistencies. It is designed to be used in
small networks of similarly-configured machines, for instance
university labs or internet cafes.


Installation
------------

To create and manage mmsnfs filesystems you need mmsnfs-utils package.
Current modules are compatible with mmsnfs-utils version 0.7a. It's
not guaranteed, that future releases will match. Utilities can be
obtained from <http://www.sourceforge.net/projects/mmsnfs/>.

To install mmsnfs kernel modules you need Linux 2.6 kernel with its
source tree. Make sure, that there is symlink /lib/modules/<kernel
version>/build pointing to this source tree.

If you would like to build modules matching your running kernel, just
run 'make' and these modules will be built _and_installed_ without any
questions.

To build for some other kernel version, run 'make UNAME=<version>'.


Master and slave nodes
----------------------

Refer to <http://mmsnfs.sourceforge.net/documentation/dov/node5.html>.

In short: master files and directories are read-only on client
machines and are always synchronized with server. Slave files can be
modified by clients, their new content is stored in cache, byt
modified slave files are no more synced with server.


Implemetation design
--------------------

Mmsnbfs filesystem consist of several kernel modules. One core module
called 'netfs' and several cahcing policies.

'dummyc' caching policy:
	it's very simple no-op caching policy, which can be used only as
	policy for client machines. It can be used, if no caching is
	requested.

'diskc' caching policy:
	it's just a normal filesystem implementation, which can be used
	as standalone filesystem, network server filesystem, which is then
	populated among clients, or as an additional cache for clients.
	It's needed for support of modifiable slave files


Modules parameters
------------------

netfs_no_debug
	turn off debugging output (recommended)

netfsd_hostid
	assign arbitrarily specified host identifier. Every host in
	mmsnfs-ed network must have unique host identifier (regardless of
	its IP). If this option is not specified, hostid is generated
	randomly when needed.

netfsd_min_reqds
	minimum number of requests handling kernel threads

netfsd_max_reqds
	maximum number of requests handling kernel threads

netfsd_multiaddr
	multicast address used for transferring mmsnfs protocol packets.
	If not specified, broadcast address 255.255.255.255 is used.
	Default interface is used for communication (ie. this one, out of
	which your default route points).

netfsd_localaddr
	local address to bind to. If not specified, your default IP
	matching outgoing interface is chosen.

netfsd_multiif
	interface number for outgoing multicast traffic. Look at output of
	'ip link' for appropriate number.

netfsd_multittl
	multicast packets TTL (time-to-live). Setting it to 1 ensures no
	packet will go outside your local network.


Mounting
--------

Please refer to mmsnfs-utils package documentations for instructions
regarding creating mmsnfs filesystems.

Supported mount parameters:

cache
	caching policy ('diskc' or 'dummyc')

server
	act as server instance.

client
	act as client instance. Specifying both server and client causes
	unspecified behaviour.

mntid
	unique mount id to serve (SVR mode) or to join (CLI mode). Can be
	omitted if you specify mntname.

mntname
	user-friendly mount name. Optional.

svrid (CLI only)
	host identifier of server machine. Normally, it's determined
	automatically.

liveupd (SVR only)
	push all changed to clients immediately when in edit-mode.

editmode (SVR only)
	enter edit-mode at mount, enable changing filesystem. Not
	recommended, please use netfs

evict (CLI only)
	enables eviction mechanisms, which should be used when cache size
	is less than total filesystem size. This enables replacement of
	old content. It's highly experimental and may cause deadlocks.
	Supported only by 'diskc' caching policy.

dontwait (CLI only)
	never wait for server when it's unreachable. Mmsnfs default
	behaviour is to forcibly wait for server when no data (even
	cached) is available for some file/directory. Passing tis option
	causes mmsnfs to fail with IO error in such cases.

svrtimeout (CLI only)
	amount of time (arbitrary units, see include/linux/netfs_fs.h,
	NETFS_POLLD_INTERVAL) after which netfs instance enters detached
	mode when no server reachable.

sleepevery (CLI only)
	force 'updater' process to sleep every this many requests
	processed.

sleeptime (CLI only)
	force 'updater' to sleep this many jiffies.

noupdate (CLI only)
	never run 'updater', useful with 'dummyc' caching policy.


Examples:

mount -o loop,liveupd,mntid=3,server,mntname=test,cache=diskc \
	-t netfs bigfs1 foo

mount -o loop,mntid=3,client,cache=diskc \
	-t netfs pfs2 bar


Reporting bugs
--------------

All observed bugs/problems and feature requests please direct to me
using SourceForge <http://sourceforge.net/tracker/?group_id=99790>.
Don't hesitate to contact me privately on
<mailto:accek@poczta.gazeta.pl> if you have problems with this
software. But before doing that, please review all revealant
documentation.

Please refer to REPORTING-BUGS included with your kernel tree source
when reporting bugs.


Author
------

Szymon Acedanski
ul. Sloneczna 81D/1
40-136 Katowice, POLAND
phone: +48 506 202715
email: accek@poczta.gazeta.pl


# vim:tw=70