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 .B fusedisk \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
   9
  10 .SH DESCRIPTION
  11
  12 \fBfusefile\fR is FUSE file mount that presents a series of fragments
  13 of other files as a contiguous concatenation. It bind mounts a driver
  14 on top of the file mountpoint to present the nominated file fragments
  15 as a single, contiguous file. It accepts over-writing on the fused
  16 file which gets distributed accordingly to the fragments, but cannot
  17 change size.
  18
  19 An optional overlay file is declared with an
  20 \fB-overlay:\fIfilename\fR argument between the mount point and the
  21 fragments. This file is then set up as an overlay for capturing writes
  22 to the fused file. The overlay file will contain the written fused
  23 file regions, followed by meta data to distinguish between written
  24 content and "holes" (where content comes from the fused fragments).
  25
  26 The fragment arguments include the filename of a source file, and
  27 optionally start and end byte positions. All in all there five
  28 variations:
  29
  30 .TP
  31 \fIfilename\fR or \fIfilename/\fR
  32 include all of the file. A pathname that includes "/" must be ended
  33 with an extra "/" since that last "/" separates the filename from the
  34 range detail.
  35
  36 .TP
  37 \fIfilename/start:end\fR
  38 include the range from the given start to end. Either "start" or "end"
  39 or both may be omitted, to mean the beginning and end of the file
  40 respectively. If "start" or "end" are less than 0 then it means
  41 relative to the end of the file.
  42
  43 .TP
  44 \fIfilename/start+length\fR
  45 include "length" bytes from the given start. A negative "start" means
  46 relative to the end of the file. If "length" is negative or omitted it
  47 means that position relative to the end.
  48
  49 .TP
  50 \fIfilename/start\fR include bytes from the given start. This is the
  51 same as "/start+"
  52
  53 .P
  54 Note that a negative start position is clipped to 0 and a too large
  55 end position is clipped to the end of the file.
  56
  57 .P
  58 Charater devices are treated as being of any given finite size, but
  59 have size 0 by default. For example, "/dev/zero/:100" means a fragment
  60 of 100 NUL bytes.
  61
  62 \fBfusedisk\fR is a helper script to set up a fused file as a block
  63 device. This uses the device mapper (\fBdmsetup\fR) to manage empty
  64 block device mappings where content is handled via \fBfusefile\fR.
  65
  66 .SH EXAMPLES
  67
  68 Insert file "y" into file "x" at position 1200:
  69 .RS
  70 \fB$ fusefile -ononempty x x/:1200 y x/1200:\fR
  71 .RE
  72 The bind mount shadows the original file "x", and presents the
  73 fused file instead.
  74
  75 Make fused file y be a swap of the beginning and end of file "x", at
  76 position 2442:
  77 .RS
  78 \fB$ fusefile y x/2442: x/:2442\fR
  79 .RE
  80
  81 Replace a partition in an image file with a different file
  82 .RS
  83 # Check the partition table
  84 .br
  85 \fB$ partx -oNR,START,SECTORS disk.raw\fR
  86     NR   START  SECTORS
  87      1    2048  2097152
  88      2 2099200   409600
  89      3 2508800 14268383
  90 .br
  91 # Replace partition 2 of 409600 sectors from 2099200 with
  92 .br
  93 # the file "insert.fat" clipped to 409600 sectors.
  94 .br
  95 \fB$ fusefile -ononempty disk.raw \\
  96          disk.raw/0:$(( 2099200*512 )) \\
  97          insert.fat/0:$(( 409600*512 )) \\
  98          disk.raw/$(( (2099200+409600)*512 )):\fR
  99 .RE
 100
 101 Protect raw disk image file with an overlay:
 102 .RS
 103 \fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
 104 .RE
 105 By that set up, the overlay file, "today", will protect the disk image
 106 file, "disk.raw" from changes, and also override the pathname
 107 "disk.raw" to be the fused file.
 108
 109 As final example, make a fused block device y as a swap of the
 110 beginning and end of file "x", at position 2442:
 111 .RS
 112 \fB$ sudo fusedisk -ouid=1000 y x/2442: x/:2442\fR
 113 .RE
 114 Note the use of \fBsudo\fR for becoming \fIroot\fR, which is required
 115 for block device handling, and also the \fB-ouid=1000\fR option so as
 116 to make the block device \fIy\fR be owned by the user with id 1000.
 117
 118 .SH NOTES
 119
 120 Note that \fBfusefile\fR opens the nominated source file or files
 121 before bind mounting. With the fuse option \fI-ononempty\fR it will
 122 bind over an non-empty file, which may be useful. The source file
 123 descriptors remain open, but the source fragments are not recomputed.
 124 If a source file changes the fused file will present the new content.
 125 If a source is reduced in size, access will be inconsistent.
 126
 127 If the mountpoint file doesn't exist, then \fBfusefile\fR creates it.
 128
 129 The fuse option \fI-oallow_other\fR is needed for sharing the fused
 130 file with other users (including "root"). Note however that this
 131 option must first be enabled in \fI/etc/fuse.conf\fR.
 132
 133 Unmount is done with "\fBfusermount -u\fR \fImountpoint\fR" as usual.
 134
 135 .P
 136 \fBUsing overlay file\fR
 137
 138 .P
 139 A fusefile mount with an \fIoverlay file\fR is writable regardless of
 140 the fused fragments, but all updates are written to the overlay file
 141 instead of to the fragments.
 142
 143   $ fusefile -oallow_other -ononempty disk.raw \fB-overlay:today\fR disk.raw
 144
 145 The overlay file ("today" in the example) contains all changes to the
 146 original file ("disk.raw" in the exmaple). It also contains a marker
 147 table at the end, as if appended to the fused file. This part of the
 148 overlay file is outside of the fused file; it consists of an element
 149 count followed by pairs of byte addresses to mark out which regions
 150 have been written into the overlay file, and the marker table is
 151 maintained so that adjoining regions are collapsed.
 152
 153 That means that an overlay file may be reused to later re-establish
 154 the same fused file with overlay as previously, to continue capturing
 155 more changes.
 156
 157 .SH AUTHOR
 158
 159 Ralph Rönnquist <ralph.ronnquist@gmail.com>.
 160