Last Update 19-FEB-2010

XrootdFS is a Posix filesystem interface for an Xrootd storage cluster. It is 
designed under the FUSE framework. Please refer to XROOTD web page for more 
info about the Xrootd, and XrootdFS web page:

http://wt2.slac.stanford.edu/xrootdfs/xrootdfs.html

The XrootdFS has been tested under 
                 FUSE 2.7.0     2.7.1     2.7.3      2.7.4
RHEL4, 32 bit          OK        OK
RHEL4, 64 bit                    OK
Fedora 9 32 bit                            OK
RHEL5, 32 bit                    OK                   OK
RHEL5, 64 bit                    OK                   OK

Note untested doesn't means things will not work. It just means we don't have 
an environment or time to test. Also note that Fedora 9 come with FUSE 
kernel module fuse.ko.

Installation:
============

(2011-01 obsolete, XrootdFS is now a package of Xrootd)

Install FUSE, including FUSE kernel module if the platform doesn't have the 
FUSE kernel module included. The FUSE software and the installation guide is 
available at http://fuse.sourceforge.net.

Expand the XrootdFS tarball under the top FUSE source director. This will 
create a 'xrootdfs' directory. Go the this directory, make necessary change to
XRDSRC and XRDLIB in Makefile and Makefile.in to reflect the location of the
Xrootd source files and libraries. Then do a 'make'.

Configuration:
=============

All configurable environment variables are located in xrootdfs.template. In 
this file, MOUNT_POINT and XROOTDFS_RDRURL are needed. XROOTDFS_CNSURL and 
XROOTDFS_FASTLS are optional.

There are two more optional environment variables:

XROOTDFS_USER: if defined, XrootdFS will setuid/setgid to this user after 
    starts.
XROOTDFS_OFSFWD: if the xrootd cluster uses ofs.forward (or ofs.forward 3way) 
    to forward mv/rm/rmdir/trunc, one can define XROOTDFS_OFSFWD to '1', 
    and XrootdFS will simply do these operations on the redirector and CNS, 
    and expect the operations to be forwarded to the data nodes by the 
    redirector. Otherwise one can define XROOTDFS_OFSFWD to '0'. XrootdFS will 
    then go to individual data node for mv/rm/rmdir/trunc.
XROOTDFS_NO_ALLOW_OTHER: do not pass option allow_other to fuse.

Please refer to the "Introduction to the XrootdFS" document in the above web
page for more general idea of XrootdFS.

Many of the configurable parameters defined via environment vairable can also be
specified at command line. Command line options will overwrite those defined in 
environment variables.

Release 3.0rc3 and up should work nicely in most usage scenario (e.g. no HPSS
backend) without XROOTDFS_CNSURL and XROOTDFS_OFSFWD defined.

Security:
========

Without enabling Xrootd security module, Xrootd data servers map all XrootdFS 
users from a given XrootdFS instance to the user that actually runs that XrootdFS 
instance. With Xrootd's security module "sss" enabled in both Xrootd data server 
and XrootdFS, XrootdFS will provide to the Xrootd data servers the actual user 
information for access control.

To use "sss" security module, both Xrootd data servers and XrootdFS should be
configured to use "sss" in a particular way, e.g. both sides should use a 
key file that contains the same key generated by xrdsssadmin program in the 
following way:

xrdsssadmin -k my_key_name -u anybody -g usrgroup add keyfile

(change only "my_key_name" and "keyfile"). Please refer to environment variable 
"XrdSecsssKT" in Xrootd "Authentication & Access Control Configuration Reference"
on where Xrootd data server and Xrootd Client (e.g. XrootdFS) search for keyfile,
as long as requirement on Unix permission bits.

Run:
===

xrootdfs.template is a template "rc" script for starting and stopping XrootdFS.
One can make necessary changes and put it in /etc/init.d.

One can also put XrootdFS mount points in /etc/fstab. That require mount.fuse be 
installed (it is part of fuse RPM). The following is an example line in /etc/fstab:

xrootdfsd /mnt fuse rdr=root://rdr.my.com//xrootd,uid=daemon 0 0

Note XrootdFS binary (xrootdfsd) much be in $PATH, and all options are passed to 
xrootdfsd via command line parameters without using environment variable.

XrootdFS run with the following default options that can be overwritten at command 
line or options in /etc/fstab:

fsname=xrootdfs
allow_other
max_write=131072
attr_timeout=10
entry_timeout=10
negative_timeout=5

Note that allow_other cannot be unset by command line. To disable it set the
environment variable XROOTDFS_NO_ALLOW_OTHER=1.

Extended file system attributes:
===============================

Starting from release 3.0rc4, XrootdFS supports several extended file system
attributes for querying and changing XrootdFS file system on the fly:

Querying extended attributes:

xroot.url : querying the actual ROOT url of the file (this is an old one)
xrootdfs.fs.nworkers : querying number of worker threads for parallel
    operations such as stat(), unlink()/rmdir(), readdir(), statvfs(), etc.
xrootdfs.fs.dataserverlist : querying the list of all data servers known
    to this XrootdFS instance. (Starting from release 3.0rc3, XrootdFS will not 
    automatically refresh this list)

Setting extended attributes:

xrootdfs.fs.nworkers : change the number of worker threads. By default
    XrootdFS will start 4 threads. One can also use environment varialbe
    XROOTDFS_NWORKERS to define the number of initial threads.
xrootdfs.fs.dataserverlist : refresh the data server list. (or "kill -USR1 pid")

Release 3.0rc4 provides a utililty program, "xattr" for querying and setting 
extended file system attributes. 

Note the new extended attribute names are simplified, and work with getfattr and
setfattr (and therefore, "xattr" is no needed anymore)

Compiling on Mac OS X (Snow Leopard):
====================================

This is experimental.

The first thing is to compile Xrootd. If Xrootd Posix preload library won't
compile/build, comment it out in GNUmakefile. XrootdFS doesn't use Xrootd 
Posix preload lib.

The XrootdFS makefile needs to be adjusted in order to compile on Snow Leopard.
Currently XrootdFS needs to be linked against static Xrootd libraries without
using -static flag. One can do this by moving all .so in Xrootd lib directory 
to another place, thus force the ld to link against the .a.


Author:

Wei Yang
Stanford Linear Accelerator Center
2575 Sand Hill Road
Menlo Park, CA 94025
