1. OVERVIEW
===========

Dropletfs-fuse, a FUSE filesystem for cloud storage, using the Scality
Droplet library [1].  Be sure to read and configure your environment as
explained in [2].


2. INSTALLATION
===============

This program is not packaged yet, as far as I know.  You'll have to compile
it by yourself.  It relies on the Droplet library, so grab it!

	$ git clone git://github.com/scality/Droplet
	$ cd Droplet
	$ ./autogen.sh
	$ ./configure
	$ make
	$ sudo make install

If the previous lines fail, I suggest you take a look at [3].

Then go to the dropletfs-fuse directory, and type:

	$ make
	$ sudo make install


3. SETTINGS
===========

 - libdroplet object path

the Droplet library is installed in /usr/local/lib by default, so you may have
to set LD_LIBRARY_PATH to this value before running dplfs.


 - Compression

You can set DROPLETFS_COMPRESSION_METHOD to ZLIB, to reduce the network load.
Default value is NONE. The default compression level is 3. You can change it
through DROPLETFS_ZLIB_LEVEL.

You can set this value in your $HOME/.dplfsrc file:

compression_method = zlib
compression_level = 3


 - Cache directory

Dropletfs use a local cache directory to operate on file descriptors.  This
cache holds the whole files you're working on.  I strongly recommend you to
set it to a directory in a partition with a bunch of available GB.

You can change its value through DROPLETFS_CACHE_DIR.  Default is /tmp.

Also, in you configuration file:

cache_dir = /tmp


 - Garbage collection

DROPLETFS_GC_AGE_THRESHOLD (in seconds): a cache file older than this value
will be removed.  If zero, the garbage collection is not triggered. Default
is 900.
DROPLETFS_GC_LOOP_DELAY (in seconds): the GC is invoked with this period.
Default is 60.

In your configuration file:

gc_age_threshold = 900
gc_loop_delay = 60


 - Smart metadata cache system

The main goal of this functionnality is to increase the responsiveness,
for example when you type 'ls -l' with a slow bandwidth. Or when your
directories are filled with many entries.

You can use the following environment variables:
DROPLETFS_SC_LOOP_DELAY: periodic update of metadata, in seconds. The
default value is 0.
DROPLETFS_SC_AGE_THRESHOLD: updates files 'older' than this, in seconds,
where 'older' means 'was not accessed after in the last N seconds'. The
default value is 0.

In your configuration file:

sc_loop_delay = 30
sc_age_threshold = 10

NOTE: default values were previously 30 and 10 seconds.  But since you
may use dropletfs-fuse with you amazon s3 account, in order to avoid your
account being heavily charged, I disabled the feature by default (nope,
the LIST command is not free, so if you forgot to umount the device
before sleeping, your banker won't be happy).


 - Encryption

Use the environment variable DROPLETFS_ENCRYPTION_METHOD.  Set it to
"AES" is you want to encrypt your data, otherwise it will be in plain
text.

You can also set it in your configuration file (e.g. $HOME/.dplfsrc):

encryption_method = aes

The default value is "none".


 - Filename pattern exclusion

In some specific cases, we do not want to upload some files on remote
storage (for example temporary files in scientific computing).  To handle
this, you can set DROPLETFS_EXCLUSION_PATTERN to a regular expression.

For example, to exclude all the files ending in .tmp or .foo, type:

$ export DROPLETFS_EXCLUSION_PATTERN='\.tmp$|\.foo$'

In you configuration file:

exclusion_pattern = '\.doc$'

This feature is *experimental*, we do not recommend using it unless you know
exactly what you're doing.

4. FIRST RUN
============

Now, mount your cloud storage wherever you want, and enjoy!

	$ sudo mkdir /tmp/cloud
	$ dplfs <my bucketname> /tmp/cloud
	$ ls /tmp/cloud
	total 0
	-rw-r--r-- 1 poz poz      10 Dec 20 16:18 bar
	dr-x------ 1 poz fuse      0 Dec 30 23:20 code/
	dr-x------ 1 poz fuse      0 Dec 30 23:20 fix/
	-rw-r--r-- 1 poz poz       4 Dec 12 17:19 foo.backup
	dr-x------ 1 poz fuse      0 Dec 30 23:20 hey/
	-rw-r--r-- 1 poz poz  214642 Dec 20 16:12 metro.pdf
	dr-x------ 1 poz fuse      0 Dec 30 23:20 test/
	-rw-r--r-- 1 poz poz     538 Dec 29 11:40 tmpstr.c
	-rw-r--r-- 1 poz poz     111 Dec 29 12:19 tmpstr.h
	$

5. UNINSTALLATION
=================

In the project directory, just type:

	$ sudo make uninstall



Please report bugs and comments to:
	https://github.com/pozdnychev/dropletfs-fuse/issues


[1] http://github.com/scality/Droplet
[2] http://github.com/scality/Droplet/wiki/Configuration-file
[3] http://github.com/scality/Droplet/README