summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars Wirzenius <lars.wirzenius@codethink.co.uk>2014-09-05 13:18:05 +0000
committerLars Wirzenius <lars.wirzenius@codethink.co.uk>2014-09-05 15:38:59 +0000
commitc136fffbdffa81f03eeb84ce491f987af53009a5 (patch)
treeb29ea871015258881dd31166d113a3d546339b25
parent23ead0ffc536d39dda148c6bbf3be6cce3561208 (diff)
downloaddefinitions-c136fffbdffa81f03eeb84ce491f987af53009a5.tar.gz
Document why VBoxManage is run in recv-hole instead of caller
-rwxr-xr-xrecv-hole25
1 files changed, 25 insertions, 0 deletions
diff --git a/recv-hole b/recv-hole
index 75f80a6a..a406cc98 100755
--- a/recv-hole
+++ b/recv-hole
@@ -33,6 +33,31 @@
# This shell script can be executed over ssh (given to ssh as an arguemnt,
# with suitable escaping) on a different computer. This allows a large
# sparse file (e.g., disk image) be transferred quickly.
+#
+# This script should be called in one of the following ways:
+#
+# recv-hole file FILENAME
+# recv-hole vbox FILENAME DISKSIZE
+#
+# In both cases, FILENAME is the pathname of the disk image on the
+# receiving end. DISKSIZE is the size of the disk image in bytes. The
+# first form is used when transferring a disk image to become an
+# identical file on the receiving end.
+#
+# The second form is used when the disk image should be converted for
+# use by VirtualBox. In this case, we want to avoid writing a
+# temporary file on disk, and then calling the VirtualBox VBoxManage
+# tool to do the conversion, since that would involve large amounts of
+# unnecessary I/O and disk usage. Instead we pipe the file directly to
+# VBoxManage, avoiding those issues. The piping is done here in this
+# script, instead of in the caller, to make it easier to run things
+# over ssh.
+#
+# However, since it's not possible seek in a Unix pipe, we have to
+# explicitly write the zeroes into the pipe. This is not
+# super-efficient, but the way to avoid that would be to avoid sending
+# a sparse file, and do the conversion to a VDI on the sending end.
+# That is out of scope for xfer-hole and recv-hole.
set -eu