From a3364eed21e2807e79053ab4578e89eeda5627f3 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 13 Aug 2021 02:45:58 -0700 Subject: [PATCH] Remove specific Qubes version refs and warn against this mistake --- developer/general/documentation-style-guide.md | 6 +++++- developer/services/qfilecopy.md | 4 ++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/developer/general/documentation-style-guide.md b/developer/general/documentation-style-guide.md index 3a9f9ba0..fdb4fe8a 100644 --- a/developer/general/documentation-style-guide.md +++ b/developer/general/documentation-style-guide.md @@ -317,7 +317,11 @@ in the beta or release candidate stage. In cases where a documentation page covers functionality that differs considerably between Qubes OS releases, the page should be subdivided into clearly-labeled sections that cover the different functionality in different -releases: +releases (examples below). + +In general, avoid mentioning specific Qubes versions in the body text of +documentation, as these references rapidly go out of date and become misleading +to readers. #### Incorrect Example diff --git a/developer/services/qfilecopy.md b/developer/services/qfilecopy.md index b6a24bb8..2f3fc0a6 100644 --- a/developer/services/qfilecopy.md +++ b/developer/services/qfilecopy.md @@ -15,14 +15,14 @@ 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. -Prior to Qubes Beta1, 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. +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 Qubes Beta1, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. In Qubes Beta2, 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. +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.