add copying-files-to-dom0 doc

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

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"
+~~~
+