merge-overlay.8

   1 .mso www.tmac
   2 .TH merge-overlay 8
   3 .SH NAME
   4 merge-overlay \- Utility to "merge down" a fusefile overlay.
   5
   6 .SH SYNOPSIS
   7 .B merge-overlay \fIfusefile\fR \fIoverlayfile\fR
   8
   9 .SH DESCRIPTION
  10
  11 \fBmerge-overlay\fR is an administration utility for writing the data
  12 blocks of a fusefile overlay into a current fusefile (or ordinary file
  13 of matching size).
  14
  15 .SH EXAMPLE
  16
  17 This section illustrates a use of \fBmerge-overlay\fR via a use case
  18 scenario that involves a succession of steps where \fBfusefile\fR is
  19 used with successive overlays for the purpose of capturing revisions
  20 of a fused file. Notably the fusefile must be of the same size
  21 throughout the scenario, and in this example case it is a raw disk
  22 image file, \fIvm.raw\fR, for a virtual machine.
  23
  24 .SS first day
  25 First a file \fIa\fR is set up as overlay for \fIvm.raw\fR to be
  26 \fIvmx.raw\fR for use during the day, and then the fusefile is torn
  27 down at the end of the day.
  28 .RS
  29 \fB$ fusefile \fIvmx.raw\fB
  30 -overlay:\fIa\fB
  31 \fIvm.raw\fR
  32 .RE
  33 .RS
  34 \fB$\fR ... using \fIvmx.raw\fR for the virtual machine ...
  35 .RE
  36 .RS
  37 \fB$ umount -u \fIvmx.raw\fR
  38 .RE
  39 By doing so, \fIvmx.raw\fR represents the original image file
  40 \fIvm.raw\fR initially but changes (i.e. data writes) are collated
  41 into the overlay file \fIa\fR while \fIvm.raw\fR remains unchanged.
  42
  43 .SS second day
  44 The next day file \fIb\fR is set up as overlay stacked over \fIa\fR
  45 for \fIvm.raw\fR to again be \fIvmx.raw\fR. Then that is used over the
  46 day before the fusefile is torn down at the end of the day.
  47 .RS
  48 \fB$ fusefile \fIvmx.raw\fB
  49 -overlay:\fIa\fB:\fIb\fB
  50 \fIvm.raw\fR
  51 .RE
  52 .RS
  53 \fB$\fR ... using \fIvmx.raw\fR for the virtual machine ...
  54 .RE
  55 .RS
  56 \fB$ umount -u \fIvmx.raw\fR
  57 .RE
  58 By doing so, \fIvmx.raw\fR represents the original image file
  59 \fIvm.raw\fR including yesterday's changes collated in \fIa\fR, and
  60 any further changes are collated into the overlay file \fIb\fR while
  61 both \fIvm.raw\fR and \fIa\fR remain unchanged.
  62
  63 .SS some days later
  64 By adding an additional overlay each day, at the end of the sixth day
  65 there is a stack of overlays,
  66 \fIa\fR:\fIb\fR:\fIc\fR:\fId\fR:\fIe\fR:\fIf\fR. Here the last overlay
  67 file \fIf\R has the last day's changes relative the overkay stack
  68 \fIa\fR:\fIb\fR:\fIc\fR:\fId\fR:\fIe\fR and so forth.
  69
  70 One may now wish to, say, merge \fIa\fR:\fIb\fR:\fIc\fR into a single
  71 overlay file \fIA\fR, and \fId\fR:\fIe\fR:\fIf\fR into another file
  72 \fIB\fR. This could be done as follows:
  73
  74 .RS
  75 ### First merge \fIa\fR, \fIb\fR and \fIc\fR into \fIA\fR
  76 .RE
  77 .RS
  78 \fB$ fusefile \fIvmx.raw\fB -overlay:\fIA\fB \fIvm.raw\fR
  79 .RE
  80 .RS
  81 \fB$ merge-overlay \fIvmx.raw\fB \fIa\fR
  82 .RE
  83 .RS
  84 \fB$ merge-overlay \fIvmx.raw\fB \fIb\fR
  85 .RE
  86 .RS
  87 \fB$ merge-overlay \fIvmx.raw\fB \fIc\fR
  88 .RE
  89 .RS
  90 \fB$ umount -u \fIvmx.raw\fR
  91 .RE
  92
  93 .RS
  94 ### Second merge \fId\fE, \fIe\fR and \fIf\fR into \fIB\fR
  95 .RE
  96 .RS
  97 \fB$ fusefile \fIvmx.raw\fB
  98 -overlay:\fIA\fB:\fIB\fB
  99 \fIvm.raw\fR
 100 .RE
 101 .RS
 102 \fB$ for f in \fId\fB \fIe\fB \fIf\fB ; do
 103 merge-overlay \fIvmx.raw\fB $f ; done\fR
 104 .RE
 105 .RS
 106 \fB$ umount -u \fIvmx.raw\fR
 107 .RE
 108 Note that including \fIA\fR for the second fusefile setup is not
 109 needed for the merging but it's will be needed for using \fIvmx.raw\fR
 110 further used after the merge.
 111
 112 .SH NOTES
 113
 114 The fusefile overlay file contains the written data only; it does not
 115 track the order of changes but rather only keeps the last written data
 116 blocks, which also are combined into larger blocks when possible. The
 117 merging of this means to write the resulting blocks into the target
 118 file in order of byte positions.
 119
 120 .SH SEE ALSO
 121
 122 .B fusefile
 123
 124 .SH COPYRIGHT
 125
 126 Copyright 2023 Ralph Rönnquist <rrq@rrq.au>