fusefile.8

   1 .mso www.tmac
   2 .TH fusefile 8
   3 .SH NAME
   4 fusefile, fusedisk \- FUSE file mount for combining file fragments
   5
   6 .SH SYNOPSIS
   7 .B fusefile \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
   8 .br
   9 .B fusefile \fB-dump\fR \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
  10 .br
  11 .B fusefile \fB-push\fR \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
  12 .br
  13 .B fusedisk \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
  14
  15 .SH DESCRIPTION
  16
  17 \fBfusefile\fR is a FUSE \fIfile mount\fR that presents a series of
  18 fragments of other files as a contiguous concatenation. Technically it
  19 bind mounts a driver on top of the filename mountpoint to provide
  20 access to the given file fragments as if in a single, contiguous file.
  21
  22 \fBfusefile\fR accepts over-writing on the fused file (i.e. the
  23 mountpoint) which gets distributed accordingly to the fragments. But
  24 neither the fused file nor the fragments can change size; any writing
  25 thus merely over-writes content without truncating fragments. All
  26 fragment files are held open while \fBfusefile\fR is active.
  27
  28 By using the optional \fB-overlay:\fIfilename\fR argument between the
  29 mount point and the fragments, an overlay file may be set up. The
  30 overlay file will then be used by \fBfusefile\fR for capturing writes
  31 to the fused file (i.e. the mountpoint). The overlay file will contain
  32 any new written fused file regions followed by meta data to
  33 distinguish between new, written content and old content that comes
  34 from the fragments.
  35
  36 By instead using the \fB-overlay:\fIlist\fR argument where \fIlist\fR
  37 is a colon-separated list of filenames, \fBfusefile\fR will use those
  38 as an ordered stack of overlays and "inject" them as fragments on top
  39 of each other.
  40
  41 The option \fB-dump\fR as first argument together with a fusefile
  42 setup will print the setup to standard output rather than establishing
  43 a fusefile mount. This is of most use with a prior overlay setup where
  44 then the printout includes the portions of updates that have been
  45 captured in the overlay. The printout is the series of fusefile
  46 fragment argments to give in order to intersperse the captured overlay
  47 portions according to the overlay table.
  48
  49 The option \fB-push\fR as first argument together with a fusefile
  50 setup will push the overlay into the sources (except for
  51 write-protected fragments). This is only of use with a prior overlay
  52 setup where then the updates that have been captured in the overlay
  53 get pushed into the fragments.
  54
  55 \fBfusedisk\fR is a helper script to set up a \fBfusefile\fR as a
  56 block device (via \fIfuseblk\fR) by using the device mapper
  57 (\fBdmsetup\fR) to manage an empty block device mapping where content
  58 is handled at the mountpoint via \fBfusefile\fR. (Note that the same
  59 thing may be done with the device manager directly, but then all
  60 fragments need to be in sectors of N*512 bytes whereas with
  61 \fBfusedisk\fR, only the fused file as a whole is "clipped" at nearest
  62 N*512 bytes below actual size)
  63
  64 .SH FRAGMENT ARGUMENTS
  65
  66 The fragment arguments include the filename of a source file, and
  67 optionally start and end byte positions. All in all there five
  68 variations:
  69
  70 .TP
  71 \fIfilename\fR or \fIfilename/\fR
  72 include all of the file. A pathname that includes "/" must be ended
  73 with an extra "/" since that last "/" separates the filename from the
  74 range detail.
  75
  76 .TP
  77 \fIfilename/start:end\fR
  78 include the range from the given start to end. Either "start" or "end"
  79 or both may be omitted, to mean the beginning and end of the file
  80 respectively. If "start" or "end" are less than 0 then it means
  81 relative to the end of the file.
  82
  83 .TP
  84 \fIfilename/start+length\fR
  85 include "length" bytes from the given start. A negative "start" means
  86 relative to the end of the file. If "length" is negative or omitted it
  87 means that position relative to the end.
  88
  89 .TP
  90 \fIfilename/start\fR include bytes from the given start. This is the
  91 same as "/start+"
  92
  93 .P
  94 Note that a negative start position is clipped to 0 and a too large
  95 end position is clipped to the end of the file.
  96
  97 .P
  98 Character devices are treated as being of any given finite size, but
  99 have size 0 by default. For example, "/dev/zero/:100" means a fragment
 100 of 100 NUL bytes.
 101
 102 .SH OPTIONS
 103
 104 This section enumerates the most interesting options to use with
 105 \fBfuesfile\fR. See "man fuse" and "man mount" for more options.
 106
 107 .TP
 108 \fB-dump\fR
 109
 110 The \fB-dump\fR "option" tells \fBfusefile\fR to print out the
 111 applicable fragment sequence for the current setup, including the
 112 overlay table, if any. The printout is done instead of setting up a
 113 mount point.
 114
 115 .TP
 116 \fB-o\fIallow_other\fB
 117
 118 The fuse option \fI-oallow_other\fR is needed for sharing the fused
 119 file with other users who otherwise will not have access to it
 120 (including "root"). Note however that this must first be enabled in
 121 \fI/etc/fuse.conf\fR.
 122
 123 .TP
 124 \fB-o\fInonempty\fR
 125
 126 The fuse option \fI-ononempty\fR may need to be used when reusing an
 127 existing file as mountpoint.
 128
 129 .TP
 130 \fB-o\fIuid=...\fR and \fB-o\fIgid=...\fR,
 131
 132 These mount options, where \fI...\fR is a user or group id
 133 respectively, are useful for root when using \fBfusedisk\fR and
 134 thereby give user or group ownership for the mount to the nominated
 135 user or group.
 136
 137 .SH EXAMPLES
 138 This section illustrates uses of \fBfusefile\fR.
 139
 140 .SS Exanple 1.
 141 Insert a file "y" into a file "x" at position 1200.
 142 .RS
 143 \fB$ fusefile -ononempty x x/:1200 y x/1200:\fR
 144 .RE
 145 This also shadows the original file "x" and presents the fused file
 146 instead.
 147
 148 .SS Example 2.
 149 Make fused file y be a swap of the beginning and end of file "x", at
 150 position 2442.
 151 .RS
 152 \fB$ fusefile y x/2442: x/:2442\fR
 153 .RE
 154
 155 .SS Example 3.
 156 Replace partition 2 of an image file, \fIA\fR, with a different
 157 file, \fIX\fR. For this example the partition table looks as follows.
 158 .RS
 159 \fB$ partx -oNR,START,SECTORS \fIA\fR
 160     NR   START  SECTORS
 161      1    2048  2097152
 162      2 2099200   409600
 163      3 2508800 14268383
 164 .RE
 165 .br
 166 As each sector is 512 bytes the clipping points around partition 2 are
 167 1074790400 and 1284505600 and the insertion size is 209715200 bytes.
 168 The \fBfusefile\fR comman will therefore be as follows.
 169 .RS
 170 \fB$ fusefile -ononempty \fIA\fB \fIA\fB/:1074790400 \fIX\fB/:209715200 \fIA\fB/1284505600\fR
 171 .RE
 172 Note that the fused file shadows the original file \fIA\fR.
 173
 174 .SS Example 4.
 175 Protect raw disk image file with an overlay:
 176 .RS
 177 \fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
 178 .RE
 179 By that set up, the overlay file, "today", will protect the disk image
 180 file, "disk.raw" from changes, and also override the pathname
 181 "disk.raw" to be the fused file.
 182
 183 .SS Example 5.
 184 A fusefile mount with an \fIoverlay file\fR is writable regardless of
 185 the fused fragments, but all updates are written to the overlay file
 186 instead of to the fragments.
 187
 188 .RS
 189 \fB$ fusefile -ononempty \fIA\fR \fB-overlay:\fIB\fB \fIA\fR
 190 .RE
 191
 192 The overlay file, \fIB\fR in the example, contains all changes to the
 193 shadowed original file, \fIA\fR. The overlay file contains only the
 194 newly written regions and content is otherwise obtained from the
 195 original file.
 196
 197 To that end, the overlay file also contains a "marker table" at the
 198 end as if appended to the fused file. That part of the file is outside
 199 of the fused file; and it's simply an element count followed by pairs
 200 of byte addresses that tell which regions of the fused file have been
 201 captured into the overlay file. (The marker table is of course
 202 maintained so that adjoining regions are collapsed)
 203
 204 Thus, an overlay file may be reused to later re-establish the same
 205 fused file with overlay as previously, to continue capturing more
 206 changes.
 207
 208 .SS Example 6.
 209 As final example, we set up a fused block device \fIy\fR as a swap of
 210 the beginning and end of file "x", at position 2442:
 211 .RS
 212 \fB$ sudo fusedisk -ouid=1000 y x/2442: x/:2442\fR
 213 .RE
 214 Note the use of \fBsudo\fR for becoming \fIroot\fR, which is required
 215 for block device handling, and also the \fB-ouid=1000\fR option so as
 216 to make the block device \fIy\fR be owned by the user with id 1000.
 217
 218 .SH NOTES
 219
 220 \fBfusefile\fR opens the nominated source files before any bind
 221 mounting. With the fuse option \fI-ononempty\fR it will bind over an
 222 non-empty file, which may be useful. The source files remain open, but
 223 the source fragments are not recomputed. If a source file changes the
 224 fused file will present the new content. If a source is reduced in
 225 size, access will be inconsistent.
 226
 227 If the mountpoint file doesn't exist, then \fBfusefile\fR creates it.
 228
 229 Unmounting is done with "\fBfusermount -u\fR \fImountpoint\fR" as
 230 usual. A \fBfusedisk\fR mount is unmounted by \fIroot\fR using
 231 \fBumount\fR.
 232
 233 .SH SEE ALSO
 234 \fBfuse, fusermount, mount, dmsetup\fR
 235
 236 .SH AUTHOR
 237
 238 Ralph Rönnquist <ralph.ronnquist@gmail.com>.
 239