home *** CD-ROM | disk | FTP | other *** search
/ PC-Online 1996 May / PCOnline_05_1996.bin / linux / source / kernel-s / ifs-5.1 / ifsprogs / readme < prev    next >
Text File  |  1995-10-10  |  7KB  |  223 lines
  1. Kernel-based Inheriting File System (IFS), experimental release 5
  2. =================================================================
  3.  
  4.  
  5. * WARNING * WARNING * WARNING * WARNING * WARNING * WARNING * WARNING * WARNIN
  6.  
  7.     THIS CODE IS EXPERIMENTAL AND HAS KNOWN BUGS. USE AT YOUR OWN
  8.     RISK. BE PREPARED TO EXPERIENCE FILE SYSTEM CORRUPTION AND TO
  9.     RESTORE YOUR SYSTEM FROM BACKUP MEDIA IF USING THIS CODE.
  10.  
  11. G * * WARNING * WARNING * WARNING * WARNING * WARNING * WARNING * WARNING * WA
  12.  
  13.  
  14. Concept
  15. -------
  16.  
  17. The Inheriting File System (IFS) provides a means to mount a "pack" of layered
  18. directories where upper layers "inherit" files from lower layers. Upper layers
  19. can also "override" files present in lower layers and the top layer can even
  20. hide ("whiteout") files of lower layers. If write operations are performed on
  21. such a pack, they are always carried out on the top layer. Directory paths and
  22. files are duplicated ("cloned") from lower layers if necessary. This concept
  23. is vaguely based on Sun's translucent file service (TFS).
  24.  
  25. IFS can be used for the following applications (among others):
  26.   - make read-only media (e.g. CD-ROMs) pseudo-writable
  27.   - make local writable copies of a common precious source (e.g. a common
  28.     source tree used by several programmers)
  29.   - "map" several directories to a single directory (e.g. /usr/bin)
  30.   - perform loopback mounts
  31.  
  32. I'd like to point out that most of this can also be done in a similar way
  33. using symbolic links.
  34.  
  35. Whiteout entries are empty regular files in a directory ... at the top layer.
  36. Whiteout entries on lower layers of a pack are ignored. An empty directory in
  37. a ... directory indicates that the corresponding directory should not inherit
  38. files from lower layers.
  39.  
  40. The current implementation assumes that sparse trees are mounted on top of a
  41. tree that contains most of the files. For extremely opposite cases, a
  42. depth-first search would be faster.
  43.  
  44.  
  45. Known restrictions and problems
  46. -------------------------------
  47.  
  48. The following bugs and restrictions are known. There are probably a lot more
  49. yet unknown bugs.
  50.  
  51.   - apparently deleted files may become visible for a short time during
  52.     mkdir or rmdir
  53.   - not all VFS operations are supported by IFS (see "Supported operations")
  54.   - file and directory access is kludgy
  55.   - changing the permissions of a file may force duplication of that file
  56.   - mount points of mounted file systems are invisible through IFS
  57.   - modifying a directory tree while it is mounted as part of a pack may yield
  58.     surprises
  59.   - link counts are usually wrong
  60.   - the code is way too complex
  61.   - IFS does not remove unused files and directories
  62.   - smount must be used - the regular mount will crash
  63.   - the top-level file system may be left in an inconsistent state (e.g. files
  64.     may be present and whited out at the same time)
  65.   - there may still be race conditions
  66.  
  67.  
  68. Installation
  69. ------------
  70.  
  71. cd to your unmodified 0.99pl11 or ALPHA 0.99pl12 kernel source tree, apply
  72. ifs.patch with
  73.  
  74. patch -p1 -s <ifs.patch
  75.  
  76. then generate the kernel with
  77.  
  78. make config
  79. make dep
  80. make clean
  81. make (or make zlilo, etc.)
  82.  
  83. Finally, extract Makefile, smount.c and unwo.c and run make to build smount
  84. and unwo.
  85.  
  86. Note: smount has changed since the last version. IFS 5 requires the new
  87.       smount. IFS 4 (and older) does not work with the new smount.
  88.  
  89.  
  90. Mounting
  91. --------
  92.  
  93. An Inheriting File System is mounted by
  94.  
  95.     smount -t ifs <pack> <dir>
  96.  
  97. where <pack> is a comma-separated list of directory names. All write
  98. operations are directed to the first directory of the list (the top-level
  99. directory). Read operations are performed on all directories. <dir> is the
  100. mount point. It must be different from the directories in <pack>. Example:
  101.  
  102.     smount -t ifs a,b,c t
  103.  
  104. The size of a pack is currently limited to four directories. This can be
  105. changed by editing include/linux/ifs_fs_param.h and re-compiling the kernel.
  106.  
  107. To unmount an Inheriting File System, type
  108.  
  109.     smount -u <dir>
  110.  
  111. where <dir> is the mount point.
  112.  
  113. Example:
  114.  
  115.     smount -u t
  116.  
  117. The top-level directory should not reside on a file system that is more
  118. restrictive than the file systems of the directories below it, e.g. using
  119. an MS-DOS FS on top of a Minix, Ext or Xia FS will yield unexpected
  120. behaviour.
  121.  
  122.  
  123. Supported operations
  124. --------------------
  125.  
  126. The IFS currently _only_ supports the following operations:
  127.  
  128.   - file and directory name lookup
  129.   - reading regular files
  130.   - reading directories (readdir)
  131.   - creating regular files (includes unwhiteouts and path cloning)
  132.   - writing to regular files (includes cloning)
  133.   - deleting regular files (includes whiteouts)
  134.   - directory creation
  135.   - directory deletion
  136.   - symbolic link creation and reading
  137.   - following symbolic links (only partially tested)
  138.   - creation and access to special files (only partially tested)
  139.   - changing file attributes (only partially tested)
  140.   - renames of random FS objects within same directory on the same layer
  141.   - renames of regular files in all other cases (only partially tested)
  142.   - statfs
  143.  
  144. Among others, the following operations are _not_ supported:
  145.  
  146.   - bmap
  147.   - creation of hard links
  148.   - non-local renames of non-files
  149.  
  150.  
  151. Restoring whited out files
  152. --------------------------
  153.  
  154. When deleting a file or directory that is not located on the top layer, the
  155. file is not removed, but a whiteout entry is created in the top layer. (This
  156. is an empty regular file in a directory named "...") Such files can be made
  157. accessible again with unwo. Usage: unwo file ...
  158.  
  159. Example:
  160.  
  161.   mkdir a b a+b; touch b/file
  162.   smount -t ifs a,b a+b; cd a+b
  163.   ls; rm file; ls
  164.   unwo file; ls
  165.  
  166.  
  167. Test
  168. ----
  169.  
  170. IFS is accompanied by a test suite that verifies correct execution of some
  171. sequential operations. This test is not designed to detect race conditions.
  172.  
  173. Prerequisites:
  174.   - a recent version of perl with syscall support. (Missing in perl as
  175.     distributed in some versions of SLS. Perl compiled "out of the box"
  176.     (without its own malloc) appears to work, though.)
  177.   - perl header files sys/syscall.ph, linux/errno.ph and linux/stat.ph
  178.     (run  h2ph sys/syscall.h linux/errno.h linux/stat.h  to generate
  179.     them).
  180.   - an empty directory on a file system with at least ~20 free blocks.
  181.     If possible, an empty file system should be used.
  182.  
  183. To run the test, extract test.pl from the distribution and start it with
  184.  
  185. ./test.pl <directoryname>
  186.  
  187. E.g.
  188.  
  189. ./test.pl /scratch
  190.  
  191.  
  192. Performance
  193. -----------
  194.  
  195. IFS directory lookups are approx. [1..N] times as expensive as ordinary
  196. directory lookups, where N is the number of layers in a pack. For best
  197. performance, the layers should differ as close to their respective tops as
  198. possible, e.g.
  199.  
  200.   A: ./x/foo/bar
  201.   B: ./y/foo/bar
  202.   C: ./z/foo/bar
  203.  
  204. is much better than
  205.  
  206.   A: ./foo/bar/x
  207.   B: ./foo/bar/y
  208.   C: ./foo/bar/z
  209.  
  210. Reading a directory with readdir needs O(N^2) lookups, because for each entry
  211. of each pack, the whiteout directory and all entries above of it have to be
  212. checked.
  213.  
  214. Because no namei caching is being done, using IFS to make a "unified" /usr/bin
  215. may actually be slower than using a long PATH with caching done by the shell.
  216.  
  217.  
  218. Contact
  219. -------
  220.  
  221. Please send bug reports, comments, flames and such to
  222. Werner Almesberger <almesber@bernina.ethz.ch>
  223.