IAFS - interactive filesystem

Introduction

The interactive filesystem is intended to handle jukeboxes. A jukebox is a blackbox with lots of medias (CD, DVD, etc.), a mechanical charger and a drive to read the media data from.

I took the definition of a jukebox a bit more in general and from my point of view a jukebox may also be a human being, having several harddisks in a safe and pluging it into a machine to access the data (a so called 'humanoide charger').

Having changeable media is nothing new, but if you have a lot of them, you'd like to know, what's on your unmounted media.

That's where IAFS comes into play. IAFS saves (with an import utility) the directory structure to local disk and adds special kind of hardlink for every file. After importing a media (wich may be a harddisk with lots of data) you can move the saved hardlinks as you like to do and so bring several medias into an individual order.
As long as you don't change the content, the linking will work, even if the directory tree has no more in common with the imported media. - well, if you move a special hardlink out of the managed tree, it's nothing more than a regular file and the linking will not work any more. But you can move that file back into the managed tree and linking will work again.

How does it work

One of my major interests was, not to limit handling to known physical devices. I also wanted all files be accessible without the help of IAFS. So IAFS became a thin management layer between kernels VFS and the fs, that manages the physical devices. The latter can be of any type, that is supported by the kernel.

IAFS uses two mountpoints for management (both can be changed via call options):

/mnt/import: the mountpoint for the exchangeable media
/media/jukebox: the path where to access the data from the exchangeable media

Beside the "public" mountpoints, there are also 2 hidden directories of interest. If you like to change the path where the jukebox is accessed from (/media/jukebox), you must ensure, that these hidden directories share the same parent directory than your jukebox-path. These hidden directories are:

/media/.jbCache

the offline cache. It will be wise to mount an empty harddisk to this location.

/media/.jbScripts

the root for the transaction scripts. To ensure flexibility and expandability, the real actions are performed by using shell scripts. To allow the 'jukebox' the handling of different environment types, there exist several subdirectories in .jbScripts, each of them is treaten as a binding type.

The action-scripts are:

notify.sh: used to trigger the changing of the media. local/notify.sh works in a KDE desktop environment and uses kdialog. vdr/notify.sh works in VDR environments and uses the OSDServer for user communication.
If you have a real jukebox, you might create your own binding type, by cloning local or vdr to i.e. serial and adopt serial/notify.sh to fit your needs.
The feedback from the script to IAFS works by exit codes. In unix manner, exit code 0 stands for OK and all other exit codes for an error.
attach.sh: used to mount the exchangeable media. The import utility verifies, how a media is mounted at import time and will remount it on access.
detach.sh: used to unmount the exchangeable media. As it is common to all binding types, it resides in .jbScripts not in the binding type directory.

Interaction

The correct working depends a lot on the right options given to the import utility. So let me first introduce the importer:

import.iafs

The importer does not require the IAFS to be mounted or active, but it has to be setup correctly. Further you should know the both public management mountpoints /mnt/import and /media/jukebox or whatever you decide to use. If you decide to use these paths, they are implemented as default. Others have to be specified.

Before running the importer, you have to manually mount the desired media to the public mountpoint /mnt/import. The importer checks how the media is mounted and uses that information on remounting on request.

To identify your media, you have to give it a unique id. That id can be just a number, a word like 'dvd1' or a whole sentence like: third harddisk on fifth floor, whatever you consider appropiate to recognize your media.

Finally you need to specify the binding type used to exchange the media, means the subdirectory of .jbSripts, which is 'local', 'vdr' or whatever you create.

Now you're ready for import.

All directory handling is routed to the 'real' fs of the offline-cache. When you open a file, the special hardlink is read. By an internal token it is asured, that no regular file is treaten as offline link. Then the id of the mounted media is checked, whether it matches the media-id of the requested file. If the media-id matches, the request is routed to the real file from the exchangeable media. If the media-id does not match, the mounted media is unmounted by a call to detach.sh. Then notify.sh is executed with the new media-id as argument.

Depending on the exit-code from notify.sh the new media will be mounted by a call to attach.sh or the file open will fail with the error, that the file does not exist.

It seems, as if user notification from a daemon process is not supported/desired. But IAFS makes no sense on systems with humanoide chargers, without that notification.
Through to the great beginners support from KDE stuff and a missing configuration ability in OSDserver, I decided to create a proxy (written in perl) for both use-cases.

Now the user-notification from daemon process works without workarounds or monkey business. Neither X, nor VDR need to be exposed to public.

