| |||||||||||||
Documentation/filesystems/dazukofs.txt
================
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.
=====================
MOUNTING/UNMOUNTING
=====================
DazukoFS is typically mounted on top of an existing directory. For example,
to stack DazukoFS on top of the /opt directory, the following mount(8)
command can be given:
# mount -t dazukofs /opt /opt
A process that accesses files in /opt will now be accessing them through
DazukoFS. Such file access events will be detected by a process that is
registered with DazukoFS. That process can then choose to allow or deny
the access.
IMPORTANT: Initially, DazukoFS will allow all file access events to occur
until an application registers to perform file access control.
Once an application has registered with DazukoFS, all file access
events must be authorized by the registered application.
The stackable filesystem can then be unmounted with:
# umount /opt
===============
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
=========
WARNING
=========
It is possible to mount DazukoFS to a directory other than the directory
that is being stacked upon. For example:
# mount -t dazukofs /opt /mnt
When accessing files within /mnt, you will be accessing files in /opt
(through DazukoFS). When accessing files directly in /opt, DazukoFS will not
be involved.
THIS HAS POTENTIAL PROBLEMS!
If files are modified directly in /opt, 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 /opt is modified ONLY through
DazukoFS (i.e. through /mnt), there should not be any problems.
This method of mounting DazukoFS may be interesting for servers that export
a part of the filesystem and the exporting service is within a chroot
environment.
==============
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
=======================
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.
(Log in to post comments)
|
|||||||||||||