From: Ralph Ronnquist Date: Thu, 25 May 2023 06:01:04 +0000 (+1000) Subject: editorial improvments and polishing X-Git-Tag: 1.0~1^2~17 X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=a934a4cb033e4df2a83fa23c265dcf14af0bb965;p=rrq%2Ffusefile.git editorial improvments and polishing --- diff --git a/fusefile.8 b/fusefile.8 index 148609b..3954389 100644 --- a/fusefile.8 +++ b/fusefile.8 @@ -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