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