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