================
 ABOUT DAZUKOFS
================

DazukoFS is a stackable filesystem that provides a mechanism for userspace
applications to perform online file access control. It was originally
developed to support online virus scanners, but could be useful for any
application that wishes to perform online file access control.

NOTE: DazukoFS is completely separate from Dazuko. DazukoFS uses a
      different interface and different devices than Dazuko. It is
      possible to use Dazuko and DazukoFS at the same time since
      they do not share any code or resources. However, DazukoFS
      is meant to replace Dazuko as an online file access control
      solution.



=================
 BUILD / INSTALL
=================

Below are brief instructions to get DazukoFS compiled and running on a
system with a Linux 2.6.27 kernel. You may need to manually adjust the
Makefile if you kernel sources are not in the default location.
(A patch is provided to convert the DazukoFS code to support Linux
2.6.26.)

compile the kernel module
  # make

install the kernel module
  # make dazukofs_install

load the kernel module
  # modprobe dazukofs

verify that the module is loaded
  # dmesg | grep dazukofs

create a playground to test DazukoFS
  # mkdir /tmp/dazukofs_test

mount DazukoFS over the playground
  # mount -t dazukofs /tmp/dazukofs_test /tmp/dazukofs_test

verify that DazukoFS is mounted
  # mount | grep dazukofs

unmount DazukoFS
  # umount /tmp/dazukofs_test



=========
 TESTING
=========

A test application is provided. The test application simply prints out the
online file access information that is captured by DazukoFS. Below are
brief instructions to perform the test.

make sure the DazukoFS kernel module is loaded
  # modprobe dazukofs

create a playground to test DazukoFS
  # mkdir /tmp/dazukofs_test

mount DazukoFS over the playground
  # mount -t dazukofs /tmp/dazukofs_test /tmp/dazukofs_test

copy some test files to the playground
  # cp /bin/* /tmp/dazukofs_test

build the test program
  # cd test
  # make

start the test program
  # env LD_LIBRARY_PATH=lib ./showfiles

open another terminal and access files in the playground
  $ find /tmp/dazukofs_test -type f | xargs file

In the first terminal, the "showfiles" program should be showing the
accessed files. You can end the test program by pressing CTRL-C.

NOTE: The /proc filesystem must be mounted in order for the "showfiles"
      program to display the file names.



===============
 MOUNT ON BOOT
===============

You may want DazukoFS to be mounted over certain directories when the
machine boots. The easiest way to do this is to add the mounts to
the end of /etc/fstab. They would look something like this:

/usr   /usr   dazukofs   defaults   0   0
/opt   /opt   dazukofs   defaults   0   0

Of course, the dazukofs module must be loaded in order for this to work.
Consult the documentation of your distribution to learn how to automatically
load specific kernel modules on boot.



=========
 WARNING
=========

It is possible to mount DazukoFS to a directory other than the directory
that is being stacked upon. For example:

# mount -t dazukofs /usr/local/games /tmp/dazukofs_test

When accessing files within /tmp/dazukofs_test, you will be accessing
files in /usr/local/games (through dazukofs). When accessing files directly
in /usr/local/games, dazukofs will not be involved (and will not detect
the file access).

THIS HAS POTENTIAL PROBLEMS!

If files are modified directly in /usr/local/games, the dazukofs layer
will not know about it. When dazukofs later tries to access those files,
it may result in corrupt data or kernel crashes. As long as
/usr/local/games is ONLY modified through dazukofs, there should not be
any problems.



==============
 KNOWN ISSUES
==============

- DazukoFS does not support writing to memory mapped files. This should not
  cause the kernel to crash, but will instead result in the application
  failing to perform the writes (although mmap() will appear to be
  successful from the application's viewpoint!).

- It is not possible to stack DazukoFS over the root filesystem (/).
  Stacking over pseudo filesystems (/proc, /dev, /sys) has not been
  tested and should be avoided.

Please report problems to the dazuko-devel mailing list
(subscription required):
     http://lists.nongnu.org/mailman/listinfo/dazuko-devel
