From b6423d19461b33da65b64aacc6c5ebbdc176d9e0 Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Sat, 28 Oct 2023 10:23:07 +1100 Subject: [PATCH] Added man page for merge-overlay --- merge-overlay.8 | 126 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 merge-overlay.8 diff --git a/merge-overlay.8 b/merge-overlay.8 new file mode 100644 index 0000000..549e9ec --- /dev/null +++ b/merge-overlay.8 @@ -0,0 +1,126 @@ +.mso www.tmac +.TH merge-overlay 8 +.SH NAME +merge-overlay \- Utility to "merge down" a fusefile overlay. + +.SH SYNOPSIS +.B merge-overlay \fIfusefile\fR \fIoverlayfile\fR + +.SH DESCRIPTION + +\fBmerge-overlay\fR is an administration utility for writing the data +blocks of a fusefile overlay into a current fusefile (or ordinary file +of matching size). + +.SH EXAMPLE + +This section illustrates a use of \fBmerge-overlay\fR via a use case +scenario that involves a succession of steps where \fBfusefile\fR is +used with successive overlays for the purpose of capturing revisions +of a fused file. Notably the fusefile must be of the same size +throughout the scenario, and in this example case it is a raw disk +image file, \fIvm.raw\fR, for a virtual machine. + +.SS first day +First a file \fIa\fR is set up as overlay for \fIvm.raw\fR to be +\fIvmx.raw\fR for use during the day, and then the fusefile is torn +down at the end of the day. +.RS +\fB$ fusefile \fIvmx.raw\fB +-overlay:\fIa\fB +\fIvm.raw\fR +.RE +.RS +\fB$\fR ... using \fIvmx.raw\fR for the virtual machine ... +.RE +.RS +\fB$ umount -u \fIvmx.raw\fR +.RE +By doing so, \fIvmx.raw\fR represents the original image file +\fIvm.raw\fR initially but changes (i.e. data writes) are collated +into the overlay file \fIa\fR while \fIvm.raw\fR remains unchanged. + +.SS second day +The next day file \fIb\fR is set up as overlay stacked over \fIa\fR +for \fIvm.raw\fR to again be \fIvmx.raw\fR. Then that is used over the +day before the fusefile is torn down at the end of the day. +.RS +\fB$ fusefile \fIvmx.raw\fB +-overlay:\fIa\fB:\fIb\fB +\fIvm.raw\fR +.RE +.RS +\fB$\fR ... using \fIvmx.raw\fR for the virtual machine ... +.RE +.RS +\fB$ umount -u \fIvmx.raw\fR +.RE +By doing so, \fIvmx.raw\fR represents the original image file +\fIvm.raw\fR including yesterday's changes collated in \fIa\fR, and +any further changes are collated into the overlay file \fIb\fR while +both \fIvm.raw\fR and \fIa\fR remain unchanged. + +.SS some days later +By adding an additional overlay each day, at the end of the sixth day +there is a stack of overlays, +\fIa\fR:\fIb\fR:\fIc\fR:\fId\fR:\fIe\fR:\fIf\fR. Here the last overlay +file \fIf\R has the last day's changes relative the overkay stack +\fIa\fR:\fIb\fR:\fIc\fR:\fId\fR:\fIe\fR and so forth. + +One may now wish to, say, merge \fIa\fR:\fIb\fR:\fIc\fR into a single +overlay file \fIA\fR, and \fId\fR:\fIe\fR:\fIf\fR into another file +\fIB\fR. This could be done as follows: + +.RS +### First merge \fIa\fR, \fIb\fR and \fIc\fR into \fIA\fR +.RE +.RS +\fB$ fusefile \fIvmx.raw\fB -overlay:\fIA\fB \fIvm.raw\fR +.RE +.RS +\fB$ merge-overlay \fIvmx.raw\fB \fIa\fR +.RE +.RS +\fB$ merge-overlay \fIvmx.raw\fB \fIb\fR +.RE +.RS +\fB$ merge-overlay \fIvmx.raw\fB \fIc\fR +.RE +.RS +\fB$ umount -u \fIvmx.raw\fR +.RE + +.RS +### Second merge \fId\fE, \fIe\fR and \fIf\fR into \fIB\fR +.RE +.RS +\fB$ fusefile \fIvmx.raw\fB +-overlay:\fIA\fB:\fIB\fB +\fIvm.raw\fR +.RE +.RS +\fB$ for f in \fId\fB \fIe\fB \fIf\fB ; do +merge-overlay \fIvmx.raw\fB $f ; done\fR +.RE +.RS +\fB$ umount -u \fIvmx.raw\fR +.RE +Note that including \fIA\fR for the second fusefile setup is not +needed for the merging but it's will be needed for using \fIvmx.raw\fR +further used after the merge. + +.SH NOTES + +The fusefile overlay file contains the written data only; it does not +track the order of changes but rather only keeps the last written data +blocks, which also are combined into larger blocks when possible. The +merging of this means to write the resulting blocks into the target +file in order of byte positions. + +.SH SEE ALSO + +.B fusefile + +.SH COPYRIGHT + +Copyright 2023 Ralph Rönnquist -- 2.39.2