1 Wrapfs: a null-layer (aka wrapper) stackable file system
3 Maintainer: Erez Zadok <ezk AT cs DOT stonybrook DOT edu>
4 Web Site: <http://wrapfs.filesystems.org/>
6 ------------------------------------------------------------------------------
9 Wrapfs is a small null-layer stackable file system, similar to BSD's Nullfs.
10 Wrapfs is small, under 1,800 lines of code. Compare that to, say, eCryptfs
11 (in mainline since 2.6.19) and Unionfs, each of which are over 10,000 LoC.
12 As such, Wrapfs is simple, easy to read and understand, and very easy to
13 code-review. Wrapfs is useful for several reasons:
15 1. Many people like to experiment with in-kernel file system ideas. Wrapfs
16 is an ideal small template that one can modify to incrementally create
17 new file system functionalities.
19 2. As a platform to test and debug generic stacking problems in other Linux
20 stackable file systems (e.g., eCryptfs) more easily.
22 3. As a way to test VFS enhancements to better support stacking in Linux.
24 4. Wrapfs is also a very useful instructional tool, often used as a starting
25 point for course assignments, for people who want a small example of how
26 the Linux VFS works, or for those who want to learn how to write new
29 5. As an alternative to bind mounts. Wrapfs acts similarly to BSD's
30 loopback mount file system (lofs).
32 Various versions of Wrapfs appeared as part of the "fistgen" package since
33 1994, and have been used by numerous users world-wide. This latest version
34 was rewritten entirely from scratch in 2010 and had supported every kernel
35 as of 2.6.32. All versions of wrapfs have been thoroughly tested using LTP,
36 FSX, racer, and other test-suites. Wrapfs code uses the latest VFS API
37 changes of the corresponding kernel. For a more detailed history of Wrapfs,
38 and list of most of its known users, see the section marked "HISTORY" below.
40 ------------------------------------------------------------------------------
43 This is a brief description of how Wrapfs operates. For more information,
44 see the full paper published in Linux Expo 1999, titled "A Stackable File
45 System Interface For Linux":
47 <http://www.fsl.cs.sunysb.edu/docs/linux-stacking/linux.pdf>
49 The basic function of a stackable file system is to pass an operation and
50 its arguments to the lower-level file system. For every VFS object (inode,
51 dentry, file, superblock, etc.), Wrapfs keeps a one-to-one mapping of a
52 Wrapfs-level object to the lower one. We call the Wrapfs object the "upper"
53 one, and the one below we call the "lower" one. Wrapfs stores these
54 mappings as simple pointers inside the private field of the existing VFS
55 objects (e.g., dentry->d_fsdata, sb->s_fs_info, and a container for inodes).
57 There are two kinds of stackable operations: those that create new VFS
58 objects and those that don't.
60 The following distilled code snippet shows a method which doesn't create a
61 new object. The method just has to pass it to the lower layer and propagate
62 any errors back up the VFS:
64 int wrapfs_unlink(struct inode *dir, struct dentry *dentry)
67 struct inode *lower_dir;
68 struct dentry *lower_dentry;
69 lower_dir = get_lower_inode(dir);
70 lower_dentry = get_lower_dentry(dentry);
71 err = lower_dir->i_op->unlink(lower_dir, lower_dentry);
75 The following code snippet shows a method which creates a new object. After
76 a lower object gets created, Wrapfs has to also create its own object, and
77 make the pointer connections between the upper and lower objects (the latter
78 is done via a helper routine called "interpose"):
80 int wrapfs_create(struct inode *dir, struct dentry *dentry, int mode)
83 struct dentry *lower_dentry;
84 struct inode *lower_dir;
85 lower_dir = wrapfs_lower_inode(dir);
86 lower_dentry = wrapfs_lower_dentry(dentry);
87 err = vfs_create(lower_dir, lower_dentry, mode);
89 err = wrapfs_interpose(dentry, dir->i_sb);
93 The wrapfs_unlink code snippet above can be easily modified to change the
94 behavior of unlink(2). For example, if an ->unlink operation is changed to
95 ->rename, this could become the basis for an "undo" file system; or if the
96 lower_dentry's name gets encrypted before calling the lower ->unlink, this
97 could be part of an encryption file system.
99 ------------------------------------------------------------------------------
102 First, you have to have some pre-existing directory already mounted from any
103 other file system, say /some/lower/path. Then, to mount wrapfs in
104 /mnt/wrapfs, on that lower directory, issue this command:
106 # mount -t wrapfs /some/lower/path /mnt/wrapfs
108 To access the files via Wrapfs, use the mount point /mnt/wrapfs.
110 ------------------------------------------------------------------------------
113 Stacking on NFS. Wrapfs has been tested with LTP, racer, fsx, parallel
114 compile, and more. It's been tested on top of ext2, ext3, xfs, reiserfs,
115 and tmpfs -- and passed all tests. However, on top of nfs3, wrapfs has to
116 treat silly-deleted files as if they don't exist: in ->unlink, if we try to
117 vfs_unlink an NFS silly-deleted file, NFS returns EBUSY; so we simply ignore
118 it and return 0 (success) to the VFS. NFS will delete this file later on
119 anyway. As the VFS also has special handling for silly-deleted files, this
120 isn't unusual. A cleaner way to handle this in the future is if the VFS
121 were to handle silly-deleted (aka "delayed-delete") files entirely at the
124 ------------------------------------------------------------------------------
127 Wrapfs was developed initially in 1994 for Linux 2.1, as part of Erez
128 Zadok's graduate work at Columbia University. It was designed to be a
129 flexible null-layer, pass-through, stackable file system, from which other
130 file systems would be developed and even instantiated automatically using a
131 high-level language. One of the first file systems developed from Wrapfs
132 was a simple encryption file system called Cryptfs (eCryptfs is based on
133 Cryptfs). Other examples include Gzipfs, a stackable compression file
134 system, and Unionfs, a stackable unification file system. Wrapfs was
135 integrated into a larger package called fistgen (see www.filesystems.org),
136 and ported to FreeBSD and Solaris. Wrapfs and fistgen continued to be
137 maintained for newer versions of kernels, but remained largely standalone
138 until recently: this release of Wrapfs for Linux represents a clean version
139 written from scratch.
141 Over the past 15+ years, versions of Wrapfs had been used by many users and
142 companies. At one point or another, the following groups have used stacking
143 code based on Wrapfs.
145 1. PROJECTS: eCryptfs, Unionfs, mini_fo, Aufs, FindFS, StoreCompress,
146 TestFS, ToPAS, and MFS.
148 2. COMPANIES AND RESEARCH LABS: Bell Labs's Plan 9 group, EMC,
149 Hewlett-Packard, IBM Research Almaden, IBM Research Austin, Red Hat,
150 SuSE, Sun Microsystems, Veritas, Booyaka, CalSoft (India), Computer Farm,
151 Deutsche Bank (Germany), DreamWorks LLC, Eli Lilly and Company, FAME
152 Information Services, GMX AG (Germany), IBM global services (India), IDA
153 Center for Communications Research, Indra Networks, Inc., Kavi
154 Corporation, Mendepie, Mitsubishi Electric (Japan), Mobile-Mind, Monster
155 Labs, Morning Network (Russia), NeST Technologies, Packet General
156 Networks, Inc., Outstep Technologies, Reflective Systems Group, River
157 Styx Internet, SARAI Net, Saint-Petersburg Official Web Site (Russia),
158 Shadow Island Games, TISCover (Germany), Trymedia Systems, Uber Admin,
159 Videsh Sanchar Nigam Limited (India), Wanadoo (France), and iNsu
162 3. UNIVERSITIES: Georgia Institute of Technology, Stanford University, UC
163 Berkeley, UCLA, University of Maryland, College Park, University of
164 Michigan, Ben Gurion University (Israel), Clarkson University, Clemson
165 University, Deutsches Elektronen Synchrotron (Germany), Electronics and
166 Telecommunications Research Institute (South Korea), Indian Institute of
167 Technology (India), National Taiwan University, Pune University (India),
168 The College of William \& Mary, Trinity College (Ireland), Universitaet
169 Frankfurt am Main (Germany), University Hospital Olomouc (Czech
170 Republic), and University of Salermo (Italy).
172 ------------------------------------------------------------------------------