From a1b3741b288209a40bb28aa37adf0654e92706f3 Mon Sep 17 00:00:00 2001
From: taradiddles <taradiddles@users.noreply.github.com>
Date: Wed, 4 Apr 2018 16:56:25 +0300
Subject: [PATCH] add copying-files-to-dom0 doc

---
 docs/README.md                             |  3 ++
 docs/common-tasks/copying-files-to-dom0.md | 45 ++++++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 docs/common-tasks/copying-files-to-dom0.md

diff --git a/docs/README.md b/docs/README.md
index 96395ff..5f8df37 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,8 @@
 #### User-contributed documentation and links to third party docs
 
+`common-tasks`
+- copying-files-to-dom0.md: how to copy files (and sparse files) from a VM to dom0
+
 `configuration`
 - improve power management: https://github.com/taradiddles/qubes-os/tree/master/powermgnt
 - use Qubes OS as a server: https://github.com/Rudd-O/qubes-network-server
diff --git a/docs/common-tasks/copying-files-to-dom0.md b/docs/common-tasks/copying-files-to-dom0.md
new file mode 100644
index 0000000..8dc819b
--- /dev/null
+++ b/docs/common-tasks/copying-files-to-dom0.md
@@ -0,0 +1,45 @@
+Copying files to dom0
+=====================
+
+**!! Note: copying untrusted content (or trusted content from an untrusted VM) compromises the whole Qubes OS security model !!**
+
+
+Technically, the output of a file in a VM (generated by a `qvm-run --pass-io ...` command) is redirected into a file in dom0:
+
+~~~
+qvm-run --pass-io vm-name "cat /path/to/file/in/vm" > "/path/to/file/in/dom0"
+~~~
+
+or with a pipe into `dd`, with the `conv=sparse` option to recreate a sparse file in dom0:
+
+~~~
+qvm-run --pass-io vm-name "cat /path/to/file/in/vm" | dd conv=sparse of=/path/to/file/in/dom0
+~~~
+
+Note that in this case the **whole** file is read by `cat` so the operation will take some time to complete for large files. Alternatively, one could pipe the output of `tar -Scf - large_file` into `tar` in dom0, but this is not recommended since an attacker could use potential vulnerabilities in `tar` to compromise dom0.
+
+Script to automate copying:
+
+~~~
+#!/bin/bash
+# qvm-copy-to-dom0
+# Copy a file from an AppVM to dom0
+# qvm-copy-to-dom0 appVM srcPath [ dst ]
+
+AppVM=$1       # mandatory
+Source=$2      # mandatory
+Destination=$3 # optional (will use ~/QubesIncoming/AppVM/ folder if null)
+
+if [ -z "$Destination" ]; then
+	Destination="$HOME/QubesIncoming/$AppVM/$(basename "$Source")"
+	mkdir -p "$HOME/QubesIncoming/$AppVM"
+fi
+
+if [ -e "$Destination" ]; then
+	echo "'$Destination' exists; aborting" >&2
+	exit 1
+fi
+
+qvm-run --pass-io $AppVM "cat $Source" > "$Destination"
+~~~
+