Installation HOWTO
(changed note to mention that the instructions may be outdated) |
(add local lib to library path for showfiles example) |
||
| (3 intermediate revisions by one user not shown) | |||
| Line 1: | Line 1: | ||
__NOTOC__ |
__NOTOC__ |
||
| − | There are 5 steps to compiling and installing Dazuko. However, you should have some experience with compiling your kernel. If you do not have this experience, it is suggested that you refer to the various available handbooks to learn about the kernel building process. Building your own kernel not only allows your system to run optimally, but also gives you a chance to work with and get a feel for the heart of your operating system. |
+ | This page briefly outlines 5 steps to compiling and installing DazukoFS. If you do not have experience compiling kernel modules or working with stackable filesystems, it is recommended that you first read through the DazukoFS documentation before installing DazukoFS. |
<div style="padding:0.5em; margin-bottom:1em; border: 2px solid #a00;"> |
<div style="padding:0.5em; margin-bottom:1em; border: 2px solid #a00;"> |
||
| − | These instructions are based on the kernel module download package. However, the kernel module package does not support recent Linux kernels. If you have a recent Linux kernel, please read the README from the [[Downloads]] page of the correct download for your Linux kernel version instead. |
+ | The information on this page refers to DazukoFS 3.x versions. Information about installing Dazuko 2.x can be found on the page [[Installation HOWTO %28Dazuko 2.x%29]]. |
</div> |
</div> |
||
| Line 10: | Line 10: | ||
== Step 1: Get your kernel source code == |
== Step 1: Get your kernel source code == |
||
| − | Dazuko is a kernel module. Once a kernel module is loaded, it becomes one with your kernel. Therefore, Dazuko will call and share the same set of functions as the kernel. This is why the kernel source code is required in order to build Dazuko. |
+ | DazukoFS is available as a kernel module. Once a kernel module is loaded it becomes one with your kernel, calling and sharing the same set of functions as the kernel. This is why the kernel source code is required in order to build DazukoFS. |
| − | |||
| − | It is highly recommended that you first build and install a kernel. Then it is certain that the kernel source code you use to build Dazuko matches the running kernel. If you do not know how to do this, read the opening paragraph above. |
||
Many distributions provide packages with the kernel source code. If you do not plan on building a new kernel, make sure you install the proper kernel source packages for your distribution. |
Many distributions provide packages with the kernel source code. If you do not plan on building a new kernel, make sure you install the proper kernel source packages for your distribution. |
||
| − | ''Linux:'' See [http://dazuko.dnsalias.org/wiki/index.php/FAQ#How_do_I_configure_my_Linux_kernel_source_code.3F FAQ] for information about configuring your Linux kernel source code. |
+ | == Step 2: Compile DazukoFS == |
| − | == Step 2: Compile Dazuko == |
+ | DazukoFS was written to work with a particular kernel version. Refer to the README included in the package to see which version it was written for. In order to support other kernel versions, various patches have been included in the package. If DazukoFS was not written for your running kernel, a patch may be available to modify DazukoFS code for your kernel. |
| − | Once the source code for your running kernel is available, you can build Dazuko. First a Makefile must be generated by running: |
+ | As an example, to patch the DazukoFS code to support the openSUSE 11.1 kernel, you would give the command: |
| − | $ ./configure |
+ | $ patch -p1 < patches/patch-opensuse-11.1 |
| − | This will determine what kind of system you have and any special flags that need to be set. Then you can compile Dazuko with: |
+ | Once the DazukoFS code has been patched (if it was necessary to do so), you can compile DazukoFS with: |
$ make |
$ make |
||
| − | This will create the device driver as well as a couple example programs. Under Linux 2.2-2.4 the device driver is named dazuko.o. Under Linux 2.6 and FreeBSD it is named dazuko.ko. |
+ | You may need to manually edit the Makefile to specify where your kernel sources are located if they are not in the default location. |
| − | You can perform a quick test to see if the device driver is compatible with your kernel using this command (as root): |
+ | Please read over the [[FAQ]] if you encounter problems. |
| − | # make test |
+ | == Step 3: Insert DazukoFS == |
| − | This will try to insert and remove the kernel module. |
+ | Once you have successfully compiled DazukoFS, the final step is to insert the module into the kernel. To do this, you must have root priveledges. This can be done with the command: |
| − | If you get any warnings or errors from any of the steps above, something may not be correct. Please read over the [[FAQ]] if you encounter problems. |
+ | # /sbin/insmod dazukofs.ko |
| − | == Step 3: Insert Dazuko == |
+ | If you don't get any messages, this is a good sign. To verify that the module has been loaded correctly, type: |
| − | Once you have successfully compiled Dazuko, the final step is to insert the module into the kernel. To do this, you must have root priveledges. This can be done with the command: |
+ | $ cat /proc/filesystems | grep dazukofs |
| − | Linux 2.2-2.4: |
+ | If you see "dazukofs" then the DazukoFS driver has been successfully loaded. |
| − | # /sbin/insmod dazuko.o |
||
| − | Linux 2.6: |
+ | == Step 4: Test DazukoFS == |
| − | # /sbin/insmod dazuko.ko |
||
| − | FreeBSD: |
+ | File access contol is only possible on directory trees where DazukoFS has been mounted. To test DazukoFS, you can create a test directory and mount DazukoFS on top of it. You will need to be root in order to perform the mount: |
| − | # /sbin/kldload dazuko.ko |
||
| − | If you don't get any messages, this is a good sign. To check if the module has been loaded type: |
+ | # mkdir /tmp/testmnt |
| + | # mount -t dazukofs /tmp/testmnt /tmp/testmnt |
||
| − | Linux 2.2-2.6 |
+ | Once a DazukoFS mount exists, an application is able to handle file access control on that mount. To test DazukoFS, you can try out the test program (showfiles) included in the test subdirectory. You can build the test program with: |
| − | $ cat /proc/modules |
||
| − | FreeBSD |
+ | $ cd test |
| − | $ /sbin/kldstat |
+ | $ make |
| − | If you see "dazuko" listed then the Dazuko driver has been successfully loaded. Unless you are using devfs, the device node must now be created. With devfs, device nodes are created automatically. |
+ | By default DazukoFS will only operate with processes that are running as root. Therefore you need to be root when you run the test program. |
| − | |||
| − | Under Linux the device major number for Dazuko must be found. This is done with: |
||
| − | $ cat /proc/devices |
||
| − | |||
| − | You should see "dazuko" listed along with its device major number (usually 254). For example purposes, I will assume this number is 254. The commands to create the device node are: |
||
| − | |||
| − | # mknod -m 600 /dev/dazuko c 254 0 |
||
| − | # chown root:root /dev/dazuko |
||
| − | |||
| − | Under FreeBSD 4 |
||
| − | # mknod /dev/dazuko c 33 0 |
||
| − | |||
| − | == Step 4: Test Dazuko == |
||
| − | |||
| − | So you've got Dazuko compiled and inserted into your kernel. Now what? |
||
| − | |||
| − | Once Dazuko is loaded, an application is able to handle file access control through the Dazuko device. To test Dazuko it is recommended that you try out the example program included (in the example_c subdirectory). You can build the example program with: |
||
| − | |||
| − | $ cd example_c |
||
| − | $ make |
||
| − | For security reasons Dazuko will only operate with processes that are running as root. Therefore you need to be root when you run the example program. The example program takes a list of paths to "watch" as arguments. |
+ | # env LD_LIBRARY_PATH=lib ./showfiles |
| − | # ./example /home /usr/home |
+ | Once the test program is running, open up another terminal or shell. Create some file within the /tmp/testmnt directory. As files are accessed, the test program should output various information. The test program always permits the accesses, however another application could be written that denies file accesses in certain conditions. |
| − | Once the example program is running, open up another terminal or shell. Open up some file within the /home directory (or any subdirectory thereof). As the files are accessed, the example program should output various information. |
+ | The test program can be ended by hitting Ctrl-C. The DazukoFS filesystem can be unmounted with: |
| − | The example program always permits the accesses, however another application could be written that denies file accesses in certain conditions. This allows a 3rd party to write complex file access control schemes (or customized file access logging utilities). |
+ | # umount /tmp/testmnt |
| − | == Step 5: Install Dazuko == |
+ | == Step 5: Install DazukoFS == |
| − | After you have verified that Dazuko correctly works on your system, you will probably want to install it on the system (so that it is easily available). From the original Dazuko source code directory (not the example_c directory) you can run (as root): |
+ | After you have verified that DazukoFS works correctly on your system, you will probably want to install it on the system (so that it is easily available). From the original DazukoFS source code directory (not the test directory) you can run (as root): |
| − | # make install |
+ | # make dazukofs_install |
| − | This performs the necessary actions to install the Dazuko device driver to your system. |
+ | This performs the necessary actions to install the DazukoFS device driver to your system. |
Latest revision as of 14:47, 17 October 2010
This page briefly outlines 5 steps to compiling and installing DazukoFS. If you do not have experience compiling kernel modules or working with stackable filesystems, it is recommended that you first read through the DazukoFS documentation before installing DazukoFS.
The information on this page refers to DazukoFS 3.x versions. Information about installing Dazuko 2.x can be found on the page Installation HOWTO (Dazuko 2.x).
[edit] Step 1: Get your kernel source code
DazukoFS is available as a kernel module. Once a kernel module is loaded it becomes one with your kernel, calling and sharing the same set of functions as the kernel. This is why the kernel source code is required in order to build DazukoFS.
Many distributions provide packages with the kernel source code. If you do not plan on building a new kernel, make sure you install the proper kernel source packages for your distribution.
[edit] Step 2: Compile DazukoFS
DazukoFS was written to work with a particular kernel version. Refer to the README included in the package to see which version it was written for. In order to support other kernel versions, various patches have been included in the package. If DazukoFS was not written for your running kernel, a patch may be available to modify DazukoFS code for your kernel.
As an example, to patch the DazukoFS code to support the openSUSE 11.1 kernel, you would give the command:
$ patch -p1 < patches/patch-opensuse-11.1
Once the DazukoFS code has been patched (if it was necessary to do so), you can compile DazukoFS with:
$ make
You may need to manually edit the Makefile to specify where your kernel sources are located if they are not in the default location.
Please read over the FAQ if you encounter problems.
[edit] Step 3: Insert DazukoFS
Once you have successfully compiled DazukoFS, the final step is to insert the module into the kernel. To do this, you must have root priveledges. This can be done with the command:
# /sbin/insmod dazukofs.ko
If you don't get any messages, this is a good sign. To verify that the module has been loaded correctly, type:
$ cat /proc/filesystems | grep dazukofs
If you see "dazukofs" then the DazukoFS driver has been successfully loaded.
[edit] Step 4: Test DazukoFS
File access contol is only possible on directory trees where DazukoFS has been mounted. To test DazukoFS, you can create a test directory and mount DazukoFS on top of it. You will need to be root in order to perform the mount:
# mkdir /tmp/testmnt # mount -t dazukofs /tmp/testmnt /tmp/testmnt
Once a DazukoFS mount exists, an application is able to handle file access control on that mount. To test DazukoFS, you can try out the test program (showfiles) included in the test subdirectory. You can build the test program with:
$ cd test $ make
By default DazukoFS will only operate with processes that are running as root. Therefore you need to be root when you run the test program.
# env LD_LIBRARY_PATH=lib ./showfiles
Once the test program is running, open up another terminal or shell. Create some file within the /tmp/testmnt directory. As files are accessed, the test program should output various information. The test program always permits the accesses, however another application could be written that denies file accesses in certain conditions.
The test program can be ended by hitting Ctrl-C. The DazukoFS filesystem can be unmounted with:
# umount /tmp/testmnt
[edit] Step 5: Install DazukoFS
After you have verified that DazukoFS works correctly on your system, you will probably want to install it on the system (so that it is easily available). From the original DazukoFS source code directory (not the test directory) you can run (as root):
# make dazukofs_install
This performs the necessary actions to install the DazukoFS device driver to your system.
