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 fusedisk \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
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.
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)
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
38 The option \fB-dump\fR together with an overlay fusefile setup will
39 print the current overlay table to standard output rather than
40 establishing a fusefile mount. The table is printed as the series of
41 fusefile fragments using the argments as given.
43 .SH FRAGMENT ARGUMENTS
45 The fragment arguments include the filename of a source file, and
46 optionally start and end byte positions. All in all there five
50 \fIfilename\fR or \fIfilename/\fR
51 include all of the file. A pathname that includes "/" must be ended
52 with an extra "/" since that last "/" separates the filename from the
56 \fIfilename/start:end\fR
57 include the range from the given start to end. Either "start" or "end"
58 or both may be omitted, to mean the beginning and end of the file
59 respectively. If "start" or "end" are less than 0 then it means
60 relative to the end of the file.
63 \fIfilename/start+length\fR
64 include "length" bytes from the given start. A negative "start" means
65 relative to the end of the file. If "length" is negative or omitted it
66 means that position relative to the end.
69 \fIfilename/start\fR include bytes from the given start. This is the
73 Note that a negative start position is clipped to 0 and a too large
74 end position is clipped to the end of the file.
77 Character devices are treated as being of any given finite size, but
78 have size 0 by default. For example, "/dev/zero/:100" means a fragment
83 This section enumerates the most interesting options to use with
84 \fBfuesfile\fR. See "man fuse" and "man mount" for more options.
89 The fuse option \fI-oallow_other\fR is needed for sharing the fused
90 file with other users who otherwise will not have access to it
91 (including "root"). Note however that this must first be enabled in
97 The fuse option \fI-ononempty\fR may need to be used when reusing an
98 existing file as mountpoint.
101 \fI-ouid=...\fR, \fI-ogid=...\fR,
103 The mount options \fI-ouid=...\fR and \fI-ogid=...\fR, where \fI...\fR
104 is a user or group id respectively, are useful for root when using
105 \fBfusedisk\fR and thereby give user or group ownership for the mount
106 to the nominated user or group.
111 This "mount option" triggers fusefil to, instead of setting up a mount
112 point, print out the applicable fusefile fragment sequence for the
113 current setup as way of presenting the overlay table.
116 This section illustrates uses of \fBfusefile\fR.
119 Insert a file "y" into a file "x" at position 1200.
121 \fB$ fusefile -ononempty x x/:1200 y x/1200:\fR
123 This also shadows the original file "x" and presents the fused file
127 Make fused file y be a swap of the beginning and end of file "x", at
130 \fB$ fusefile y x/2442: x/:2442\fR
134 Replace partition 2 of an image file, \fIA\fR, with a different
135 file, \fIX\fR. For this example the partition table looks as follows.
137 \fB$ partx -oNR,START,SECTORS \fIA\fR
144 As each sector is 512 bytes the clipping points around partition 2 are
145 1074790400 and 1284505600 and the insertion size is 209715200 bytes.
146 The \fBfusefile\fR comman will therefore be as follows.
148 \fB$ fusefile -ononempty \fIA\fB \fIA\fB/:1074790400 \fIX\fB/:209715200 \fIA\fB/1284505600\fR
150 Note that the fused file shadows the original file \fIA\fR.
153 Protect raw disk image file with an overlay:
155 \fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
157 By that set up, the overlay file, "today", will protect the disk image
158 file, "disk.raw" from changes, and also override the pathname
159 "disk.raw" to be the fused file.
162 A fusefile mount with an \fIoverlay file\fR is writable regardless of
163 the fused fragments, but all updates are written to the overlay file
164 instead of to the fragments.
167 \fB$ fusefile -ononempty \fIA\fR \fB-overlay:\fIB\fB \fIA\fR
170 The overlay file, \fIB\fR in the example, contains all changes to the
171 shadowed original file, \fIA\fR. The overlay file contains only the
172 newly written regions and content is otherwise obtained from the
175 To that end, the overlay file also contains a "marker table" at the
176 end as if appended to the fused file. That part of the file is outside
177 of the fused file; and it's simply an element count followed by pairs
178 of byte addresses that tell which regions of the fused file have been
179 captured into the overlay file. (The marker table is of course
180 maintained so that adjoining regions are collapsed)
182 Thus, an overlay file may be reused to later re-establish the same
183 fused file with overlay as previously, to continue capturing more
187 As final example, we set up a fused block device \fIy\fR as a swap of
188 the beginning and end of file "x", at position 2442:
190 \fB$ sudo fusedisk -ouid=1000 y x/2442: x/:2442\fR
192 Note the use of \fBsudo\fR for becoming \fIroot\fR, which is required
193 for block device handling, and also the \fB-ouid=1000\fR option so as
194 to make the block device \fIy\fR be owned by the user with id 1000.
198 \fBfusefile\fR opens the nominated source files before any bind
199 mounting. With the fuse option \fI-ononempty\fR it will bind over an
200 non-empty file, which may be useful. The source files remain open, but
201 the source fragments are not recomputed. If a source file changes the
202 fused file will present the new content. If a source is reduced in
203 size, access will be inconsistent.
205 If the mountpoint file doesn't exist, then \fBfusefile\fR creates it.
207 Unmounting is done with "\fBfusermount -u\fR \fImountpoint\fR" as
208 usual. A \fBfusedisk\fR mount is unmounted by \fIroot\fR using
212 \fBfuse, fusermount, mount, dmsetup\fR
216 Ralph Rönnquist <ralph.ronnquist@gmail.com>.