
INTRODUCTION

offlinefs is a fuse-based filesystem initially intended to join a
large collection of ejectable media (like CDs and DVDs) in a single
writable filesystem where the files could still be searched, moved
around, reorganized in directories, etc.

If an user tries to open a file, he's asked to insert the volume where
that file's contents are stored. The data is then transparently read
from the real medium.

If you've got any problem, questions, contributions... contact me at
<currojerez@gmail.com>. 

The source code is currently maintained at:
http://savannah.nongnu.org/projects/offlinefs/


INTERNALS

Each file's contents can be provided by an arbitrary handler (an
object implementing the interface at
src/libofflinefs/media/medium.hxx), so it isn't limited to the usage
described above.

When the user tries to access a file, one of the handlers is called
depending on the file's extended attributes (offlinefs.mediumid): the
specified medium ID is looked up in the media database and one of the
compiled-in handlers is selected.


LICENSE

Copyright (C) 2008 Francisco Jerez

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You can find the full GNU General Public License in the file "COPYING".


INSTALLATION

To build it, you need the following dependencies:
 - Berkeley DB (runtime and headers for C++, it's likely to have a
 name like libdb4.X++-dev in your distribution... versions 4.7-4.5
 have been tested. It's not known if other versions work)
 - FUSE (runtime and headers)
 - Extended attributes library (It's likely to be called attr-dev,
 libattr-dev or something similar)
 - Standard GNU C++ compilation tools and libraries (g++, make, etc)
 - kdialog (It's used to show messages in an X display: you could use
 any similar program by editing the corresponding line in the
 insertion script)
 - The boost::program_options library and headers
 (libboost-program-options-dev in debian)

Then you would just run the following commands at this directory:
$ ./configure
$ make
And as root:
# make install

If you installed it at the default prefix (/usr/local) and you didn't
had /usr/local/lib in your library path, you'll have to edit
/etc/ld.so.conf to add it, and then run: 
# ldconfig


USAGE

Before using it you'll have to initialize a database directory: it
could be anywhere (by default it's assumed to be at
$HOME/.offlinefs/), create it somewhere with enough permissions to
allow r/w access to the users that will be using it.  You can
initialize it with:

$ offlinefs --rebuilddb [ -o dbroot=<path to database directory> ]

And then you can mount it with:

$ offlinefs [ -o dbroot=<...> ] <mount point>

If you are going to mount it as root and you expect some unprivileged
user to be able to write in the database, it's possible that you will
need to specify other options like "-o dbgroup" and "-o dbumask" at
the command line.

You can get it automatically mounted at system startup by adding a
line like this one in /etc/fstab:
offlinefs      <mount point> 	     fuse      	       <mount options>	     0 0

Where <mount options> is any combination of the options which are
prefixed with "-o " in the command line.

Some useful command line options are "-d" (debug mode) and "-o
allow_other" (especially when run as root: otherwise he would be the
only user allowed to access the filesystem).

To unmount it as an unprivileged user, you can do:
$ fusermount -u <mount point>

MEDIA MANAGEMENT

You can modify the media database with the "offmedia" command. It's
kind of a low-level tool, and you will rarely have to use it:
generally, you would import a whole filesystem tree with the
"offimport_cd.sh" script: It creates a new entry in the media database
(an "insert" type medium). Then it recursively scans the specified
directory adding each file and each directory to the filesystem and
associating them with the newly created medium.

You could use it like this:
$ offimport.sh -i <directory> -l <label>

When trying to access a file, you will be asked to insert the volume
with label <label>.  (Depending on the user having mounted the
filesystem and the X display you want to be asked in, you may have
to modify the insertion script at /usr/local/etc/offlinefs/insert)

To get a dump of the media DB, you can use the command:
$ offmedia --list

offimport_cd.sh internally uses the offimport program, which
reproduces a directory listing ( e.g. the one generated by "find")
inside the database.

MEDIUM TYPES

The only currently implemented medium types are:
* directory
 The data is stored somewhere else in the filesystem, at the directory
 specified by the "directory" medium attribute. It is useful if you
 want a permanent backend to make the filesystem writable (you can
 specify a default medium to write the data to in the command line).

 To create a directory medium:
 $ offmedia --add directory --label <label>
 $ offmedia --label <label> --set directory <directory>

 Note that <directory> should be an absolute path.  You can also set
 the "unlink_files" medium attribute. It is used to allow it deleting
 the underlying files when they are not needed anymore (this doesn't
 make sense in a static medium like a CD).
 
* insert
 Similar to "directory", but before any filesystem operation, the
 presence of the volume will be checked with an user-specified command
 ("checkcmd" attribute) and in case it isn't present, an
 user-specified script will be run ("insertcmd" attribute).
