.mso www.tmac
.TH fusefile 8
.SH NAME
-fusefile \- FUSE file mount for combining file fragments
+fusefile, fusedisk \- FUSE file mount for combining file fragments
.SH SYNOPSIS
-.B fusefile \fR[fuse options\fR] \fBmountpoint\fR \fIfilename/from-to\fR ...
+.B fusefile \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
+.B fusedisk \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
.SH DESCRIPTION
file which gets distributed accordingly to the fragments, but cannot
change size.
+An optional overlay file is declared with an
+\fB-overlay:\fIfilename\fR argument between the mount point and the
+fragments. This file is then set up as an overlay for capturing writes
+to the fused file. The overlay file will contain the written fused
+file regions, followed by meta data to distinguish between written
+content and "holes" (where content comes from the fused fragments).
+
The fragment arguments include the filename of a source file, and
optionally start and end byte positions. All in all there five
variations:
means that position relative to the end.
.TP
-\fIfilename/start\fR
-include bytes from the given start. This is the same as "/start+"
+\fIfilename/start\fR include bytes from the given start. This is the
+same as "/start+"
.P
Note that a negative start position is clipped to 0 and a too large
-end position is clipped to the end of the file.
+end position is clipped to the end of the file.
.P
Charater devices are treated as being of any given finite size, but
have size 0 by default. For example, "/dev/zero/:100" means a fragment
of 100 NUL bytes.
+\fBfusedisk\fR is a helper script to set up a fused file as a block
+device. This uses the device mapper (\fBdmsetup\fR) to manage empty
+block device mappings where content is handled via \fBfusefile\fR.
+
.SH EXAMPLES
Insert file "y" into file "x" at position 1200:
\fB$ fusefile y x/2442: x/:2442\fR
.RE
+Replace a partition in an image file with a different file
+.RS
+# Check the partition table
+.br
+\fB$ partx -oNR,START,SECTORS disk.raw\fR
+ NR START SECTORS
+ 1 2048 2097152
+ 2 2099200 409600
+ 3 2508800 14268383
+.br
+# Replace partition 2 of 409600 sectors from 2099200 with
+.br
+# the file "insert.fat" clipped to 409600 sectors.
+.br
+\fB$ fusefile -ononempty disk.raw \\
+ disk.raw/0:$(( 2099200*512 )) \\
+ insert.fat/0:$(( 409600*512 )) \\
+ disk.raw/$(( (2099200+409600)*512 )):\fR
+.RE
+
+Protect raw disk image file with an overlay:
+.RS
+\fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
+.RE
+By that set up, the overlay file, "today", will protect the disk image
+file, "disk.raw" from changes, and also override the pathname
+"disk.raw" to be the fused file.
+
+As final example, make a fused block device y as a swap of the
+beginning and end of file "x", at position 2442:
+.RS
+\fB$ sudo fusedisk -ouid=1000 y x/2442: x/:2442\fR
+.RE
+Note the use of \fBsudo\fR for becoming \fIroot\fR, which is required
+for block device handling, and also the \fB-ouid=1000\fR option so as
+to make the block device \fIy\fR be owned by the user with id 1000.
+
.SH NOTES
Note that \fBfusefile\fR opens the nominated source file or files
If a source file changes the fused file will present the new content.
If a source is reduced in size, access will be inconsistent.
-If the mountpoint file doesn't exist, then \fBfusefile\fR creates it,
-and removes it when unmounted.
+If the mountpoint file doesn't exist, then \fBfusefile\fR creates it.
+
+The fuse option \fI-oallow_other\fR is needed for sharing the fused
+file with other users (including "root"). Note however that this
+option must first be enabled in \fI/etc/fuse.conf\fR.
+
+Unmount is done with "\fBfusermount -u\fR \fImountpoint\fR" as usual.
+
+.P
+\fBUsing overlay file\fR
+
+.P
+A fusefile mount with an \fIoverlay file\fR is writable regardless of
+the fused fragments, but all updates are written to the overlay file
+instead of to the fragments.
+
+ $ fusefile -oallow_other -ononempty disk.raw \fB-overlay:today\fR disk.raw
+The overlay file ("today" in the example) contains all changes to the
+original file ("disk.raw" in the exmaple). It also contains a marker
+table at the end, as if appended to the fused file. This part of the
+overlay file is outside of the fused file; it consists of an element
+count followed by pairs of byte addresses to mark out which regions
+have been written into the overlay file, and the marker table is
+maintained so that adjoining regions are collapsed.
+
+That means that an overlay file may be reused to later re-establish
+the same fused file with overlay as previously, to continue capturing
+more changes.
.SH AUTHOR
-Ralph Rönnquist <ralph.ronnquist@gmail.com>
+Ralph Rönnquist <ralph.ronnquist@gmail.com>.
+
projects / rrq / fusefile.git / blobdiff