Skip navigation.
Home
PersistentFS.com

PersistentFS Installation

Layout

The suggested locations for the PersistentFS installation files are:

  • Executable file: /sbin/persistentfs
  • Configuration file: /etc/persistentfs.conf

The default locations for files created by PersistentFS at runtime are:

  • Cache file: /var/cache/persistentfs.cache
  • Log file: /var/log/persistentfs.log
  • PID file: /var/run/persistentfs.pid

Installing the FUSE kernel module under EC2

PersistentFS uses the FUSE (Filesystem in Userspace) interface, which consists of a kernel module, fuse.ko, and a runtime library, libfuse.so.2. If you are using PersistentFS under Amazon EC2, using Amazon's v2.6.16 32-bit kernel or v2.6.16.33 64-bit kernel, you must install the FUSE kernel module located on the PersistentFS.com web site. The FUSE kernel module built by Amazon for these kernels is defective and can cause kernel crashes. The module on the PersistentFS.com website was built from the latest stable FUSE source release and was tested to work correctly.

The FUSE kernel module built for Amazon's v2.6.16-xenU 32-bit EC2 kernel can be downloaded and installed as follows:

su
mkdir -p /lib/modules/2.6.16-xenU/kernel/fs/fuse
cd /lib/modules/2.6.16-xenU/kernel/fs/fuse
rm -f fuse.ko
curl -O http://www.persistentfs.com/extras/ec2-linux-2.6.16-xenU/fuse.ko
/sbin/depmod
reboot

The FUSE kernel module built for Amazon's v2.6.16.33-xenU x86_64 EC2 kernel can be downloaded and installed as follows:

su
mkdir -p /lib/modules/2.6.16.33-xenU/kernel/fs/fuse
cd /lib/modules/2.6.16.33-xenU/kernel/fs/fuse
rm -f fuse.ko
curl -O http://www.persistentfs.com/extras/ec2-linux-2.6.16.33-xenU-x86_64/fuse.ko
/sbin/depmod
reboot

Installing the FUSE Runtime Library

PersistentFS requires the FUSE runtime library libfuse.so. This is often included with a Linux distribution. Nonetheless, it is recommended that you download and install the FUSE runtime library available on the PersistentFS.com website. This library was built from the latest stable FUSE source release and was tested to work properly with PersistentFS. It should be compatible with other FUSE applications as well.

libfuse.so should be installed in the system directory that contains 32-bit library files. On 32-bit systems, and on 64-bit Red Hat distributions, this directory is /usr/lib. On 64-bit Debian distributions, this directory has been changed to /usr/lib32. Prior to installing libfuse.so, you should check to see where the 32-bit system libraries are stored, and modify the steps below if necessary:

su
cd /usr/lib
rm -f libfuse.so.2.7.3
curl -O http://www.persistentfs.com/extras/libfuse.so.2.7.3
ln -sf libfuse.so.2.7.3 libfuse.so.2
ln -sf libfuse.so.2.7.3 libfuse.so
/sbin/ldconfig /usr/lib

Installing PersistentFS

  1. Download and install the PersistentFS executable:


    2. su
    cd /sbin
    rm -f persistentfs
    curl -O http://www.persistentfs.com/release/development/latest/persistentfs
    chmod 500 persistentfs

  2. PersistentFS requires the standard 32-bit C/C++ runtime libraries. On most systems, these will already be installed, but this is a good time to check.


    First, attempt to launch PersistentFS:

    /sbin/persistentfs

    If a required library is missing, an error message will be displayed with the name of the missing library that must be installed before continuing. Otherwise, if PersistentFS displays its welcome banner, there are no missing libraries.

  3. Download the PersistentFS configuration file:


    cd /etc
    rm -f persistentfs.conf
    curl -O http://www.persistentfs.com/release/development/latest/persistentfs.conf

  4. Edit persistentfs.conf and set S3Bucket, S3KeyPrefix, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, and any other desired parameters (see Command line & Configuration File Options or "/sbin/persistentfs --help" for an explanation of the settings).

    nano persistentfs.conf

    For S3KeyPrefix, we suggest something ending in "-", such as "test-" or "pfs1-". All data PersistentFS stores in the bucket will be given this key prefix, allowing it to be easily identified.

    For this release of PersistentFS, the bucket you specify in the S3Bucket parameter needs to be created before running PersistentFS. There are many tools that can create a bucket, or you can use AWSZone. If the bucket is located in the Amazon EU datacenter, you will have to set UseS3VHostUrl=true in persistentfs.conf.

    For production use, you will want to increase the size of PersistentFS's cache file using the CacheMegabytes setting. The first time PersistentFS is run, the cache file will be allocated, and this will take approx. 30 seconds per GB. The size can be changed later without reallocating the entire cache file. Note that the default location for the PersistentFS cache file is /var/cache/persistentfs.cache. This can be changed with the CacheFilename setting. If you use the default location, you should ensure that /var/cache is located on the EC2 ephemeral store (not on the root file system) and that it has sufficient free space. Otherwise, you can change CacheFilename so the cache file is stored under /mnt, for example, at /mnt/persistentfs.cache.

  5. Create a mount point. A suggested mount point is:

    mkdir -p /mnt/pfs

Beginning PersistentFS Operation

  1. Check that the FUSE kernel module is loaded:

    su
    /sbin/modprobe fuse

    If the fuse.ko module is not configured to load at system boot, you will need to run "modprobe fuse" after every reboot.

  2. Run persistentfs and create a new file system:

    /sbin/persistentfs mountpoint -f --CreateNewFileSystem

    After PersistentFS displays the message "Starting FUSE main loop", the new file system can be dismounted by pressing Control-C.

  3. The file system can be remounted, with the persistentfs process put in the background and its output sent to its log file by using the command:

    /sbin/persistentfs mountpoint -o allow_other

    This command makes the file system available to all users. For a complete list of mount options, see Command line & Configuration File Options.

  4. You can check to see if the file system is mounted using the "df" command. When the PersistentFS file system is mounted, df will display a line that looks like this:

    Filesystem         1K-blocks   Used      Available Use% Mounted on
    fuse            274877906880      0   274877906880   0% /mnt/pfs

  5. When running in the background, the file system can be unmounted using the command:

    umount mountpoint

    Before rebooting, shutting down, halting or terminating the system, you should wait until PersistentFS's PID file has disappeared. This ensures PersistentFS has finished saving all modified data to S3:

    while [ -f /var/run/persistentfs.pid ]; do sleep 1; done

  6. If you attempt to mount the file system and get the error message "*** THE FILE SYSTEM IS IN USE OR WAS NOT CLEANLY DISMOUNTED", you should check to make sure the PersistentFS process is not running:

    ps aux | grep persistentfs

    This check needs to be done on your current machine, as well as every other machine that could have mounted the same file system. If a PersistentFS process is still running that uses the same file system, you can check its log file output ("tail -f /var/log/persistentfs.log"), wait for it to finish, umount it, or as a last resort, kill or kill -9 the process.

    After you have ensured the file system is not in use by any other process, it can be repaired and remounted using the command:

    /sbin/persistentfs mountpoint -o allow_other --RepairDismount

  7. If you would like to see PersistentFS "in action", you can enable some of the Log/Tracing options in persistentfs.conf. Enabling the following options is a good place to start: TraceFuseIn, TraceFuseOut, TraceReadWriteIn, TraceReadWriteOut, TraceFsync, TraceIndexLock, TraceFind, TraceIndexInsDel, TraceIndexPageOps and TraceFlushQueues. These options can also be enabled from the command line by including the option with "--", i.e., "--TraceFuseIn".