================ ABOUT DAZUKOFS ================ DazukoFS is a stackable filesystem to allow 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.32 kernel. You may need to manually adjust the Makefile if you kernel sources are not in the default location. (Patches are provided for various other kernels. See the section below titled "PATCHING" for more information.) 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 ========== PATCHING ========== In the "patches" directory there are patches available to modify the DazukoFS code to fit various other kernels. For example, if you are running openSUSE 11.1 you can patch the code with the following command: $ patch -p1 < patches/patch-opensuse-11.1 There should not be any errors. If there are errors, then the patch is broken and should be reported on the dazuko-devel mailing list. Once the code has been patched you can build the kernel module as described in the section "BUILD / INSTALL" above. ========= 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. Attempting to mmap files as read-write will result in an error. Applications typically handle this by falling back to regular I/O. Read-only memory mapping is supported by DazukoFS. - 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 ======================= DAZUKOFS APPLICATIONS ======================= This last section is meant for developers of DazukoFS applications. This section will discuss the methods used for interacting with DazukoFS in order to perform online file access control. Although this section describes the low-level communication between application and kernel, be aware that a userspace library libdazukofs exists that has already implemented this communication. Using the library makes it very easy to write applications for DazukoFS. The library can be found on the Dazuko website: http://www.dazuko.org An application can register itself to receive notification about DazukoFS file access events. The application then also has the authority to block the file access. DazukoFS supports multiple groups. A group is a set of registered processes that work together. For each file access event, only one of the registered processes of a group will be notified. By registering multiple processes within the same group, an application will be able to perform file access control for multiple files simultaneously. A list of registered groups can be seen by reading from the /dev/dazukofs.ctrl device. For example: 0:Group_A 1:Group_B This means that the group named "Group_A" has been assigned the group id 0 and the group name "Group_B" has been assigned the group id 1. Groups can be added by writing to the /dev/dazukofs.ctrl device. For example, writing: add=My_New_Group will create a new group, which will be assigned an available group id. The creation of the group should be verified by reading from the /dev/dazukofs.ctrl device. This is also necessary to see which group id was assigned to the new group. 0:Group_A 1:Group_B 2:My_New_Group The new group "My_New_Group" has been assigned the group id 2. Group names are restricted to the characters: a-z A-Z 0-9 - _ Each group has their own device /dev/dazukofs.N in order to interact with DazukoFS (where 'N' is the group id). For "My_New_Group" we are assigned /dev/dazukofs.2 to use. By opening the device /dev/dazukofs.N an application has registered itself. A read on the device will block until a file access event on DazukoFS has taken place. When a file access event has occured, the read will return with information about the file access event. For example: id=11 fd=4 pid=3226 This means that the particular file access event has been given the id 11. The file descriptor 4 has been opened for the registered process. This file descriptor allows the registered process read-only access to the file being accessed. The pid of the accessing process is 3226. Using this information, the registered application must determine if the access should be denied or allowed. The application must then respond with an answer. This is done by writing to the device: id=11 r=0 "r" is the response. A value of 0 means to allow the access. A value of 1 means to deny the access. IMPORTANT: The application is responsible for closing the file descriptor that was opened by DazukoFS. Since DazukoFS will open the file being accessed, the registered process only requires read/write permissions to the device in order to perform online file access control. The file is opened even if the registered application normally would not have access to the file. This allows an unprivileged process to perform file access control for any file on the system. By closing the device, the application will unregister itself. To provide crash protection for applications, groups can be added using the "addtrack" keyword instead of "add". The keyword "addtrack" tells DazukoFS to add the group and track the number of registered processes in that group. Tracking begins as soon as the first process has registered with DazukoFS. Once all processes of the group have unregistered, DazukoFS will automatically delete the group. If an application crashes, is killed, or ends without closing the device, DazukoFS will still unregister that process. Using "addtrack" will ensure that a created group is automatically deleted if the application is not able to shutdown in a clean manner. NOTE: If "addtrack" is used, it is necessary for the device to be kept open the entire time the application is performing online file access control. Otherwise the group may become unintentionally deleted. If "add" is used, it is not necessary for the device to be kept open while the application decides if access should be allowed. Actually, DazukoFS doesn't care which process responds to a file access event. DazukoFS is only interested in a response for the given event id. A group can be deleted by writing to the /dev/dazukofs.ctrl device. For example, writing: del=My_New_Group When a group is deleted, any processes registered with that group will be interrupted. Further reads on /dev/dazukofs.N will result in an error (until some other group has been assigned that group id). The deletion of the group should be verified by reading from the /dev/dazukofs.ctrl device. 0:Group_A 1:Group_B If no groups have been added, DazukoFS will allow all file access events. If, however, at least one group is added, DazukoFS will expect one process from each group to handle every file access event. Even if no processes are registered but one or more groups exist, DazukoFS will still wait for file access events to be handled by each group. For this reason it is important that an application deletes a group it has created, once it should no longer perform online file access control. All processes on the system that try to access files on a DazukoFS mount will require authorization (if at least one group exists). This is also true for registered process that try to access files on a DazukoFS mount. IMPORTANT: If registered processes access files on a DazukoFS mount, they will cause new file access events that must be authorized. This could lead to deadlock if not properly considered. Since the registered process receives an open file descriptor to the file being accessed, there should be no need for that process to open other files. However, if the process must open additional files (and these files potentially lie on a DazukoFS mount), it is possible for processes to hide themselves from DazukoFS. By opening the /dev/dazukofs.ign device, a process will be ignored by DazukoFS. It does not matter if the process is registered or not. No data must be written or read from the device. It simply needs to be opened. WARNING: Make sure the permissions for /dev/dazukofs.ign are securely set. Otherwise, any process could potentially hide itself. As soon as the /dev/dazukofs.ign device is closed, the process is no longer hidden.