X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=fusefile.8;h=148609b6086083a005c56c1febbeded0c902569e;hb=fd4646a864893c598888ff36dbb8c13a4e424808;hp=4baf0a98a08dc55790b0383ecee6514f8d2307b3;hpb=55b2774b3ac5f48aca48f18d3aa3f49a7ba621a6;p=rrq%2Ffusefile.git diff --git a/fusefile.8 b/fusefile.8 index 4baf0a9..148609b 100644 --- a/fusefile.8 +++ b/fusefile.8 @@ -1,81 +1,160 @@ .mso www.tmac .TH fusefile 8 .SH NAME -fusefile \- FUSE file mount for combining file fragments read-only +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 -\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. +\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). The fragment arguments include the filename of a source file, and optionally start and end byte positions. All in all there five variations: + .TP -\fIfilename\fR -include all of the file. -.TP -\fIfilename/\fR -include all of the file named with "/" in the pathname. This case -requires a final "/", since the last "/" separates the filename from -the position details. -.TP -\fIfilename/from\fR -include the file from the given start position, to end. +\fIfilename\fR or \fIfilename/\fR +include all of the file. A pathname that includes "/" must be ended +with an extra "/" since that last "/" separates the filename from the +range detail. + .TP -\fIfilename/-to\fR -include the file from beginning to the given end position (not -included). +\fIfilename/start:end\fR +include the range from the given start to end. Either "start" or "end" +or both may be omitted, to mean the beginning and end of the file +respectively. If "start" or "end" are less than 0 then it means +relative to the end of the file. + .TP -\fIfilename/from-to\fR -include the file from the given start position, up to the given end -position (not included). +\fIfilename/start+length\fR +include "length" bytes from the given start. A negative "start" means +relative to the end of the file. If "length" is negative or omitted it +means that position relative to the end. + .TP -\fBpad=\fIfilename\fR +\fIfilename/start\fR include bytes from the given start. This is the +same as "/start+" -when this is given as first argument, the fused file is set up as a -writable random-access file, where the write events are captured -appended to the nominated "pad" file. The new content is inserted into -the fused file but not the original files, and fragments are split up -and adjusted as needed so as to make the write events appear as -insertions inteo the fused file. +.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. + +.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: .RS -\fB$ fusefile -ononempty x x/-1200 y x/1200\fR +\fB$ fusefile -ononempty x x/:1200 y x/1200:\fR .RE The bind mount shadows the original file "x", and presents the -composite instead. +fused file instead. + +Make fused file y be a swap of the beginning and end of file "x", at +position 2442: +.RS +\fB$ fusefile y x/2442: x/:2442\fR +.RE -Make file y be a swap of the beginning and end of file "x", at position 2442: +Replace a partition in an image file with a different file .RS -\fB$ fusefile y x/2442 x/-2442\fR +# 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(s) 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 or reduces in size, anything may happen. +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. + +If the mountpoint file doesn't exist, then \fBfusefile\fR creates it. -If the mountpoint file doesn't exist, then \fBfusefile\fR creates it, -and removes it when unmounted. +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. -When a "pad" file is used, it is updated as a simple archive where -each write event is a new member appended at the end. Each "pad" -member has a prefix of two newline-terminated text lines telling the -insertion position and the member size (both as ascii decimal digits), -before the actual insertion event content. +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 Rönnquist . +