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