qubes-doc/developer/services/qfilecopy.md

---
lang: en
layout: doc
permalink: /doc/qfilecopy/
redirect_from:
- /en/doc/qfilecopy/
- /doc/Qfilecopy/
- /wiki/Qfilecopy/
ref: 35
title: Inter-qube file copying (qfilecopy)
---

There are two cases when we need a mechanism to copy files between VMs:

- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM
- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM.

In the early days of Qubes OS, for both cases, a block device (backed by a file in dom0 with a vfat filesystem on it) was attached to VM, file(s) copied there, and then the device was detached and attached to target VM. In the DispVM case, if a edited file has been modified, another block device is passed to requester VM in order to update the source file.

This has the following disadvantages:

- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.
- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.

In modern Qubes OS releases, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. Nowadays, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.

The rpc action for regular file copy is *qubes.Filecopy*, the rpc client is named *qfile-agent*, the rpc server is named *qfile-unpacker*. For DispVM copy, the rpc action is *qubes.OpenInVM*, the rpc client is named *qopen-in-vm*, rpc server is named *vm-file-editor*. Note that the qubes.OpenInVM action can be done on a normal AppVM, too.

Being a rpc server, *qfile-unpacker* must be coded securely, as it processes potentially untrusted data format. Particularly, we do not want to use external tar or cpio and be prone to all vulnerabilities in them; we want a simplified, small utility, that handles only directory/file/symlink file type, permissions, mtime/atime, and assume user/user ownership. In the current implementation, the code that actually parses the data from srcVM has ca 100 lines of code and executes chrooted to the destination directory. The latter is hardcoded to `~user/QubesIncoming/srcVM`; because of chroot, there is no possibility to alter files outside of this directory.
Qfilecopy changed 2011-04-04 07:51:54 -04:00			`---`
Add lang + ref tags to frontmatter Those are fields used by the language switcher to correlate pages across different languages, even if they have different names/paths/titles. They are generated with the prepare_for_translation.py script. 2021-03-13 13:06:18 -05:00			`lang: en`
wiki -> doc migration 2015-04-10 16:17:45 -04:00			`layout: doc`
Revert "Remove all instances of `permalink:` in YAML frontmatter" This reverts commit c815e4c54c315dfca30c66f6a33e07b1ff90b786. https://github.com/QubesOS/qubes-issues/issues/6701#issuecomment-862822827 2021-06-16 22:56:25 -04:00			`permalink: /doc/qfilecopy/`
Change URIs from CamelCase to lowercase-hyphen-separated 2015-10-11 03:04:59 -04:00			`redirect_from:`
Remove en/ from URLs (QubesOS/qubes-issues#1333) 2015-10-28 18:14:40 -04:00			`- /en/doc/qfilecopy/`
Change URIs from CamelCase to lowercase-hyphen-separated 2015-10-11 03:04:59 -04:00			`- /doc/Qfilecopy/`
			`- /wiki/Qfilecopy/`
Add lang + ref tags to frontmatter Those are fields used by the language switcher to correlate pages across different languages, even if they have different names/paths/titles. They are generated with the prepare_for_translation.py script. 2021-03-13 13:06:18 -05:00			`ref: 35`
Fix capitalization; update terms (QubesOS/qubes-issues#6769) Thank you to @unman for the initial sentence case pass. 2021-07-09 08:10:44 -04:00			`title: Inter-qube file copying (qfilecopy)`
Qfilecopy changed 2011-04-04 07:51:54 -04:00			`---`

			`There are two cases when we need a mechanism to copy files between VMs:`

Markdown formatting fixes - mark all code blocks with ``` - unify empty lines between sections - adjust list syntax (no space before dash) - adjust headers to use Atx-style syntax - remove trailing spaces 2021-03-13 12:03:23 -05:00			`- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM`
			`- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM.`
Qfilecopy changed 2011-04-04 07:51:54 -04:00
Remove specific Qubes version refs and warn against this mistake 2021-08-13 05:45:58 -04:00			`In the early days of Qubes OS, for both cases, a block device (backed by a file in dom0 with a vfat filesystem on it) was attached to VM, file(s) copied there, and then the device was detached and attached to target VM. In the DispVM case, if a edited file has been modified, another block device is passed to requester VM in order to update the source file.`
Qfilecopy changed 2011-04-04 07:51:54 -04:00
			`This has the following disadvantages:`

Markdown formatting fixes - mark all code blocks with ``` - unify empty lines between sections - adjust list syntax (no space before dash) - adjust headers to use Atx-style syntax - remove trailing spaces 2021-03-13 12:03:23 -05:00			`- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.`
			`- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.`
Qfilecopy changed 2011-04-04 07:51:54 -04:00
Remove specific Qubes version refs and warn against this mistake 2021-08-13 05:45:58 -04:00			`In modern Qubes OS releases, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. Nowadays, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.`
Qfilecopy changed 2011-04-04 07:51:54 -04:00
Qfilecopy changed 2011-08-30 09:38:27 -04:00			`The rpc action for regular file copy is qubes.Filecopy, the rpc client is named qfile-agent, the rpc server is named qfile-unpacker. For DispVM copy, the rpc action is qubes.OpenInVM, the rpc client is named qopen-in-vm, rpc server is named vm-file-editor. Note that the qubes.OpenInVM action can be done on a normal AppVM, too.`
Qfilecopy changed 2011-04-04 07:51:54 -04:00
Update incoming directory to QubesIncoming Five years ago, commit https://github.com/QubesOS/qubes-core-agent-linux/commit/a9bd7120c4252b0b7f1a93f9fe874c2cb0140ff3 changed the target directory of qfile-unpacker from /home/user/incoming to /home/user/QubesIncoming. Update the documentation accordingly. 2018-03-14 03:16:04 -04:00			Being a rpc server, qfile-unpacker must be coded securely, as it processes potentially untrusted data format. Particularly, we do not want to use external tar or cpio and be prone to all vulnerabilities in them; we want a simplified, small utility, that handles only directory/file/symlink file type, permissions, mtime/atime, and assume user/user ownership. In the current implementation, the code that actually parses the data from srcVM has ca 100 lines of code and executes chrooted to the destination directory. The latter is hardcoded to `~user/QubesIncoming/srcVM`; because of chroot, there is no possibility to alter files outside of this directory.