rrq
/
fusefile
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity
Browse Source

editorial improvments and polishing

suites/experimental
Ralph Rönnquist 4 months ago
parent
ec9fd496f3
commit
a934a4cb03
Signed by: rrq GPG Key ID: 7729547634107541
1 changed files with 112 additions and 67 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 179
      fusefile.8

179
fusefile.8
View File

@ -5,23 +5,37 @@ fusefile, fusedisk \- FUSE file mount for combining file fragments
.SH SYNOPSIS
.B fusefile \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
.br
.B fusedisk \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
.SH DESCRIPTION
\fBfusefile\fR is FUSE file mount that presents a series of fragments
of other files as a contiguous concatenation. It bind mounts a driver
on top of the file mountpoint to present the nominated file fragments
as a single, contiguous file. It accepts over-writing on the fused
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).
\fBfusefile\fR is a FUSE file mount that presents a series of
fragments of other files as a contiguous concatenation. It bind mounts
a driver on top of the file mountpoint to present the nominated file
fragments as a single, contiguous file. \fBfusefile\fR accepts
over-writing on the fused file (i.e. the mountpoint) which gets
distributed accordingly to the fragments, but it cannot change size;
any writing thus merely replaces content without truncating fragments.
All fragment files are held open while \fBfusefile\fR is active.
\fBfusedisk\fR is a helper script to set up a \fBfusefile\fR as a
block device (via \fIfuseblk\fR) by using the device mapper
(\fBdmsetup\fR) to manage an empty block device mapping where content
is handled at the mountpoint via \fBfusefile\fR. (Note that the same
thing may be done with the device manager directly, but then all
fragments need to be in sectors of N*512 bytes. With \fBfusedisk\fR
only the fused file as a whole is "clipped" at N*512 bytes)
By using the optional \fB-overlay:\fIfilename\fR argument between the
mount point and the fragments, an overlay file may be set up. The
overlay file will then be used by \fBfusefile\fR for capturing writes
to the fused file (i.e. the mountpoint). The overlay file will contain
any new written fused file regions followed by meta data to
distinguish between new, written content and old content that comes
from the fragments.
.SH FRAGMENT ARGUMENTS
The fragment arguments include the filename of a source file, and
optionally start and end byte positions. All in all there five
@ -55,49 +69,75 @@ Note that a negative start position is clipped to 0 and a too large
end position is clipped to the end of the file.
.P
Charater devices are treated as being of any given finite size, but
Character 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 OPTIONS
This section enumerates the most interesting options to use with
\fBfuesfile\fR. See "man fuse" and "man mount" for more options.
.TP
\fI-oallow_other\fB
The fuse option \fI-oallow_other\fR is needed for sharing the fused
file with other users who otherwise will not have access to it
(including "root"). Note however that this must first be enabled in
\fI/etc/fuse.conf\fR.
.TP
\fI-ononempty\fR
The fuse option \fI-ononempty\fR may need to be used when reusing an
existing file as mountpoint.
.TP
\fI-ouid=...\fR, \fI-ogid=...\fR,
The mount options \fI-ouid=...\fR and \fI-ogid=...\fR, where \fI...\fR
is a user or group id respectively, are useful for root when using
\fBfusedisk\fR and thereby give user or group ownership for the mount
to the nominated user or group.
.SH EXAMPLES
This section illustrates uses of \fBfusefile\fR.
Insert file "y" into file "x" at position 1200:
.SS Exanple 1.
Insert a file "y" into a file "x" at position 1200.
.RS
\fB$ fusefile -ononempty x x/:1200 y x/1200:\fR
.RE
The bind mount shadows the original file "x", and presents the
fused file instead.
This also shadows the original file "x" and presents the fused file
instead.
.SS Example 2.
Make fused file y be a swap of the beginning and end of file "x", at
position 2442:
position 2442.
.RS
\fB$ fusefile y x/2442: x/:2442\fR
.RE
Replace a partition in an image file with a different file
.SS Example 3.
Replace partition 2 of an image file, \fIA\fR, with a different
file, \fIX\fR. For this example the partition table looks as follows.
.RS
# Check the partition table
.br
\fB$ partx -oNR,START,SECTORS disk.raw\fR
\fB$ partx -oNR,START,SECTORS \fIA\fR
NR START SECTORS
1 2048 2097152
2 2099200 409600
3 2508800 14268383
.RE
.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
As each sector is 512 bytes the clipping points around partition 2 are
1074790400 and 1284505600 and the insertion size is 209715200 bytes.
The \fBfusefile\fR comman will therefore be as follows.
.RS
\fB$ fusefile -ononempty \fIA\fB \fIA\fB/:1074790400 \fIX\fB/:209715200 \fIA\fB/1284505600\fR
.RE
Note that the fused file shadows the original file \fIA\fR.
.SS Example 4.
Protect raw disk image file with an overlay:
.RS
\fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
@ -106,8 +146,34 @@ 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:
.SS Example 5.
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.
.RS
\fB$ fusefile -ononempty \fIA\fR \fB-overlay:\fIB\fB \fIA\fR
.RE
The overlay file, \fIB\fR in the example, contains all changes to the
shadowed original file, \fIA\fR. The overlay file contains only the
newly written regions and content is otherwise obtained from the
original file.
To that end, the overlay file also contains a "marker table" at the
end as if appended to the fused file. That part of the file is outside
of the fused file; and it's simply an element count followed by pairs
of byte addresses that tell which regions of the fused file have been
captured into the overlay file. (The marker table is of course
maintained so that adjoining regions are collapsed)
Thus, an overlay file may be reused to later re-establish the same
fused file with overlay as previously, to continue capturing more
changes.
.SS Example 6.
As final example, we set up a fused block device \fIy\fR 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
@ -117,42 +183,21 @@ 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
before bind mounting. With the fuse option \fI-ononempty\fR it will
bind over an non-empty file, which may be useful. The source file
descriptors remain open, but the source fragments are not recomputed.
If a source file changes the fused file will present the new content.
If a source is reduced in size, access will be inconsistent.
\fBfusefile\fR opens the nominated source files before any bind
mounting. With the fuse option \fI-ononempty\fR it will bind over an
non-empty file, which may be useful. The source files remain open, but
the source fragments are not recomputed. 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.
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.
Unmounting is done with "\fBfusermount -u\fR \fImountpoint\fR" as
usual. A \fBfusedisk\fR mount is unmounted by \fIroot\fR using
\fBumount\fR.
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 SEE ALSO
\fBfuse, fusermount, mount, dmsetup\fR
.SH AUTHOR

Write Preview
Loading…
Cancel
Save