I packaged a separated archive for vdrsystems. As my standard on VDR systems is LinVDR, users of other vdr-systems may have to adopt the scripts.

Installation

at the jukebox machine
Unpack the archive change into the iafs directory and call ./IAFS.sh. The IAFS-manager is intended to be executed as a normal user. All superuser tasks are wrapped by sudo-calls. Of cause, you need write-permission to the iafs directory unpacked from archive.
The IAFS-manager checks the requirements and guides you through installation, setup and also assists on importing medias, as well as on removing medias from cache.
Just follow the menue-items topdown.
The IAFS-manager with all it's steps has been tested on Debian testing 32bit and Debian stable 64bit - and it worked fine.
on a KDE slave:
Copy the proxy (iafsProxy.pl) to /usr/bin and create a softlink to the users KDE Autostart directory
```
   ln -s /usr/bin/iafsProxy.pl ~/.kde/Autostart/iafsProxy.pl
```
That softlink should be created for every user, that should receive media-change- notification from IAFS. The proxy has to be adapted. Change line 28 'yourDesktop' to the hostname of the machine, where IAFS is working. Only with this change a communication will be allowed.
on the VDR (LinVDR):
Untar the archive. Important (as usual on LinVDR packages) to add the Option -C
```
   tar -jxf <archiv> -C /
```
but that should be well known.
At /etc and /etc/init.d there are files, prefixed by append_to_. These files are to activate the proxy on the VDR machine.
/usr/sbin/iafsProxy.pl should be changed that way, that line 28 'yourDesktop' will be changed to the hostname of the machine, that runs IAFS. Only with this change a communication will be allowed.

The Manager

The script IAFS.sh assists on building and setup of IAFS and also helps on importing medias or removing medias from cache. It verifies the given mediaid for the current step. Especially for the first time, its usage is recommended.

In installations, that don't follow the default path recommendations, its even more valuable, as IAFS.sh is able to save the important settings, so you don't have to reenter them again.

The IAFS-manager is intended to be localizable - well, it's texts only. Currently texts in english and german are provided. If you like to translate texts, I will be very happy about your submission (see .lang for textfiles).

FINETUNING

some application determine the mime-type of a file by reading the first chunk, so you might want to turn "magic mime-type" handling off. Another anoying file might be .directory and as I like to have the information of recordings available without mounting them, I extended the functionality of the importer.

You can add filenames to dedicated files, which then on import are not linked, but copied. The system wide configuration file is searched at /etc/iafs/nolink.cnf, the user configuration is ~/.iafs.nolink. User configuration can only extend system configuration, not overwrite.

The format is quite simple: one filename a row and lines starting with '#' are treaten as comment. Sample:

   # enter filenames, that should be copied instead of linked
   .directory
   summary.vdr
   info.vdr

Start the game

IAFS is intended to be started as root, so mounting and unmounting will work. With the helper for mount (mount.iafs) it is possible to start IAFS from fstab.

Sample line for fstab looks like:

      /mnt/import  /media/jukebox   iafs  defaults    0  0

The importer does not need root access. It performs normal file operations and as long as the rights of the directories are setup well, nothing bad should happen.

If you imported a media without a prefix or want to remove an imported media - no problem - that's a task for wipe.iafs. It is intended to remove all files from an imported media - no matter whether the offline-links have been moved around. That utility has a stats-mode, which displays all imported medias with the number of files related to it.
It also as a 'testmode', which only list the files, that belong to a media.

LIST of EXECUTABLES

IAFS.sh - the IAFS manager - use to build, setup, im- and export
fs.iafs - the filesystem itself
mount.iafs - the mount helper
import.iafs - the importer
wipe.iafs - the cache cleaner (with stats option)
iafsProxy.pl - the proxy for KDE and VDR. Who uses another windowmanager may easyly adopt iafsProxy.pl to his preferred windowmanager.

PERMISSIONS and MOUNT options

With the new mount helper nearly all options are passed to fuse. But as IAFS is a readonly-filesystem by intention, no write options are supported. 'ro' is hardcoded. I also wanted IAFS to be nearly invisible, so 'allow_other' and 'default_permissions' are also fixed. Both mean, that access-rights are not changed by IAFS.

Starting with release 0.0.4, IAFS saves the mount parameters from the import time (The format of the offline-links changed and those of you, that already gave IAFS a try, need to recreate the cache.). So if you like to change the access-rights, do it on mounting the media to import and IAFS will reuse your options.

HAVE FUN!

IAFS project home

FUSE project home

IAFS is hosted at