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