X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=fusefile.8;h=b952f5574075e2ae9b0df699ead855873618a772;hb=HEAD;hp=e2577c195a4073653d7b64a8eb1481177f7a1ad9;hpb=5e65b7ecf2c54b600c5d98f06031ecf62e5a6cec;p=rrq%2Ffusefile.git diff --git a/fusefile.8 b/fusefile.8 index e2577c1..b952f55 100644 --- a/fusefile.8 +++ b/fusefile.8 @@ -1,69 +1,239 @@ .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 ... +.br +.B fusefile \fB-dump\fR \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ... +.br +.B fusefile \fB-push\fR \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. +\fBfusefile\fR is a FUSE \fIfile mount\fR that presents a series of +fragments of other files as a contiguous concatenation. Technically it +bind mounts a driver on top of the filename mountpoint to provide +access to the given file fragments as if in 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 +neither the fused file nor the fragments can change size; any writing +thus merely over-writes content without truncating fragments. All +fragment files are held open while \fBfusefile\fR is active. + +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. + +By instead using the \fB-overlay:\fIlist\fR argument where \fIlist\fR +is a colon-separated list of filenames, \fBfusefile\fR will use those +as an ordered stack of overlays and "inject" them as fragments on top +of each other. + +The option \fB-dump\fR as first argument together with a fusefile +setup will print the setup to standard output rather than establishing +a fusefile mount. This is of most use with a prior overlay setup where +then the printout includes the portions of updates that have been +captured in the overlay. The printout is the series of fusefile +fragment argments to give in order to intersperse the captured overlay +portions according to the overlay table. + +The option \fB-push\fR as first argument together with a fusefile +setup will push the overlay into the sources (except for +write-protected fragments). This is only of use with a prior overlay +setup where then the updates that have been captured in the overlay +get pushed into the fragments. + +\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 whereas with +\fBfusedisk\fR, only the fused file as a whole is "clipped" at nearest +N*512 bytes below actual size) + +.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 variations: + +.TP +\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/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\fR -include all of the file. +\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 -\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. +\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. + +.P +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. + +.SH OPTIONS + +This section enumerates the most interesting options to use with +\fBfuesfile\fR. See "man fuse" and "man mount" for more options. + .TP -\fIfilename/from\fR -include the file from the given start position, to end. +\fB-dump\fR + +The \fB-dump\fR "option" tells \fBfusefile\fR to print out the +applicable fragment sequence for the current setup, including the +overlay table, if any. The printout is done instead of setting up a +mount point. + .TP -\fIfilename/-to\fR -include the file from beginning to the given end position (not -included). +\fB-o\fIallow_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 -\fIfilename/from-to\fR -include the file from the given start position, up to the given end -position (not included). +\fB-o\fInonempty\fR + +The fuse option \fI-ononempty\fR may need to be used when reusing an +existing file as mountpoint. + +.TP +\fB-o\fIuid=...\fR and \fB-o\fIgid=...\fR, + +These mount options, 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. + +.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 +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. +.RS +\fB$ fusefile y x/2442: x/:2442\fR +.RE -Insert file "y" into file "x" at position 1200: +.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 +\fB$ partx -oNR,START,SECTORS \fIA\fR + NR START SECTORS + 1 2048 2097152 + 2 2099200 409600 + 3 2508800 14268383 +.RE +.br +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 x x/-1200 y x/1200\fR +\fB$ fusefile -ononempty \fIA\fB \fIA\fB/:1074790400 \fIX\fB/:209715200 \fIA\fB/1284505600\fR .RE -The bind mount shadows the original file "x", and presents the -composite instead. +Note that the fused file shadows the original file \fIA\fR. -Make file y be a swap of the beginning and end of file "x", at position 2442: +.SS Example 4. +Protect raw disk image file with an overlay: .RS -\fB$ fusefile y x/2442 x/-2442\fR +\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. + +.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 +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 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. -If the mountpoint file doesn't exist, then \fBfusefile\fR creates it, -and removes it when unmounted. +Unmounting is done with "\fBfusermount -u\fR \fImountpoint\fR" as +usual. A \fBfusedisk\fR mount is unmounted by \fIroot\fR using +\fBumount\fR. + +.SH SEE ALSO +\fBfuse, fusermount, mount, dmsetup\fR .SH AUTHOR -Ralph Rönnquist +Ralph Rönnquist . +