4 fusefile, fusedisk \- FUSE file mount for combining file fragments
7 .B fusefile \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
9 .B fusefile \fB-dump\fR \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
11 .B fusefile \fB-push\fR \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
13 .B fusedisk \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
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.
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.
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
36 By instead using the \fB-overlay:\fIlist\fR argument where \fIlist\fR
37 is a colon-separated list of filenames, \fBfusefile\fR will use those
38 as an ordered stack of overlays and "inject" them as fragments on top
41 The option \fB-dump\fR as first argument together with a fusefile
42 setup will print the setup to standard output rather than establishing
43 a fusefile mount. This is of most use with a prior overlay setup where
44 then the printout includes the portions of updates that have been
45 captured in the overlay. The printout is the series of fusefile
46 fragment argments to give in order to intersperse the captured overlay
47 portions according to the overlay table.
49 The option \fB-push\fR as first argument together with a fusefile
50 setup will push the overlay into the sources (except for
51 write-protected fragments). This is only of use with a prior overlay
52 setup where then the updates that have been captured in the overlay
53 get pushed into the fragments.
55 \fBfusedisk\fR is a helper script to set up a \fBfusefile\fR as a
56 block device (via \fIfuseblk\fR) by using the device mapper
57 (\fBdmsetup\fR) to manage an empty block device mapping where content
58 is handled at the mountpoint via \fBfusefile\fR. (Note that the same
59 thing may be done with the device manager directly, but then all
60 fragments need to be in sectors of N*512 bytes whereas with
61 \fBfusedisk\fR, only the fused file as a whole is "clipped" at nearest
62 N*512 bytes below actual size)
64 .SH FRAGMENT ARGUMENTS
66 The fragment arguments include the filename of a source file, and
67 optionally start and end byte positions. All in all there five
71 \fIfilename\fR or \fIfilename/\fR
72 include all of the file. A pathname that includes "/" must be ended
73 with an extra "/" since that last "/" separates the filename from the
77 \fIfilename/start:end\fR
78 include the range from the given start to end. Either "start" or "end"
79 or both may be omitted, to mean the beginning and end of the file
80 respectively. If "start" or "end" are less than 0 then it means
81 relative to the end of the file.
84 \fIfilename/start+length\fR
85 include "length" bytes from the given start. A negative "start" means
86 relative to the end of the file. If "length" is negative or omitted it
87 means that position relative to the end.
90 \fIfilename/start\fR include bytes from the given start. This is the
94 Note that a negative start position is clipped to 0 and a too large
95 end position is clipped to the end of the file.
98 Character devices are treated as being of any given finite size, but
99 have size 0 by default. For example, "/dev/zero/:100" means a fragment
104 This section enumerates the most interesting options to use with
105 \fBfuesfile\fR. See "man fuse" and "man mount" for more options.
110 The \fB-dump\fR "option" tells \fBfusefile\fR to print out the
111 applicable fragment sequence for the current setup, including the
112 overlay table, if any. The printout is done instead of setting up a
116 \fB-o\fIallow_other\fB
118 The fuse option \fI-oallow_other\fR is needed for sharing the fused
119 file with other users who otherwise will not have access to it
120 (including "root"). Note however that this must first be enabled in
121 \fI/etc/fuse.conf\fR.
126 The fuse option \fI-ononempty\fR may need to be used when reusing an
127 existing file as mountpoint.
130 \fB-o\fIuid=...\fR and \fB-o\fIgid=...\fR,
132 These mount options, where \fI...\fR is a user or group id
133 respectively, are useful for root when using \fBfusedisk\fR and
134 thereby give user or group ownership for the mount to the nominated
138 This section illustrates uses of \fBfusefile\fR.
141 Insert a file "y" into a file "x" at position 1200.
143 \fB$ fusefile -ononempty x x/:1200 y x/1200:\fR
145 This also shadows the original file "x" and presents the fused file
149 Make fused file y be a swap of the beginning and end of file "x", at
152 \fB$ fusefile y x/2442: x/:2442\fR
156 Replace partition 2 of an image file, \fIA\fR, with a different
157 file, \fIX\fR. For this example the partition table looks as follows.
159 \fB$ partx -oNR,START,SECTORS \fIA\fR
166 As each sector is 512 bytes the clipping points around partition 2 are
167 1074790400 and 1284505600 and the insertion size is 209715200 bytes.
168 The \fBfusefile\fR comman will therefore be as follows.
170 \fB$ fusefile -ononempty \fIA\fB \fIA\fB/:1074790400 \fIX\fB/:209715200 \fIA\fB/1284505600\fR
172 Note that the fused file shadows the original file \fIA\fR.
175 Protect raw disk image file with an overlay:
177 \fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
179 By that set up, the overlay file, "today", will protect the disk image
180 file, "disk.raw" from changes, and also override the pathname
181 "disk.raw" to be the fused file.
184 A fusefile mount with an \fIoverlay file\fR is writable regardless of
185 the fused fragments, but all updates are written to the overlay file
186 instead of to the fragments.
189 \fB$ fusefile -ononempty \fIA\fR \fB-overlay:\fIB\fB \fIA\fR
192 The overlay file, \fIB\fR in the example, contains all changes to the
193 shadowed original file, \fIA\fR. The overlay file contains only the
194 newly written regions and content is otherwise obtained from the
197 To that end, the overlay file also contains a "marker table" at the
198 end as if appended to the fused file. That part of the file is outside
199 of the fused file; and it's simply an element count followed by pairs
200 of byte addresses that tell which regions of the fused file have been
201 captured into the overlay file. (The marker table is of course
202 maintained so that adjoining regions are collapsed)
204 Thus, an overlay file may be reused to later re-establish the same
205 fused file with overlay as previously, to continue capturing more
209 As final example, we set up a fused block device \fIy\fR as a swap of
210 the beginning and end of file "x", at position 2442:
212 \fB$ sudo fusedisk -ouid=1000 y x/2442: x/:2442\fR
214 Note the use of \fBsudo\fR for becoming \fIroot\fR, which is required
215 for block device handling, and also the \fB-ouid=1000\fR option so as
216 to make the block device \fIy\fR be owned by the user with id 1000.
220 \fBfusefile\fR opens the nominated source files before any bind
221 mounting. With the fuse option \fI-ononempty\fR it will bind over an
222 non-empty file, which may be useful. The source files remain open, but
223 the source fragments are not recomputed. If a source file changes the
224 fused file will present the new content. If a source is reduced in
225 size, access will be inconsistent.
227 If the mountpoint file doesn't exist, then \fBfusefile\fR creates it.
229 Unmounting is done with "\fBfusermount -u\fR \fImountpoint\fR" as
230 usual. A \fBfusedisk\fR mount is unmounted by \fIroot\fR using
234 \fBfuse, fusermount, mount, dmsetup\fR
238 Ralph Rönnquist <ralph.ronnquist@gmail.com>.