diff --git a/about/code-of-conduct.md b/about/code-of-conduct.md index af4ae3fa..3925c62d 100644 --- a/about/code-of-conduct.md +++ b/about/code-of-conduct.md @@ -27,7 +27,7 @@ Examples of unacceptable behavior by participants include: - Publishing others' private information, such as a physical or electronic address, without explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting -(Please also see our [mailing list discussion guidelines](https://www.qubes-os.org/mailing-lists/#discussion-list-guidelines).) +(Please also see our [mailing list discussion guidelines](/mailing-lists/#discussion-list-guidelines).) ## Our Responsibilities diff --git a/basics_user/user-faq.md b/about/faq.md similarity index 70% rename from basics_user/user-faq.md rename to about/faq.md index 13ae1fdc..1feb568f 100644 --- a/basics_user/user-faq.md +++ b/about/faq.md @@ -1,75 +1,34 @@ --- -layout: doc -title: Users' FAQ -permalink: /doc/user-faq/ +layout: sidebar +title: Frequently Asked Questions +permalink: /faq/ redirect_from: +- /doc/user-faq/ - /en/doc/user-faq/ - /doc/UserFaq/ - /wiki/UserFaq/ +- /doc/devel-faq/ +- /en/doc/devel-faq/ +- /doc/DevelFaq/ +- /wiki/DevelFaq/ --- -Qubes Users' FAQ -================ +# Frequently Asked Questions -[General Questions](#general-questions) ---------------------------------------- - * [Is Qubes just another Linux distribution?](#is-qubes-just-another-linux-distribution) - * [How is Qubes different from other security solutions?](#how-is-qubes-different-from-other-security-solutions) - * [Does Qubes use full disk encryption (FDE)?](#does-qubes-use-full-disk-encryption-fde) - * [What is the main concept behind Qubes?](#what-is-the-main-concept-behind-qubes) - * [What about other approaches to security?](#what-about-other-approaches-to-security) - * [What about safe languages and formally verified microkernels?](#what-about-safe-languages-and-formally-verified-microkernels) - * [Why does Qubes use virtualization?](#why-does-qubes-use-virtualization) - * [What do all these terms mean?](#what-do-all-these-terms-mean) - * [Does Qubes run every app in a separate VM?](#does-qubes-run-every-app-in-a-separate-vm) - * [Why does Qubes use Xen instead of KVM or some other hypervisor?](#why-does-qubes-use-xen-instead-of-kvm-or-some-other-hypervisor) - * [What about this other/new (micro)kernel/hypervisor?](#what-about-this-othernew-microkernelhypervisor) - * [What's so special about Qubes' GUI virtualization?](#whats-so-special-about-qubes-gui-virtualization) - * [Can I watch YouTube videos in qubes?](#can-i-watch-youtube-videos-in-qubes) - * [Can I run applications, like games, which require 3D support?](#can-i-run-applications-like-games-which-require-3d-support) - * [Is Qubes a multi-user system?](#is-qubes-a-multi-user-system) - * [Why passwordless sudo?](#why-passwordless-sudo) - * [How should I report documentation issues?](#how-should-i-report-documentation-issues) - * [Will Qubes seek to get certified on the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-to-get-certified-under-the-gnu-free-system-distribution-guidelines-gnu-fsdg) - * [Should I trust this website?](#should-i-trust-this-website) - * [What does it mean to "distrust the infrastructure"?](#what-does-it-mean-to-distrust-the-infrastructure) - * [Why does this website use Cloudflare?](#why-does-this-website-use-cloudflare) - * [Why doesn't this website have security feature X?](#why-doesnt-this-website-have-security-feature-x) +## General & Security -[Installation & Hardware Compatibility](#installation--hardware-compatibility) ------------------------------------------------------------------------------- - * [How much disk space does each qube require?](#how-much-disk-space-does-each-qube-require) - * [How much memory is recommended for Qubes?](#how-much-memory-is-recommended-for-qubes) - * [Can I install Qubes on a system without VT-x?](#can-i-install-qubes-on-a-system-without-vt-x) - * [Can I install Qubes on a system without VT-d?](#can-i-install-qubes-on-a-system-without-vt-d) - * [What is a DMA attack?](#what-is-a-dma-attack) - * [Can I use AMD-v instead of VT-x?](#can-i-use-amd-v-instead-of-vt-x) - * [Can I install Qubes in a virtual machine (e.g., on VMware)?](#can-i-install-qubes-in-a-virtual-machine-eg-on-vmware) - * [Why does my network adapter not work?](#why-does-my-network-adapter-not-work) - * [Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?](#can-i-install-qubes-os-together-with-other-operating-system-dual-bootmulti-boot) +### What is the main concept behind Qubes? -[Common Problems](#common-problems) ------------------------------------ - * [Which version of Qubes am I running?](#which-version-of-qubes-am-i-running) - * [My qubes lost Internet access after a TemplateVM update. What should I do?](#my-qubes-lost-internet-access-after-a-templatevm-update-what-should-i-do) - * [My keyboard layout settings are not behaving correctly. What should I do?](#my-keyboard-layout-settings-are-not-behaving-correctly-what-should-i-do) - * [My dom0 and/or TemplateVM update stalls when attempting to update via …](#my-dom0-andor-templatevm-update-stalls-when-attempting-to-update-via-the-gui-tool-what-should-i-do) - * [How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?](#how-do-i-run-a-windows-hvm-in-non-seamless-mode-ie-as-a-single-window) - * [I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.](#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot) - * [I assigned a PCI device to a qube, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube-why-isnt-the-device-available-in-dom0) - * [How do I install Flash in a Debian qube?](#how-do-i-install-flash-in-a-debian-qube) - * [How do I play video files?](#how-do-i-play-video-files) - * [How do I access my external drive?](#how-do-i-access-my-external-drive) - * [My encrypted drive doesn't appear in Debian qube?](#my-encrypted-drive-doesnt-appear-in-debian-qube) - * [Windows Update is stuck.](#windows-update-is-stuck) - * [Fullscreen Firefox is frozen.](#fullscreen-firefox-is-frozen) - * [I have weird graphics glitches like the screen turning partially black.](#i-have-weird-graphics-glitches-like-the-screen-turning-partially-black) - ------------------ +To build security on the "Security by Compartmentalization (or Isolation)" principle. +### What about other approaches to security? -General Questions ------------------ +The other two popular [approaches](https://blog.invisiblethings.org/2008/09/02/three-approaches-to-computer-security.html) are “Security by Correctness” and “Security by Obscurity.” +We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future. + +### How is Qubes different from other security solutions? + +Please see [this article](https://blog.invisiblethings.org/2012/09/12/how-is-qubes-os-different-from.html) for a thorough discussion. ### Is Qubes just another Linux distribution? @@ -77,26 +36,6 @@ If you really want to call it a distribution, then it's more of a "Xen distribut But Qubes is much more than just Xen packaging. It has its own VM management infrastructure, with support for template VMs, centralized VM updating, etc. It also has a very unique GUI virtualization infrastructure. -### How is Qubes different from other security solutions? - -Please see [this article](https://blog.invisiblethings.org/2012/09/12/how-is-qubes-os-different-from.html) for a thorough discussion. - -### Does Qubes use full disk encryption (FDE)? - -Yes, of course! -Full disk encryption is enabled by default. -Specifically, we use [`LUKS`](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[`dm-crypt`](https://en.wikipedia.org/wiki/Dm-crypt). -You can even [manually configure your encryption parameters](/doc/encryption-config/), if you like! - -### What is the main concept behind Qubes? - -To build security on the “Security by Compartmentalization (or Isolation)” principle. - -### What about other approaches to security? - -The other two popular [approaches](https://blog.invisiblethings.org/2008/09/02/three-approaches-to-computer-security.html) are “Security by Correctness” and “Security by Obscurity.” -We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future. - ### What about safe languages and formally verified microkernels? In short: these are non-realistic solutions today. We discuss this in further depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf). @@ -105,6 +44,13 @@ In short: these are non-realistic solutions today. We discuss this in further de We believe that this is currently the only practically viable approach to implementing strong isolation while simultaneously providing compatibility with existing applications and drivers. +### Does Qubes use full disk encryption (FDE)? + +Yes, of course! +Full disk encryption is enabled by default. +Specifically, we use [`LUKS`](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[`dm-crypt`](https://en.wikipedia.org/wiki/Dm-crypt). +You can even [manually configure your encryption parameters](/doc/encryption-config/), if you like! + ### What do all these terms mean? All Qubes-specific terms are defined in the [glossary](/doc/glossary/). @@ -119,6 +65,10 @@ A typical user would likely need around five qubes. Very paranoid users, or thos In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface). We discuss this in much greater depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf). +### How is Qubes affected by Xen Security Advisories (XSAs)? + +See the [XSA Tracker](/security/xsa/). + ### What about this other/new (micro)kernel/hypervisor? Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first: @@ -143,39 +93,27 @@ Here are the answers for Xen 4.1 (which we use as of 2014-04-28): 7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization. 8. Mostly WorksTM :) +### Which virtualization modes do VMs use? + +Here is an overview of the VM virtualization modes that correspond to each Qubes OS version (as of 2018-01-13): + +VM type \ Qubes OS version | 3.2 | 4.0-rc1-3 | 4.0-rc4 | +---------------------------------- | --- | --------- | ------- | +Default VMs without PCI devices | PV | HVM | PVH | +Default VMs with PCI devices | PV | HVM | HVM | +Stub domains - Default VMs w/o PCI | N/A | PV | N/A | +Stub domains - Default VMs w/ PCI | N/A | PV | PV | +Stub domains - HVMs | PV | PV | PV | + ### What's so special about Qubes' GUI virtualization? We have designed the GUI virtualization subsystem with two primary goals: security and performance. Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks. At the same time, due to the smart use of Xen shared memory, our GUI implementation is very efficient, so most virtualized applications really feel as if they were executed natively. -### Can I watch YouTube videos in qubes? - -Absolutely. - -### Can I run applications, like games, which require 3D support? - -Those won’t fly. -We do not provide OpenGL virtualization for Qubes. -This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure. -However, Qubes does allow for the use of accelerated graphics (OpenGL) in Dom0’s Window Manager, so all the fancy desktop effects should still work. - -For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads: - -- [GPU passing to HVM](https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&) -- [Clarifications on GPU security](https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&) - -### Is Qubes a multi-user system? - -No. -Qubes does not pretend to be a multi-user system. -Qubes assumes that the user who controls Dom0 controls the whole system. -It would be very difficult to **securely** implement multi-user support. -See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details. - ### Why passwordless sudo? -Please refer to [this page](https://www.qubes-os.org/doc/vm-sudo/). +Please refer to [this page](/doc/vm-sudo/). ### How should I report documentation issues? @@ -227,11 +165,48 @@ So, if feature X isn't enabled, it's most likely for one of three reasons: 3. Our platform supports it, but we're not aware that we can enable it or have forgotten to do so. (If it seems like this is the case, let us know!) +---------- -Installation & Hardware Compatibility -------------------------------------- +## Users -(See also: [System Requirements](/doc/system-requirements/), [Hardware Compatibility List](/hcl/), and [Certified Laptops](/doc/certified-laptops/).) +### Can I watch YouTube videos in qubes? + +Absolutely. + +### Can I run applications, like games, which require 3D support? + +Those won’t fly. +We do not provide OpenGL virtualization for Qubes. +This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure. +However, Qubes does allow for the use of accelerated graphics (OpenGL) in Dom0’s Window Manager, so all the fancy desktop effects should still work. + +For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads: + +- [GPU passing to HVM](https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&) +- [Clarifications on GPU security](https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&) + +### Is Qubes a multi-user system? + +No. +Qubes does not pretend to be a multi-user system. +Qubes assumes that the user who controls Dom0 controls the whole system. +It is very difficult to **securely** implement multi-user support. +See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details. + +However, in Qubes 4.x we will be implementing management functionality. See [Admin API](/news/2017/06/27/qubes-admin-api/) and [Core Stack](/news/2017/10/03/core3/) for more details. + + +### What are the system requirements for Qubes OS? + +See the [System Requirements](/doc/system-requirements/). + +### Is there a list of hardware that is compatible with Qubes OS? + +See the [Hardware Compatibility List](/hcl/). + +### Is there any certified hardware for Qubes OS? + +See [Certified Hardware](/doc/certified-hardware/). ### How much disk space does each qube require? @@ -242,10 +217,14 @@ This also means that it is possible to update the software for several qubes sim ### How much memory is recommended for Qubes? -At least 4 GB. +At least 4 GB, but 8 GB is more realistic. It is possible to install Qubes on a system with 2 GB of RAM, but the system would probably not be able to run more than three qubes at a time. -### Can I install Qubes on a system without VT-x? +### Can I install Qubes 4.x on a system without VT-x or VT-d? + +Qubes 4.x requires Intel VT-x with EPT / AMD-V with RVI (SLAT) and Intel VT-d / AMD-Vi (aka AMD IOMMU) for proper functionality (see the [4.x System Requirements](/doc/system-requirements/#qubes-release-4x)). You may be able to install it without the required CPU features for testing purposes only, but VMs may not function correctly and there will be no security isolation. For more information, see our post on [updated requirements for Qubes-certified hardware](/news/2016/07/21/new-hw-certification-for-q4/). + +### Can I install Qubes 3.2 on a system without VT-x? Yes. Xen doesn't use VT-x (or AMD-v) for PV guest virtualization. @@ -253,7 +232,7 @@ Xen doesn't use VT-x (or AMD-v) for PV guest virtualization. However, without VT-x, you won't be able to use fully virtualized VMs (e.g., Windows-based qubes), which were introduced in Qubes 2. In addition, if your system lacks VT-x, then it also lacks VT-d. (See next question.) -### Can I install Qubes on a system without VT-d? +### Can I install Qubes 3.2 on a system without VT-d? Yes. You can even run a NetVM, but you will not benefit from DMA protection for driver domains. @@ -278,7 +257,7 @@ Most attacks on NetVM / UsbVM (but not all!) require being somewhat close to the ### Can I use AMD-v instead of VT-x? -See [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5). +Yes, and see [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5). ### Can I install Qubes in a virtual machine (e.g., on VMware)? @@ -288,7 +267,7 @@ Some users have been able to do this, but it is neither recommended nor supporte You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes. There may be a binary blob, which provides drivers in the linux-firmware package. -Open a terminal and run `sudo yum install linux-firmware` in the TemplateVM upon which your NetVM is based. You have to restart the NetVM after the TemplateVM has been shut down. +Open a terminal and run `sudo dnf install linux-firmware` (or `sudo yum install linux-firmware` in Qubes versions prior to 3.2.1) in the TemplateVM upon which your NetVM is based. You have to restart the NetVM after the TemplateVM has been shut down. ### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)? @@ -296,9 +275,6 @@ You shouldn't do that, because it poses a security risk for your Qubes OS instal But if you understand the risk and accept it, read [documentation on multibooting](/doc/multiboot/), it begins with an explanation of the risks with such a setup. -Common Problems ---------------- - ### Which version of Qubes am I running? See [here](/doc/version-scheme/#check-installed-version). @@ -332,23 +308,26 @@ This can usually be fixed by updating via the command line. In dom0, open a terminal and run `sudo qubes-dom0-update`. -In your TemplateVMs, open a terminal and run `sudo yum upgrade`. +In your TemplateVMs, open a terminal and run `sudo dnf upgrade` (or `sudo yum upgrade` for Qubes older than 3.2.1). ### How do I run a Windows HVM in non-seamless mode (i.e., as a single window)? Enable "debug mode" in the qube's settings, either by checking the box labeled "Run in debug mode" in the Qubes VM Manager qube settings menu or by running the [qvm-prefs command](/doc/dom0-tools/qvm-prefs/).) - ### I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot. - This is probably because one of the controllers does not support reset. -In Qubes R2 any such errors were ignored but in Qubes R3.0 they are not. -A device that does not support reset is not safe and generally should not be assigned to a VM. +In Qubes R2 any such errors were ignored. In Qubes R3.x they are not. In R4.x, devices that are automatically added to sys-net and sys-usb on install but do not support FLR will be attached with the no-strict-reset option, but see the related warning in the last sentence in this answer. + +A device that does not support reset is not ideal and generally should not be assigned to a VM. Most likely the offending controller is a USB 3.0 device. You can remove this controller from the usbVM, and see if this allows the VM to boot. -Alternatively you may be able to disable USB 3.0 in the BIOS. +Alternatively you may be able to disable USB 3.0 in the BIOS. +If the BIOS does not have the option to disable USB 3.0, try running the following command in dom0 to [force USB 2.0 modes for the USB ports][force_usb2]: + + lspci -nn | grep USB | cut -d '[' -f3 | cut -d ']' -f1 | xargs -I@ setpci -H1 -d @ d0.l=0 + Errors suggesting this issue: @@ -362,12 +341,18 @@ Errors suggesting this issue: internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available. -Another solution would be to set the pci_strictreset option using qvm-prefs in dom0: +Another solution would be to set the pci_strictreset option in dom0: -`qvm-prefs usbVM -s pci_strictreset false` + - In Qubes R4.x, when attaching the PCI device to the VM (where `` can be obtained from running [qvm-pci](/doc/dom0-tools/qvm-pci/)): -This option allows the VM to ignore the error and the VM will start. -Please review the note on [this page](https://www.qubes-os.org/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk. + qvm-pci attach --persistent --option no-strict-reset=true usbVM dom0: + + - In Qubes R3.x, by modifying the VM's properties: + + qvm-prefs usbVM -s pci_strictreset false + +These options allow the VM to ignore the error and the VM will start. +Please review the notes on [this page](/doc/Dom0Tools/QvmPrefs/) and [here](/doc/assigning-devices/) and be aware of the potential risks. ### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0? @@ -385,8 +370,9 @@ or MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias` MOD=`modprobe -R $MODALIAS | head -n 1` echo 0000: > /sys/bus/pci/drivers/$MOD/bind - - + +See also [here](/doc/assigning-devices/). + ### How do I install Flash in a Debian qube? The Debian way is to install the flashplugin-nonfree package. @@ -427,11 +413,13 @@ For Fedora: ### How do I access my external drive? -External media such as external hard drives or flash drives plugged in via USB are available in the sys-usb VM. -They can either be manually mounted with the `mount` command, or accessed conveniently via the graphical file manager which mounts them under `/run/media/user`. +The recommended approach is to pass only the specific partition you intend to use from [`sys-usb`](/doc/usb/) to another qube via [qvm-block](/doc/dom0-tools/qvm-block/). They will show up in the destination qube as `/dev/xvd*` and must be mounted manually. Another approach is to attach the entire USB drive to your destination qube. However, this could theoretically lead to an attack because it forces the destination qube to parse the device's partition table. If you believe your device is safe, you may proceed to attach it. -Devices which are passed from one VM to another via `qvm-block` show up as `/dev/xvd*` and must be mounted manually. -See ["How to attach USB drives"](/doc/usb/#how-to-attach-usb-drives) for more information. +In Qubes 4.0, this is accomplished with the Devices Widget located in the tool tray (default top right corner, look for an icon with a yellow square). From the top part of the list, click on the drive you want to attach, then select the qube to attach it to. Although you can also attach the entire USB device to a qube by selecting it from the bottom part of the list, in general this approach should not be used because you are exposing the target qube to unnecessary additional attack surface. + +In Qubes 3.2, you can use the Qubes VM Manager. Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click Attach/detach block devices, and select your desired action and device. + +Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube. See ["How to attach USB drives"](/doc/usb/#how-to-attach-usb-drives) for more information. ### My encrypted drive doesn't appear in Debian qube. @@ -472,3 +460,62 @@ If it seems like the issue described in [this thread](https://github.com/QubesOS - Q → System Tools → Window Manager Tweaks → Compositor → uncheck "Enable display compositing" Please report (via the mailing lists) if you experience this issue, and whether disabling the compositor fixes it for you or not. + +### My HVM in Qubes R4.0 won't let me start/install an OS + +I see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd=off to disable!... ok`. + +From a `dom0` prompt, enter: + + qvm-prefs kernel "" + + +---------- + +## Developers + +### Why does dom0 need to be 64-bit? + +Since 2013 [Xen has not supported 32-bit x86 architecture](https://wiki.xenproject.org/wiki/Xen_Project_Release_Features) and Intel VT-d, which Qubes uses to isolate devices and drivers, is available on Intel 64-bit processors only. + +In addition, with features like improved ASLR, it is often more difficult to exploit a bug on x64 Linux than x86 Linux. +While we designed Qubes from the beginning to limit potential attack vectors, we still realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, however simple, might contain some bugs. +Plus since we haven't implemented a separate storage domain, the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface. +So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer. +The 64-bit option provides some (little perhaps, but some) more protection against some classes of attacks, and at the same time does not have any disadvantages except the extra requirement of a 64 bit processor. +And even though Qubes now "needs" a 64 bit processor, it didn't make sense to run Qubes on a system without 3-4GB of memory, and those have 64-bit CPUs anyway. + +### What is the recommended build environment for Qubes OS? + +Any rpm-based, 64-bit environment, the preferred OS being Fedora. + +### How do I build Qubes from sources? + +See [these instructions](/doc/qubes-builder/). + +### How do I submit a patch? + +See the [Qubes Source Code Repositories](/doc/source-code/) article. + +### What is Qubes' attitude toward changing guest distros? + +We try to respect each distro's culture, where possible. +See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an example. + +The policy is there mostly to ease maintenance, on several levels: + + * Less modifications means easier migration to new upstream distribution + releases. + * The upstream documentation matches the distribution running in the Qubes VM. + * We're less likely to introduce Qubes-specific issues. + * Each officially supported distribution (ideally) should offer the same set of + Qubes-specific features - a change in one supported distribution should be + followed also in others, including new future distributions. + +### Is the I/O emulation component (QEMU) part of the Trusted Computing Base (TCB)? + +No. Unlike many other virtualization systems, Qubes takes special effort to keep QEMU _outside_ of the TCB. +This has been achieved thanks to the careful use of Xen's stub domain feature. +For more details about how we improved on Xen's native stub domain use, see [here](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html). + +[force_usb2]: https://www.systutorials.com/qa/1908/how-to-force-a-usb-3-0-port-to-work-in-usb-2-0-mode-in-linux diff --git a/about/mailing-lists.md b/about/mailing-lists.md index a6b6dee6..1a271ca5 100644 --- a/about/mailing-lists.md +++ b/about/mailing-lists.md @@ -14,6 +14,42 @@ redirect_from: Qubes Mailing Lists =================== +Staying Safe +------------ + +The Qubes mailing lists are open to the public. The contents of the list are +crawled by search engines and archived by third-party services outside of our +control. Please do not send anything to the mailing lists that you are not +comfortable seeing discussed in public. If confidentiality is a concern, please +use PGP encryption in an off-list email. + +The Qubes community includes people from all walks of life and from around the +world. Individuals differ in areas of experience and technical expertise. You +will come into contact with others whose views and agendas differ from your own. +Everyone is free to write what they please, as long as it doesn't violate our +[Code of Conduct][coc]. Be friendly and open, but do not believe everything you +read. Use good judgment, and be especially careful when following instructions +(e.g., copying commands) given by others on the lists. + +All official announcements from the [Qubes team] will be signed by the PGP key +belonging to the team member who sends the announcement. However, anyone on the +list can choose to sign their messages, so the presence of a PGP signature does +not indicate authority. How, then, should you sort the good advice from the bad? +This is up to each individual to decide, but it helps to know that many members +of our community have proven themselves knowledgeable through their +[contributions] to the project. Typically, these individuals sign their messages +with the same key as (or another key authenticated by) the one they use to +[sign their contributions][code-signing]. + +For example, you might find it easier to trust advice from someone who has a +proven track record of [contributing software packages] or [contributing to the +documentation]. It's unlikely that individuals who have worked hard to build +good reputations for themselves through their contributions over the years would +risk giving malicious advice in signed messages to public mailing lists. Since +every contribution to the Qubes OS Project is publicly visible and +cryptographically signed, anyone would be in a position to [verify] that these +came from the same keyholder. + Discussion list guidelines -------------------------- @@ -75,7 +111,8 @@ guidelines. including many who post to the lists anonymously. (Given the integration of Qubes with [Whonix], we understand better than most the complexities of privacy and anonymity, and we know that many users have no other choice but - to post anonymously.) You can read our project's [Code of Conduct][coc] for more information. + to post anonymously.) You can read our project's [Code of Conduct][coc] for + more information. ### Specific rules and notes ### @@ -166,6 +203,7 @@ were sent directly to the list. interface. This has the advantage that it allows you to search and reply to messages which were sent prior to your subscription to the list. However, a Google account is required in order to post through this interface. + * You can also search the [traditional mail archive][qubes-users-archive] #### Gmane @@ -246,6 +284,7 @@ You must be subscribed in order to post to this list. interface. This has the advantage that it allows you to search and reply to messages which were sent prior to your subscription to the list. However, a Google account is required in order to post through this interface. + * You can also search the [traditional mail archive][qubes-devel-archive] #### Gmane @@ -331,8 +370,8 @@ qubes-translation ### How to use this list -This list is for discussion around the localization and translation of Qubes OS, -its documentation, and the website. +This list is for discussion around the localization and translation of Qubes OS, +its documentation, and the website. Examples of topics or question suitable for this list include: @@ -360,6 +399,12 @@ You must be subscribed in order to post to this list. messages which were sent prior to your subscription to the list. However, a Google account is required in order to post through this interface. +[Qubes team]: /team/ +[contributions]: /doc/contributing/ +[code-signing]: /doc/code-signing/ +[contributing software packages]: /doc/package-contributions/ +[contributing to the documentation]: /doc/doc-guidelines/ +[verify]: /security/verifying-signatures/ [qsb]: /security/bulletins/ [qubes-announce-web]: https://groups.google.com/group/qubes-announce [top-post]: https://en.wikipedia.org/wiki/Posting_style @@ -369,9 +414,11 @@ You must be subscribed in order to post to this list. [HCL]: /doc/hcl/ [Installation Guide]: /doc/installation-guide/ [System Requirements]: /doc/system-requirements/ -[User FAQ]: /doc/user-faq/ +[User FAQ]: /faq/#users [documentation]: /doc/ [thunderbird-newsgroup]: https://support.mozilla.org/en-US/kb/creating-newsgroup-account +[qubes-users-archive]: https://www.mail-archive.com/qubes-users@googlegroups.com/ +[qubes-devel-archive]: https://www.mail-archive.com/qubes-devel@googlegroups.com/ [qubes-users-web]: https://groups.google.com/group/qubes-users [qubes-devel-web]: https://groups.google.com/group/qubes-devel [qubes-translation-web]: https://groups.google.com/group/qubes-translation @@ -383,3 +430,4 @@ You must be subscribed in order to post to this list. [localization]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Alocalization [coc]: /code-of-conduct/ [Transifex]: https://www.transifex.com/otf/qubes/ + diff --git a/basics_dev/coding-style.md b/basics_dev/coding-style.md index 4e9640ff..f37e2b90 100644 --- a/basics_dev/coding-style.md +++ b/basics_dev/coding-style.md @@ -78,7 +78,7 @@ File naming conventions **File naming in Windows systems:** - All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions) -- Other, 3rd party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers` +- Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers` General programming style guidelines ------------------------------------ diff --git a/basics_dev/devel-faq.md b/basics_dev/devel-faq.md deleted file mode 100644 index ba62c832..00000000 --- a/basics_dev/devel-faq.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -layout: doc -title: Developers' FAQ -permalink: /doc/devel-faq/ -redirect_from: -- /en/doc/devel-faq/ -- /doc/DevelFaq/ -- /wiki/DevelFaq/ ---- - -Qubes Developers' FAQ -===================== - -Why does dom0 need to be 64-bit? --------------------------------- - -Since 2013 [Xen has not supported 32-bit x86 architecture](https://wiki.xenproject.org/wiki/Xen_Project_Release_Features) and Intel VT-d, which Qubes uses to isolate devices and drivers, is available on Intel 64-bit processors only. - -In addition, with features like improved ASLR, it is often more difficult to exploit a bug on x64 Linux than x86 Linux. -While we designed Qubes from the beginning to limit potential attack vectors, we still realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, however simple, might contain some bugs. -Plus since we haven't implemented a separate storage domain, the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface. -So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer. -The 64-bit option provides some (little perhaps, but some) more protection against some classes of attacks, and at the same time does not have any disadvantages except the extra requirement of a 64 bit processor. -And even though Qubes now "needs" a 64 bit processor, it didn't make sense to run Qubes on a system without 3-4GB of memory, and those have 64-bit CPUs anyway. - -What is the recommended build environment for Qubes OS? ------------------------------------------- - -Any rpm-based, 64-bit environment, the preferred OS being Fedora. - -How do I build Qubes from sources? --------------------------------- - -See [these instructions](/doc/qubes-builder/). - -How do I submit a patch? ------------------------- - -See the [Qubes Source Code Repositories](/doc/source-code/) article. - -What is Qubes' attitude toward changing guest distros? ------------------------------------------------------- - -We try to respect each distro's culture, where possible. -See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an example. - -The policy is there mostly to ease maintenance, on several levels: - - * Less modifications means easier migration to new upstream distribution - releases. - * The upstream documentation matches the distribution running in the Qubes VM. - * We're less likely to introduce Qubes-specific issues. - * Each officially supported distribution (ideally) should offer the same set of - Qubes-specific features - a change in one supported distribution should be - followed also in others, including new future distributions. - -Is I/O emulation component (QEMU) part of the Trusted Computing Base (TCB)? ------------------------- - -No. Unlike many other virtualization systems, Qubes takes special effort to keep QEMU _outside_ of the TCB. -This has been achieved thanks to the careful use of Xen's stub domain feature. -For more details about how we improved on Xen's native stub domain use, see [here](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html). diff --git a/basics_dev/gsoc.md b/basics_dev/gsoc.md index 81585974..9ed852cc 100644 --- a/basics_dev/gsoc.md +++ b/basics_dev/gsoc.md @@ -5,9 +5,8 @@ permalink: /gsoc/ redirect_from: /GSoC/ --- -2017 Google Summer of Code +2018 Google Summer of Code ================ - ## Information for Students Thank you for your interest in participating in the [Google Summer of Code program][gsoc-qubes] with the [Qubes OS team][team]. You can read more about the Google Summer of Code program at the [official website][gsoc] and the [official FAQ][gsoc-faq]. @@ -18,6 +17,8 @@ You don't have to be a proven developer -- in fact, this whole program is meant You should start learning the components that you plan on working on before the start date. Qubes developers are available on the [mailing lists][ml-devel] for help. The GSoC timeline reserves a lot of time for bonding with the project -- use that time wisely. Good communication is key, you should plan to communicate with your team daily and formally report progress and plans weekly. Students who neglect active communication will be failed. +You can view the projects we had in 2017 in the [GSoC archive here][2017-archive]. + ### Overview of Steps - Join the [qubes-devel list][ml-devel] and introduce yourself, and meet your fellow developers @@ -35,7 +36,7 @@ Before the summer starts, there are some preparatory tasks which are highly enco ### Student proposal guidelines -A project proposal is what you will be judged upon. Write a clear proposal on what you plan to do, the scope of your project, and why we should choose you to do it. Proposals are the basis of the GSoC projects and therefore one of the most important things to do well. The proposal is not only the basis of our decision of which student to choose, it has also an effect on Google's decision as to how many student slots are assigned to Qubes. +A project proposal is what you will be judged upon. Write a clear proposal on what you plan to do, the scope of your project, and why we should choose you to do it. Proposals are the basis of the GSoC projects and therefore one of the most important things to do well. The proposal is not only the basis of our decision of which student to choose, it has also an effect on Google's decision as to how many student slots are assigned to Qubes. Below is the application template: @@ -85,50 +86,12 @@ These project ideas were contributed by our developers and may be incomplete. If **Expected results**: What is the expected result in the timeframe given -**Knowledge prerequisite**: Pre-requisites for working on the project. What coding language and knowledge is needed? +**Knowledge prerequisite**: Pre-requisites for working on the project. What coding language and knowledge is needed? If applicable, links to more information or discussions **Mentor**: Name and email address. ``` -### Qubes MIME handlers - -**Project**: Qubes MIME handlers - -**Brief explanation**: [#441](https://github.com/QubesOS/qubes-issues/issues/441) (including remembering decision whether some file -should be opened in DispVM or locally) - -**Expected results**: - - - Design mechanism for recognising which files should be opened locally and which in Disposable VM. This mechanism should: - - Respect default action like "by default open files in Disposable VM" (this - may be about files downloaded from the internet, transferred from - other VM etc). - - Allow setting persistent flag for a file that should be opened in specific - way ("locally"); this flag should local to the VM - it shouldn't be possible - to preserve (or even fabricate) the flag while transferring the file from/to - VM. - - See linked ticket for simple ideas. - - Implement generic file handler to apply this mechanism; it should work - regardless of file type, and if file is chosen to be opened locally, normal - (XDG) rules of choosing application should apply. - - Setting/unsetting the flag should be easy - like if once file is chosen to - be opened locally, it should remember that decision. - - Preferably use generic mechanism to integrate it into file managers (XDG - standards). If not possible - integrate with Nautilus and Dolphin. - - Optionally implement the same for Windows. - - Document the mechanism (how the flag is stored, how mechanism is plugged - into file managers etc). - - Write unit tests and integration tests. - -**Knowledge prerequisite**: - - - XDG standards - - Bash or Python scripting - - Basic knowledge of configuration/extension for file managers - -**Mentor**: [Marek Marczykowski-Górecki](/team/) - ### Template manager, new template distribution mechanism **Project**: Template manager, new template distribution mechanism @@ -165,7 +128,7 @@ would override all the user changes there). More details: [#1705](https://github.com/QubesOS/qubes-issues/issues/1705) for some idea (this one lack integrity verification, but similar service could be developed with that added) - - If new "package" format is developed, add support for it into + - If new "package" format is developed, add support for it into [linux-template-builder](https://github.com/QubesOS/qubes-linux-template-builder). - Document the mechanism. - Write unit tests and integration tests. @@ -180,6 +143,84 @@ would override all the user changes there). More details: **Mentor**: [Marek Marczykowski-Górecki](/team/) +### Easy inter-VM networking configuration + +**Project**: Easy inter-VM networking configuration + +**Brief explanation**: Utility to easily configure selected VMs to be reachable (by network) from other VMs or outside network. Currently such configuration require adding iptables rules in multiple VMs manually. For exposing VM to outside network, it may be good to adopt qrexec-based TCP forwarding ([#2148](https://github.com/QubesOS/qubes-issues/issues/2148)). + +**Expected results**: + +- support firewall rules for inter-VM traffic in qubes-firewall - both VM side (qubes-firewall service) and dom0 configuration side (relevant Admin API calls) +- mechanism for configuring firewall in target VM, especially INPUT iptables chain - currently it is hardcoded to drop new incoming connections +- convenient tool (or modification to existing tool) for controlling above mechanisms +- integration the above with existing GUI tools (especially VM settings) + +Relevant links: + - [Qubes networking and firewall documentation](/doc/firewall/) + - [qubes-firewall service code](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/qubesagent/firewall.py) + +**Knowledge prerequisite**: + +- iptables +- basics of nft +- python3 + +**Mentor**: [Marek Marczykowski-Górecki](/team/) + +### Mechanism for maintaining in-VM configuration + +**Project**: Mechanism for maintaining in-VM configuration + +**Brief explanation**: Large number of VMs is hard to maintain. Templates helps with keeping them updated, but many applications have configuration in user home directory, which is not synchronized. + +**Expected results**: + +- Design a mechanism how to _safely_ synchronize application configuration living in user home directory (`~/.config`, some other "dotfiles"). Mechanism should be resistant against malicious VM forcing its configuration on other VMs. Some approach could be a strict control which VM can send what changes (whitelist approach, not blacklist). +- Implementation of the above mechanism. +- Documentation how to configure it securely. + + +**Knowledge prerequisite**: + +- shell and/or python scripting +- Qubes OS qrexec services + +**Mentor**: [Marek Marczykowski-Górecki](/team/), [Wojtek Porczyk](/team/). + +### Wayland support in GUI agent and/or GUI daemon + +**Project**: Wayland support in GUI agent and/or GUI daemon + +**Brief explanation**: Currently both GUI agent (VM side of the GUI virtualization) and GUI daemon (dom0 side of GUI virtualization) support X11 protocol only. It may be useful to add support for Wayland there. Note that those are in fact two independent projects: + +1. GUI agent - make it work as Wayland compositor, instead of extracting window's composition buffers using custom X11 driver +2. GUI daemon - act as Wayland application, showing windows retrieved from VMs, keeping zero-copy display path (window content is directly mapped from application running in VM, not copied) + +**Expected results**: + +Choose either of GUI agent, GUI daemon. Both are of similar complexity and each separately looks like a good task for GSoC time period. + +- design relevant GUI agent/daemon changes, the GUI protocol should not be affected +- consider window decoration handling - VM should have no way of spoofing those, so it must be enforced by GUI daemon (either client-side - by GUI daemon itself, or server-side, based on hints given by GUI daemon) +- implement relevant GUI agent/daemon changes +- implement tests for new GUI handling, similar to existing tests for X11 based GUI + +Relevant links: + - [Low level GUI documentation](/doc/gui/) + - [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux) + - [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon) + - [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366) + +**Knowledge prerequisite**: + +- Wayland architecture +- basics of X11 (for understanding existing code) +- C language +- using shared memory (synchronization methods etc) + +**Mentor**: [Marek Marczykowski-Górecki](/team/). + ### Qubes Live USB **Project**: Revive Qubes Live USB, integrate it with installer @@ -230,40 +271,11 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552), **Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/) -### IPv6 support -**Project**: IPv6 support - -**Brief explanation**: Add support for native IPv6 in Qubes VMs. This should -include IPv6 routing (+NAT...), IPv6-aware firewall, DNS configuration, dealing -with IPv6 being available or not in directly connected network. See -[#718](https://github.com/QubesOS/qubes-issues/issues/718) for more details. - -**Expected results**: - - - Add IPv6 handling to network configuration scripts in VMs - - Add support for IPv6 in Qubes firewall (including CLI/GUI tools to configure it) - - Design and implement simple mechanism to propagate information about IPv6 - being available at all (if necessary). This should be aware of ProxyVMs - potentially adding/removing IPv6 support - like VPN, Tor etc. - - Add unit tests and integration tests for both configuration scripts and UI - enhancements. - - Update documentation. - -**Knowledge prerequisite**: - - - network protocols, especially IPv6, TCP, DNS, DHCPv6, ICMPv6 (including - autoconfiguration) - - ip(6)tables, nftables, NAT - - Python and Bash scripting - - network configuration on Linux: ip tool, configuration files on Debian and - Fedora, NetworkManager - -**Mentor**: [Marek Marczykowski-Górecki](/team/) - ### Thunderbird, Firefox and Chrome extensions + **Project**: additional Thunderbird, Firefox and Chrome extensions -**Brief explanation**: +**Brief explanation**: * browser/mail: open link in vm * browser/mail: open link in dispvm @@ -283,7 +295,7 @@ with IPv6 being available or not in directly connected network. See - writing Thunderbird/Firefox extensions (XUL, javascript) - writing Chrome extensions (javascript) -**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu) +**Mentor**: Inquire on [qubes-devel][ml-devel]. ### LogVM(s) @@ -314,31 +326,7 @@ immune to altering past entries. See - systemd - Python/Bash scripting -**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu) - -### GUI improvements - -**Project**: GUI improvements - -**Brief explanation**: - -* GUI for enabling USB keyboard: [#2329](https://github.com/QubesOS/qubes-issues/issues/2329) -* GUI for enabling USB passthrough: [#2328](https://github.com/QubesOS/qubes-issues/issues/2328) -* GUI interface for /etc/qubes/guid.conf: [#2304](https://github.com/QubesOS/qubes-issues/issues/2304) -* Improving inter-VM file copy / move UX master ticket: [#1839](https://github.com/QubesOS/qubes-issues/issues/1839) -* and comprehensive list of GUI issues: [#1117](https://github.com/QubesOS/qubes-issues/issues/1117) - -**Expected results**: - - - Add/enhance GUI tools to configure/do things mentioned in description above. - Reasonable subset of those things is acceptable. - - Write tests for added elements. - -**Knowledge prerequisite**: - - - Python, PyGTK - -**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu) +**Mentor**: [Marek Marczykowski-Górecki](/team/) ### Xen GPU pass-through for Intel integrated GPUs **Project**: Xen GPU pass-through for Intel integrated GPUs (largely independent of Qubes) @@ -378,54 +366,22 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **Brief explanation**: [T509](https://phabricator.whonix.org/T509) -**Expected results**: +**Expected results**: - Work at upstream Tor: An older version of https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. - https://trac.torproject.org/projects/tor/ticket/21397 - implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39 -- port whonix-gw-firewall to nftables -- port whonix-ws-firewall to nftables +- port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables - make connections to IPv6 Tor relays work - make connections to IPv6 destinations work -**Knowledge prerequisite**: - -**Mentor**: [Patrick Schleizer](/team/) - -### Standalone connection wizard for Tor pluggable transports -**Project**: Standalone connection wizard for Tor pluggable transports - -**Brief explanation**: [#1938](https://github.com/QubesOS/qubes-issues/issues/1938), https://www.whonix.org/blog/connection-bridge-wizard, https://github.com/Whonix/anon-connection-wizard - -**Expected results**: - -Users are presented with a GUI where they can select different bridges to use to connect to Tor if it is censored in their country/region, just like with the Tor Browser. - **Knowledge prerequisite**: +- nftables +- iptables +- IPv6 + **Mentor**: [Patrick Schleizer](/team/) -### Leverage modern static & dynamic analysis -**Project**: Leverage modern static & dynamic analysis - -**Brief explanation**: - -**Expected results**: Stand up tooling to automatically run various tools against the Qubes code base, and address as many found issues as possible. - -**Knowledge prerequisite**: Familiarity with various analysis tools & techniques, including but not limited to: valgrind, coverity, clang's sanitizers, guided fuzzing. - -**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu) - -### Formally analyze how untrusted inputs propagate through the Qubes code base -**Project**: Formally analyze how untrusted inputs propagate through the Qubes code base - -**Brief explanation**: It would be useful to have a rigorous understanding of what code paths are reachable and which state can be affected via input from untrusted domains. Such analysis would likely involve building a model of the system with a combination of taint tracking and static and symbolic analysis. - -**Expected results**: A rigorous model of the scope of code paths and state reachable or affectable from other (Xen) domains. - -**Knoledge prerequisite**: Frama-C, pytaint, angr, others. - -**Mentor**: [Jean-Philippe Ouellet](mailto:jpo@vt.edu) - ### Audio support for Qubes Windows Tools **Project**: Audio support for Qubes Windows Tools @@ -448,8 +404,8 @@ Users are presented with a GUI where they can select different bridges to use to **Mentor**: [Rafał Wojdyła](/team/) -### Gui agent for Windows 8/10 -**Project**: Gui agent for Windows 8/10 +### GUI agent for Windows 8/10 +**Project**: GUI agent for Windows 8/10 **Brief explanation**: Add support for Windows 8+ to the Qubes GUI agent and video driver. Starting from Windows 8, Microsoft requires all video drivers to conform to the WDDM display driver model which is incompatible with the current Qubes video driver. Unfortunately the WDDM model is much more complex than the old XPDM one and officially *requires* a physical GPU device (which may be emulated). Some progress has been made to create a full WDDM driver that *doesn't* require a GPU device, but the driver isn't working correctly yet. Alternatively, WDDM model supports display-only drivers which are much simpler but don't have access to system video memory and rendering surfaces (a key feature that would simplify seamless GUI mode). [#1861](https://github.com/QubesOS/qubes-issues/issues/1861) @@ -459,27 +415,7 @@ Users are presented with a GUI where they can select different bridges to use to **Mentor**: [Rafał Wojdyła](/team/) -### Make Anti Evil Maid resistant against shoulder surfing and video surveillance - -**Project**: Observing the user during early boot should not be sufficient to defeat the protection offered by Anti Evil Maid. - -**Brief explanation**: - -1. Implement optional support for time-based one-time-password seed secrets. Instead of verifying a static text or picture (which the attacker can record and replay later on a compromised system), the user would verify an ephemeral six-digit code displayed on another device, e.g. a smartphone running any Google Authenticator compatible code generator app. - -2. Implement optional support for storing a passphrase-encrypted LUKS disk decryption key on a secondary AEM device. The attacker would then have to seize this device in order to decrypt the user's data; just recording the passphrase as it is entered would no longer be enough. - -**Expected results**: AEM package updates implementing both features, with fallback support in case the user does not have their smartphone or secondary AEM device at hand. Good UX and documentation for enrolling or upgrading users. - -**Knowledge prerequisite**: - -- Bash scripting -- The AEM threat model -- GRUB2, dracut, systemd, LUKS - -**Mentor**: [Rusty Bird](mailto:rustybird@openmailbox.org) - -### GNOME support in dom0 +### GNOME support in dom0 / GUI VM **Project**: GNOME support in dom0 @@ -515,6 +451,18 @@ Users are presented with a GUI where they can select different bridges to use to **Mentor**: [Marek Marczykowski-Górecki](/team/) +### Generalize the Qubes PDF Converter to other types of files + +**Project**: Qubes Converters + +**Brief explanation**: One of the pioneering ideas of Qubes is to use disposable virtual machines to convert untrustworthy files (such as documents given to journalists by unknown and potentially malicious whistleblowers) into trusthworhty files. See [Joanna's blog on the Qubes PDF Convert](http://theinvisiblethings.blogspot.co.uk/2013/02/converting-untrusted-pdfs-into-trusted.html) for details of the idea. Joanna has implemented a prototype for PDF documents. The goal of this project would be to generalize beyond the simple prototype to accommodate a wide variety of file formats, including Word documents, audio files, video files, spreadsheets, and so on. The converters should prioritise safety over faithful conversion. For example the Qubes PDF converter typically leads to lower quality PDFs (e.g. cut and paste is no longer possible), because this makes the conversion process safer. + +**Expected results**: We expect that in the timeframe, it will be possible to implement many converters for many file formats. However, if any unexpected difficulties arise, we would prioritise a small number of safe and high quality converters over a large number of unsafe or unuseful converters. + +**Knowledge prerequisite**: Most of the coding will probably be implemented as shell scripts to interface with pre-existing converts (such as ImageMagick in the Qubes PDF converter). However, shell scripts are not safe for processing untrusted data, so any extra processing will need to be implemented in another language -- probably Python. + +**Mentors**: Andrew Clausen and Jean-Philippe Ouellet + ### Mitigate focus-stealing attacks **Project**: Mitigate focus-stealing attacks @@ -524,14 +472,14 @@ Users are presented with a GUI where they can select different bridges to use to **Knoledge prerequisite**: X APIs, Qubes GUI protocol, familiarity with the targeted window manager. -**Mentor**: +**Mentor**: Inquire on [qubes-devel][ml-devel]. ### Progress towards reproducible builds **Project**: Progress towards reproducible builds **Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See: -- "[Security challenges for the Qubes build process](https://www.qubes-os.org/news/2016/05/30/build-security/)" +- "[Security challenges for the Qubes build process](/news/2016/05/30/build-security/)" - [This mailing list post](https://groups.google.com/d/msg/qubes-devel/gq-wb9wTQV8/mdliS4P2BQAJ) - and [reproducible-builds.org](https://reproducible-builds.org/) @@ -539,9 +487,9 @@ for more information and qubes-specific background. **Expected results**: Significant progress towards making the Qubes build process deterministic. This would likely involve cooperation with and hacking on several upstream build tools to eliminate sources of variability. -**Knoledge prerequisite**: qubes-builder [[1]](https://www.qubes-os.org/doc/qubes-builder/) [[2]](https://www.qubes-os.org/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. +**Knoledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. -**Mentor**: +**Mentor**: [Marek Marczykowski-Górecki](/team/) ### Android development in Qubes @@ -556,25 +504,26 @@ Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233) **Knowledge prerequisite**: -**Mentor**: +**Mentor**: Inquire on [qubes-devel][ml-devel]. ---- We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC). +[2017-archive]: https://summerofcode.withgoogle.com/archive/2017/organizations/5074771758809088/ [gsoc-qubes]: https://summerofcode.withgoogle.com/organizations/6239659689508864/ [gsoc]: https://summerofcode.withgoogle.com/ -[team]: https://www.qubes-os.org/team/ +[team]: /team/ [gsoc-faq]: https://developers.google.com/open-source/gsoc/faq -[contributing]: https://www.qubes-os.org/doc/contributing/#contributing-code -[patches]: https://www.qubes-os.org/doc/source-code/#how-to-send-patches -[code-signing]: https://www.qubes-os.org/doc/code-signing/ -[ml-devel]: https://www.qubes-os.org/mailing-lists/#qubes-devel +[contributing]: /doc/contributing/#contributing-code +[patches]: /doc/source-code/#how-to-send-patches +[code-signing]: /doc/code-signing/ +[ml-devel]: /mailing-lists/#qubes-devel [gsoc-participate]: https://developers.google.com/open-source/gsoc/ [gsoc-student]: https://developers.google.com/open-source/gsoc/resources/manual#student_manual [how-to-gsoc]: http://teom.org/blog/kde/how-to-write-a-kick-ass-proposal-for-google-summer-of-code/ [gsoc-submit]: https://summerofcode.withgoogle.com/ -[mailing-lists]: https://www.qubes-os.org/mailing-lists/ +[mailing-lists]: /mailing-lists/ [qubes-issues]: https://github.com/QubesOS/qubes-issues/issues [qubes-issues-suggested]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22 -[qubes-builder]: https://www.qubes-os.org/doc/qubes-builder/ +[qubes-builder]: /doc/qubes-builder/ diff --git a/basics_dev/package-contributions.md b/basics_dev/package-contributions.md index 56731da6..4665e0ec 100644 --- a/basics_dev/package-contributions.md +++ b/basics_dev/package-contributions.md @@ -7,8 +7,6 @@ permalink: /doc/package-contributions/ Package Contributions ===================== -**Notice:** *This is an unofficial draft. Once this information is official, this notice will be removed.* - We're very grateful to the talented and hard-working community members who contribute software packages to Qubes OS. This page explains the inclusion criteria and procedures for such packages, as well as the roles and responsibilities of those involved. @@ -23,7 +21,7 @@ In order to be accepted, packages must: * Have a clearly-defined use case for Qubes users. * Not be unduly burdensome to review. -(Please note that we always reserve the right add criteria to this list.) +(Please note that we always reserve the right to add criteria to this list.) Contribution Procedure ---------------------- diff --git a/basics_dev/source-code.md b/basics_dev/source-code.md index f39a2460..ae1c884a 100644 --- a/basics_dev/source-code.md +++ b/basics_dev/source-code.md @@ -26,7 +26,7 @@ All of our repositories are available under the [QubesOS GitHub account]. To clone a repository: ~~~ -git clone https://github.com/QubesOS/.git +git clone https://github.com/QubesOS/qubes-.git ~~~ e.g.: diff --git a/basics_user/contributing.md b/basics_user/contributing.md index 7af8c78f..5a7568b1 100644 --- a/basics_user/contributing.md +++ b/basics_user/contributing.md @@ -17,6 +17,7 @@ ways in which you can help: * Audit the [source code] * [Report security issues] * [Send patches][patch] to fix bugs or implement features +* [Contribute packages] * [Report bugs] * [Test new releases and updates] * Submit [HCL reports] for your hardware @@ -31,7 +32,6 @@ ways in which you can help: * Follow us on [Twitter] * Join us on [Reddit] * Like us on [Facebook] - * Support our [StackExchange] proposal * And last but not least, tell your friends and colleagues about how Qubes can help them secure their digital lives! @@ -60,6 +60,7 @@ be grateful to [receive your patch][patch]. [source code]: /doc/source-code/ [Report security issues]: /security/ [patch]: /doc/source-code/#how-to-send-patches +[Contribute packages]: /doc/package-contributions [Report bugs]: /doc/reporting-bugs/ [Test new releases and updates]: /doc/testing/ [HCL reports]: /doc/hcl/ @@ -72,9 +73,8 @@ be grateful to [receive your patch][patch]. [Twitter]: https://twitter.com/QubesOS [Reddit]: https://www.reddit.com/r/Qubes/ [Facebook]: https://www.facebook.com/QubesOS -[StackExchange]: https://area51.stackexchange.com/proposals/98519/qubes-os [GitHub issues]: https://github.com/QubesOS/qubes-issues/issues [qubes-devel]: /mailing-lists/#qubes-devel -[Community-Developed Feature Tracker]: https://www.qubes-os.org/qubes-issues/ +[Community-Developed Feature Tracker]: /qubes-issues/ [Qubes download mirror]: /downloads/mirrors/ diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index bcd8e0ec..e58459e8 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -43,7 +43,7 @@ documentation change will be reviewed before it's published to the web. This allows us to maintain quality control and protect our users. As mentioned above, we keep all the documentation in a dedicated [Git -repository][qubes-doc] hosted on [GitHub]. Thanks to the GitHub interface, you can +repository][qubes-doc] hosted on [GitHub]. Thanks to the GitHub's interface, you can edit the documentation even if you don't know Git at all! The only thing you need is a GitHub account, which is free. @@ -105,6 +105,29 @@ pull request, we'll post a comment explaining why we can't. ![done](/attachment/wiki/doc-edit/10-done.png) +How to add images +----------------- + +To add an image to a page, use the following syntax in the main document: + +``` +![Image Title](/attachment/wiki/page-title/image-filename.png) +``` + +Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename. + + +Version-specific Documentation +------------------------------ + +We maintain only one set of documentation for Qubes OS. +We do not maintain a different set of documentation for each version of Qubes. +Our single set of Qubes OS documentation is updated on a continual, rolling basis. +Our first priority is to document all **current, stable releases** of Qubes. +Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. +In cases where a documentation page covers functionality that differs considerably between Qubes OS versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions. + + Contribution Suggestions ------------------------ @@ -135,25 +158,25 @@ Style Guidelines Markdown Conventions -------------------- -All the documentation is written in Markdown for maximum accessibility. When -making contributions, please try to observe the following style conventions: +All the documentation is written in Markdown for maximum accessibility. +When making contributions, please try to observe the following style conventions: * Use spaces instead of tabs. - * Insert a newline at the end of each sentence. - * Rationale: This practice is most appropriate for source that consists - primarily of natural language text. It results in the most useful diffs - and facilitates translation into other languages while mostly preserving - source readability. - * If appropriate, make numerals in numbered lists match between Markdown - source and HTML output. - * Rationale: In the event that a user is required to read the Markdown source - directly, this will make it easier to follow, e.g., numbered steps in a set - of instructions. + * In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo. + Examples of exceptions: + * [QSBs] (intended to be read as plain text) + * [News] posts (plain text is reproduced on the [mailing lists]) + * URLs that appear inside code blocks (e.g., in comments and document templates) + * Files like `README.md` and `CONTRIBUTING.md` + * Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples). + * Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text. + It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability. + * If appropriate, make numerals in numbered lists match between Markdown source and HTML output. + * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. * Use hanging indentations where appropriate. - * Use underline headings (`=====` and `-----`) if possible. If this is not - possible, use Atx-style headings on both the left and right sides - (`### H3 ###`). + * Use underline headings (`=====` and `-----`) if possible. + If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`). * Use `[reference-style][ref]` links. `[ref]: https://daringfireball.net/projects/markdown/syntax#link` @@ -177,5 +200,8 @@ Please try to write good commit messages, according to the [gh-pull]: https://help.github.com/articles/using-pull-requests/ [GitHub]: https://github.com/ [mailing lists]: /mailing-lists/ +[QSBs]: /security/bulletins/ +[News]: /news/ [md]: https://daringfireball.net/projects/markdown/ [git-commit]: /doc/coding-style/#commit-message-guidelines + diff --git a/basics_user/getting-started.md b/basics_user/getting-started.md index 9317eba7..691e8ebd 100644 --- a/basics_user/getting-started.md +++ b/basics_user/getting-started.md @@ -9,7 +9,7 @@ redirect_from: - /wiki/GettingStarted/ --- -Now that you've installed Qubes, let's cover some basic concepts. +After [installing Qubes](/doc/installation-guide/), let's cover some basic concepts. You might also like to refer to the [Glossary](/doc/glossary/). AppVMs (qubes) and TemplateVMs @@ -58,7 +58,7 @@ Qubes VM Manager and Command Line Tools All aspects of the Qubes system can be controlled using command line tools run under a dom0 console. To open a console window in dom0, either go to Start-\>System Tools-\>Konsole or press Alt-F2 and type `konsole`. -Various command line tools are described as part of this guide, and the whole reference can be found [here](/doc/dom0-tools/). +Various command line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/). ![r2b1-dom0-konsole.png](/attachment/wiki/GettingStarted/r2b1-dom0-konsole.png) diff --git a/basics_user/intro.md b/basics_user/intro.md index 71e2dc8d..ade01e72 100644 --- a/basics_user/intro.md +++ b/basics_user/intro.md @@ -228,9 +228,9 @@ technical details have been omitted here for the sake of presentation. [Xen]: https://www.xenproject.org [paper-compart]: https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf [doc]: /doc/ -[user-faq]: /doc/user-faq/ +[user-faq]: /faq/#users [system-doc]: /doc/system-doc/ -[devel-faq]: /doc/devel-faq/ +[devel-faq]: /faq/#developers [downloads]: /downloads/ [getting started]: /getting-started/ diff --git a/basics_user/reporting-bugs.md b/basics_user/reporting-bugs.md index 6cc8f78c..8fb9ca63 100644 --- a/basics_user/reporting-bugs.md +++ b/basics_user/reporting-bugs.md @@ -16,71 +16,65 @@ redirect_from: Reporting Bugs ============== -One of the most important ways in which you can [contribute to the Qubes OS Project] is by reporting any bugs you have found. -Please note that there is a separate process for [reporting security issues](/security/). +One of the most important ways in which you can [contribute to the Qubes OS Project] is by reporting any bugs you have found. -Before you submit a report --------------------------- +Important +--------- -Before you submit a bug report, please take a moment to: - - * Check whether your issue has already been reported. - - * Determine which venue is most appropriate for it. - - * Read the [documentation] to see whether what you've found is really a bug. - - * Search through the existing [Qubes issues][qubes-issues] by typing your key - words in the **Filters** box. Make sure to check both currently open issues, - as well as issues that are already closed. If you find an issue that seems to - be similar to yours, read through it. If this issue is the same as yours, you - can comment with additional information to help the maintainer debug it. - Adding a comment will subscribe you to email notifications, which can be - helpful in getting important updates regarding the issue. If you don't have - anything to add but still want to receive email updates, you can click the - "watch" button at the bottom of the comments. - - * Search through our [mailing list] archives by visiting the Google Groups web - interfaces for both [qubes-users] and [qubes-devel]. +- **To disclose a security issue confidentially, please see the [Security] page.** +- **In all other cases, please do not email individual developers about bugs.** +- **Please note that many issues can be resolved by reading the [documentation].** Where to submit your report --------------------------- -Our [GitHub issues][qubes-issues] tracker is not intended for personal, -localized troubleshooting questions, such as problems that affect only a -specific laptop model. Those questions are more likely to be answered in -[qubes-users], which receives much more traffic. Instead, GitHub issues are -meant to track more general bugs and enhancements that affect a broad range of -Qubes users. - - -How to copy information out of Dom0 ------------------------------------ - -See [Copying from (and to) dom0](/doc/copy-from-dom0/). - - -How to submit a report on the mailing lists -------------------------------------------- - -Please see the [mailing list guidelines][mailing list]. +All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the [website]) are tracked in [qubes-issues], our GitHub issues tracker. +However, [qubes-issues] is not intended for personal, localized troubleshooting questions, such as problems that affect only a specific laptop model. +Those questions should instead be asked in [qubes-users], where they are more likely to be answered. +Instead, [qubes-issues] is meant for tracking more general bugs and enhancements that affect a broad range of Qubes users. +Please see the sections [How to submit a report on GitHub] and [How to submit a report on the mailing lists] below for more information. How to submit a report on GitHub -------------------------------- -We track all bugs in the [qubes-issues] tracker on GitHub. +**Before you submit an issue in [qubes-issues], please check to see whether it has already been reported.** +Search through the existing issues by typing your key words in the **Filters** box. +Make sure to check both currently open issues, as well as issues that are already closed. +If you find an issue that seems to be similar to yours, read through it. +If this issue is the same as yours, you can comment with additional information to help the maintainer debug it. +Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. +If you don't have anything to add but still want to receive email updates, you can click the "watch" button at the bottom of the comments. -When you file a new issue, you should be sure to include the version of Qubes -you're using, as well as versions of related software packages. If your issue is -related to hardware, provide as many details as possible about the hardware, -which could include using command-line tools such as `lspci`. +When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages. +If your issue is related to hardware, provide as many details as possible about the hardware, which could include using command-line tools such as `lspci`. If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [updates-status] repository. +Project maintainers really appreciate thorough explanations. +It usually helps them address the problem more quickly, so everyone wins! -Project maintainers really appreciate thorough explanations. It usually -helps them address the problem more quickly, so everyone wins! +Once your issue is addressed, your GitHub issue may be closed. +After that, the package containing the fix will move to the appropriate [testing] repository, then to the appropriate stable repository. +If you so choose, you can test the fix while it's in the [testing] repository, or you can wait for it to land in the stable repository. +If, after testing the fix, you find that it does not really fix your bug, please leave a comment on your issue explaining the situation. +When you do, we will receive a notification and respond on your issue or reopen it (or both). +Please **do not** create a duplicate issue or attempt to contact the developers individually about your problem. + + +How to submit a report on the mailing lists +------------------------------------------- + +Before submitting a report on the mailing lists, please check to see whether your issue has already been reported by searching through the archives. +You can do this by visiting the Google Groups web interfaces for both [qubes-users] and [qubes-devel]. +Please see the [Mailing Lists] page for further information. + + +How to copy information out of dom0 +----------------------------------- + +Copying information out of dom0 can be useful when reporting bugs. +See [Copying from (and to) dom0] for more information. Testing new releases and updates @@ -96,12 +90,17 @@ Please see our guidelines on [how to contribute code]. [contribute to the Qubes OS Project]: /doc/contributing/ +[Security]: /security/ [documentation]: /doc/ +[website]: / [qubes-issues]: https://github.com/QubesOS/qubes-issues/issues -[mailing list]: https://www.qubes-os.org/mailing-lists/ -[qubes-users]: https://groups.google.com/group/qubes-users -[qubes-devel]: https://groups.google.com/group/qubes-devel +[Mailing List]: /mailing-lists/ +[qubes-users]: /mailing-lists/#qubes-users +[qubes-devel]: /mailing-lists/#qubes-devel +[How to submit a report on GitHub]: #how-to-submit-a-report-on-github +[How to submit a report on the mailing lists]: #how-to-submit-a-report-on-the-mailing-lists [testing]: /doc/testing/ [updates-status]: https://github.com/QubesOS/updates-status/issues +[Copying from (and to) dom0]: /doc/copy-from-dom0/ [how to contribute code]: /doc/contributing/#contributing-code diff --git a/building/building-archlinux-template.md b/building/building-archlinux-template.md index 62b5b59b..a9989c0d 100644 --- a/building/building-archlinux-template.md +++ b/building/building-archlinux-template.md @@ -77,13 +77,13 @@ redirect_from:

-## 4: Downloading and verifying the "Qubes Automated Build System" +## 4: Downloading and verifying the integrity of the "Qubes Automated Build System" * Import the Qubes master key - gpg --recv-keys 0xDDFA1A3E36879494 + gpg --keyserver pgp.mit.edu --recv-keys 0xDDFA1A3E36879494 -* Verify its fingerprint, set as 'trusted'. [This is described here](https://www.qubes-os.org/doc/VerifyingSignatures). +* Verify its fingerprint, set as 'trusted'. [This is described here](/doc/VerifyingSignatures). * Download the Qubes developers' keys. @@ -98,9 +98,10 @@ redirect_from: * Copy your gpg keyrings to your local copy of the repository. (Otherwise you will be asked to download the keys again.) - # Assuming qubes-builder is in your home directory - cp .gnupg/pubring.gpg qubes-builder/keyrings/git/ - cp .gnupg/trustdb.gpg qubes-builder/keyrings/git/ + # Execute the following commands in your home directory. + # It is assumed that the path to the repository is '~/qubes-builder'. + mkdir -p qubes-builder/keyrings/git + cp -t qubes-builder/keyrings/git/ .gnupg/pubring.gpg .gnupg/trustdb.gpg * Verify the integrity of the downloaded repository. The last line should read `gpg: Good signature from`... diff --git a/building/qubes-builder.md b/building/qubes-builder.md index 3fd1815f..d5fe6e48 100644 --- a/building/qubes-builder.md +++ b/building/qubes-builder.md @@ -8,7 +8,7 @@ redirect_from: - /wiki/QubesBuilder/ --- -**Note: The build system has been improved since this how-to was last updated. The [Archlinux template building instructions](https://www.qubes-os.org/doc/building-archlinux-template/) contain more up-to-date and detailed information on how to use the build system.** +**Note: The build system has been improved since this how-to was last updated. The [Archlinux template building instructions](/doc/building-archlinux-template/) contain more up-to-date and detailed information on how to use the build system.** Building Qubes from scratch =========================== @@ -17,7 +17,7 @@ We have a fully automated build system for Qubes, that downloads, builds and packages all the Qubes components, and finally should spit out a ready-to-use installation ISO. -In order to use it one should use an rpm-based distro, like Fedora :) and should ensure the following packages are installed: +In order to use it, one should use an rpm-based distro, like Fedora :), and should ensure the following packages are installed: - sudo - gpg diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index c5fbe9b7..4d9bd8f8 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -11,96 +11,218 @@ redirect_from: Qubes Backup, Restoration, and Migration ======================================== -**Caution:** The Qubes backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). It is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups. +**Caution:** The Qubes R3.2 backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). +Although resolved in R4.0 and higher with the switch to scrypt, it is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups. With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines. -As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/). +As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. +There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/). -Creating a Backup +Creating a Backup (R4.0 and later) ----------------- -1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list. This brings up the **Qubes Backup VMs** window. +1. Go to **Applications menu -> System Tools -> Backup Qubes**. +This brings up the **Qubes Backup VMs** window. -2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up. +2. Move the VMs that you want to back up to the right-hand **Selected** column. +VMs in the left-hand **Available** column will not be backed up. - **Note:** A VM must be shut down in order to be backed up. Currently running VMs appear in red. + You may choose whether to compress backups by checking or unchecking the **Compress the backup** box. + Normally this should be left on unless you have a specific reason otherwise. + + Once you have selected all desired VMs, click **Next**. + +3. Select the destination for the backup: + + If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. + If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. + + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. + For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. + This destination directory must already exist. + If it does not exist, you must create it manually prior to backing up. + + By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. + Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. + This can be used to send your backup directly to, e.g., a remote server using SSH. + + **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. + + At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box. + + **Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.** + +4. You will now see the summary of VMs to be backed up. +If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out. + +5. When you are ready, click **Next**. +Qubes will proceed to create your backup. +Once the progress bar has completed, you may click **Finish**. + +Creating a Backup (R3.2 and earlier) +----------------- + +1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list. +This brings up the **Qubes Backup VMs** window. + +2. Move the VMs that you want to back up to the right-hand **Selected** column. +VMs in the left-hand **Available** column will not be backed up. + + **Note:** A VM must be shut down in order to be backed up. + Currently running VMs appear in red. Once you have selected all desired VMs, click **Next**. 3. Select the destination for the backup: If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**. - If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), first mount the device in a VM, then select the mount point inside that VM as the backup destination. + If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination. - You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up. + You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. + For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right. + If it does not exist, you must create it manually prior to backing up. - By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH. + By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. + Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. + This can be used to send your backup directly to, e.g., a remote server using SSH. At this point, you must also choose whether to encrypt your backup by checking or unchecking the **Encrypt backup** box. **Note:** It is strongly recommended that you opt to encrypt all backups which will be sent to untrusted destinations! - **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted! + **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. + If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. + If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted! -4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**. +4. You will now see the summary of VMs to be backed up. +If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out. + +5. When you are ready, click **Next**. +Qubes will proceed to create your backup. +Once the progress bar has completed, you may click **Finish**. -Restoring from a Backup +Restoring from a Backup (R4.0 and later) ----------------------- -1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list. This brings up the **Qubes Restore VMs** window. +1. Go to **Applications menu -> System Tools -> Restore Backup**. +This brings up the **Qubes Restore VMs** window. 2. Select the source location of the backup to be restored: - - If your backup is located on a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device**. + - If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item. - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. - You must also specify the directory in which the backup resides (or a command to be executed in a VM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again type `backups` into the **Backup directory** field. - - **Note:** After you have typed the directory location of the backup in the **Backup directory** field, click the ellipsis button `...` to the right of the field. + You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. + If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. + For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. + Once you've located the backup file, double-click it or select it and hit **OK**. 3. There are three options you may select when restoring from a backup: - 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway. - 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. - 3. **skip dom0**: If this box is checked, dom0's home directory will not be restored from your backup. + 1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. + 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. + If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. + However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. + See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. -4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. +4. If your backup is encrypted, you must check the **Encrypted backup** box. +If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. - **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification. + **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. + If the backup was not encrypted, the supplied passphrase is used only for integrity verification. + All backups made from a Qubes R4.0 system will be encrypted. - **Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. You must first remove or change the name of any VM with the same name in order to restore such a VM. +5. You will now see the summary of VMs to be restored. +If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out. -5. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**. +6. When you are ready, click **Next**. +Qubes will proceed to restore from your backup. +Once the progress bar has completed, you may click **Finish**. + +Restoring from a Backup (R3.2 and earlier) +----------------------- + +1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list. +This brings up the **Qubes Restore VMs** window. + +2. Select the source location of the backup to be restored: + + - If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item. + - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**. + + You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. + If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. + For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder. + Once you've located the backup file, double-click or select it and hit **OK**. + +3. There are three options you may select when restoring from a backup: + 1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template. + 2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. + If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway. + 3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data. + However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details. + +4. If your backup is encrypted, you must check the **Encrypted backup** box. +If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. + + **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. + If the backup was not encrypted, the supplied passphrase is used only for integrity verification. + + **Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. + You must first remove or change the name of any VM with the same name in order to restore such a VM. + +5. You will now see the summary of VMs to be restored. +If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out. + +6. When you are ready, click **Next**. +Qubes will proceed to restore from your backup. +Once the progress bar has completed, you may click **Finish**. Emergency Backup Recovery without Qubes --------------------------------------- -The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. +The Qubes backup system has been designed with emergency disaster recovery in mind. +No special Qubes-specific tools are required to access data backed up by Qubes. +In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure. -For emergency restore of backup created on Qubes R2 or newer take a look [here](/doc/backup-emergency-restore-v3/). For backups created on earlier Qubes versions, take a look [here](/doc/backup-emergency-restore-v2/). +Refer to the following for emergency restore of a backup created on: + + * [Qubes R4 or newer](/doc/backup-emergency-restore-v4/) + * [Qubes R3](/doc/backup-emergency-restore-v3/) + * [Qubes R2 or older](/doc/backup-emergency-restore-v2/) Migrating Between Two Physical Machines --------------------------------------- -In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved! +In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine. +All of your settings and data will be preserved! Choosing a Backup Passphrase ---------------------------- Here are some things to consider when selecting a passphrase for your backups: - * If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. If your system drive decryption passphrase is already sufficiently strong, it may not.) - * An adversary who has access to your backups may try to substitute one backup for another. For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase. - * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. + * If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. + (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. + If your system drive decryption passphrase is already sufficiently strong, it may not.) + * An adversary who has access to your backups may try to substitute one backup for another. + For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. + If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase. + * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). + On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. Notes ----- - * The Qubes backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. Users are advised to use a very high entropy passphrase for Qubes backups. For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ). + * The Qubes R3.2 and earlier backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. + The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. + Users are advised to use a very high entropy passphrase for Qubes backups. + For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ). * For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion). * If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion). diff --git a/common-tasks/copying-files.md b/common-tasks/copying-files.md index 392310a6..a5b8af28 100644 --- a/common-tasks/copying-files.md +++ b/common-tasks/copying-files.md @@ -19,20 +19,36 @@ In order to copy file(s) from qube A to qube B, follow these steps: GUI --- -1. Open file manager in the source qube (qube A), choose file(s) that you wish to copy, and right click on the selection, and choose `Copy to another AppVM` +1. Open file manager in the source qube (qube A), choose file(s) that you wish to copy, and right click on the selection, and choose `Copy to another AppVM` -1. A dialog box will appear asking for the name of the destination qube (qube B). +2. A dialog box will appear asking for the name of the destination qube (qube B). -1. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent). After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B: +3. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent). After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B: -- `/home/user/QubesIncoming/` + `/home/user/QubesIncoming/` + +4. You can now move them whenever you like in the qube B filesystem using the file manager there. -1. You can now move them whenever you like in the qube B filesystem using the file manager there. CLI --- -[qvm-copy-to-vm](/doc/vm-tools/qvm-copy-to-vm/) +``` +qvm-copy-to-vm [--without-progress] dest_vmname file [file]+ +``` + +Also see: [qvm-copy-to-vm](/doc/vm-tools/qvm-copy-to-vm/) + + +Qubes 4.0 +--------- + +In Qubes 4.0, qvm-copy-to-vm and qvm-move-to-vm are deprecated (GUI behaviour is unchanged from Qubes 3.2). In the command line, use qvm-copy or qvm-move to avoid typing target qube name twice. + +``` +qvm-copy [--without-progress] file [file]+ +``` + On inter-qube file copy security ---------------------------------- @@ -44,3 +60,4 @@ However, one should keep in mind that performing a data transfer from *less trus See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes. You may also want to read how to [revoke "Yes to All" authorization](/doc/qrexec3/#revoking-yes-to-all-authorization) + diff --git a/common-tasks/dispvm.md b/common-tasks/dispvm.md index 45cbfc35..cda6ce0c 100644 --- a/common-tasks/dispvm.md +++ b/common-tasks/dispvm.md @@ -11,74 +11,95 @@ redirect_from: Disposable VMs (DispVMs) ======================== -Background ----------- +A Disposable VM (DispVM) is a lightweight VM that can be created quickly and will disappear when closed. +Disposable VMs are usually created in order to host a single application, like a viewer, editor, or web browser. +Changes made to a file opened in a Disposable VM are passed back to the originating VM. +This means that you can safely work with untrusted files without risk of compromising your other VMs. +DispVMs can be created either directly from Dom0 or from within AppVMs. +Once a DispVM has been created it will appear in Qubes VM Manager with the name "dispX". -A Disposable VM (DispVM) is a lightweight VM that can be created quickly and which will disappear when it is finished with. Usually a Disposable VM is created in order to host a single application, like a viewer or an editor. This means that you can safely work with files without risk of compromising any of your VMs. Changes made to a file opened in a disposable VM are passed back to the originating VM. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why would one want to use a Disposable VM. +See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a Disposable VM. -By default a DispVM will inherit the NetVM and firewall settings of the ancestor VM, that is the VM it is launched from. Thus if an AppVM uses sys-net as NetVM (instead of, say, sys-whonix), any DispVM launched from this AppVM will also have sys-net as its NetVM. You can change this behaviour for individual VMs: in Qubes VM Manager open VM Settings for the VM in question and go to the "Advanced" tab. Here you can edit the "NetVM for DispVM" setting to change the NetVM of any DispVM launched from that VM. +Disposable VMs and Networking +----------------------------- -A DispVM launched from the Start Menu inherits the NetVM of the [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template). By default it is named `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM) and, as a so-called internal VM, hidden in Qubes VM Manager; it can be shown by selecting "Show/Hide internal VMs". Notice that changing the "NetVM for DispVM" setting for the DVM Template does *not* affect the NetVM of DispVMs launched from the Start Menu; only changing the DVM Template's own NetVM does. +NetVM and firewall rules for Disposable VMs can be set as they can for a normal VM. +By default a DispVM will inherit the NetVM and firewall settings of the VM from which it is launched. +Thus if an AppVM uses sys-net as its NetVM, any DispVM launched from this AppVM will also have sys-net as its NetVM. +You can change this behaviour for individual VMs: in Qubes VM Manager open VM Settings for the VM in question and go to the "Advanced" tab. +Here you can edit the "NetVM for DispVM" setting to change the NetVM of any DispVM launched from that VM. -Once a DispVM has been created it will appear in Qubes VM Manager with the name "dispX", and NetVM and firewall rules can be set as for a normal VM. +A Disposable VM launched from the Start Menu inherits the NetVM of the [DVM Template](/doc/glossary/#dvm-template). +By default the DVM template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM). +As an "internal" VM it is hidden in Qubes VM Manager, but can be shown by selecting "Show/Hide internal VMs". +Note that changing the "NetVM for DispVM" setting for the DVM Template does *not* affect the NetVM of DispVMs launched from the Start Menu; only changing the DVM Template's own NetVM does. +Opening a file in a Disposable VM via GUI +----------------------------------------- -Opening a file in a Disposable VM (via GUI) -------------------------------------------- - -In some AppVM, right click on the file you wish to open in a Disposable VM (in the Nautilus file manager), then choose "Open in Disposable VM". Wait a few seconds and the default application for this file type should appear displaying the file content. This app is running in a whole new VM -- a disposable VM created for the purpose of viewing or editing this very file. Once you close the viewing application the whole Disposable VM will be destroyed. If you have edited the file and saved the changes the changed file will be saved back to the original VM, overwriting the original. +In an AppVM's file manager, right click on the file you wish to open in a Disposable VM, then choose "Open in Disposable VM". +Wait a few seconds and the default application for this file type should appear displaying the file content. +This app is running in its own dedicated VM -- a Disposable VM created for the purpose of viewing or editing this very file. +Once you close the viewing application the whole Disposable VM will be destroyed. +If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original. ![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-2.png) Opening a fresh web browser instance in a new Disposable VM ----------------------------------------------------------- -Sometimes it is convenient to open a fresh instance of Firefox within a new fresh Disposable VM. This can be easily done by using the Start Menu: just go to Start -\> System Tools -\> DispVM:Firefox web browser . Wait a few seconds until a web browser starts. Once you close the viewing application the whole Disposable VM will get destroyed. +Sometimes it is desirable to open an instance of Firefox within a new fresh Disposable VM. +This can be done easily using the Start Menu: just go to Start -\> System Tools -\> DispVM:Firefox web browser. +Wait a few seconds until a web browser starts. +Once you close the viewing application the whole Disposable VM will be destroyed. ![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-3.png) Opening a file in a Disposable VM via command line (from AppVM) --------------------------------------------------------------- -Use the `qvm-open-in-dvm` command line (from your AppVM), e.g.: +Use the `qvm-open-in-dvm` command from a terminal in your AppVM: ~~~ [user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf ~~~ -The qvm-open-in-dvm will not exit until you close the application in the Disposable VM. - -Starting an arbitrary application in a disposable VM via command line (from Dom0) ---------------------------------------------------------------------------------- - -**Note:** Normally there should be no need for doing this -- this is just for Qubes hackers ;) - -~~~ -[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red -~~~ - -In fact the Disposable VM appmenu used for starting Firefox contains a very similar command to the above. Please note, however, that it generally makes little sense to start any other application other than a Web Browser this way... +Note that the `qvm-open-in-dvm` process will not exit until you close the application in the Disposable VM. Starting an arbitrary program in a Disposable VM from an AppVM -------------------------------------------------------------- -Sometimes it might be useful to start an arbitrary program, such as e.g. terminal in an Disposable VM from an AppVM. This could be simply done this way: +Sometimes it can be useful to start an arbitrary program in a DispVM. This can be done from an AppVM by running ~~~ [user@vault ~]$ qvm-run '$dispvm' xterm ~~~ -Note the above command is issued in an AppVM, not in Dom0. The created Disposable VM can be normally accessed via other tools, such as e.g. `qvm-copy-to-vm`, using its 'dispX' name, as shown by the Qubes Manager or `qvm-ls` tools. +The created Disposable VM can be accessed via other tools (such as `qvm-copy-to-vm`) using its "dispX" name as shown in the Qubes Manager or `qvm-ls`. +Starting an arbitrary application in a Disposable VM via command line (from Dom0) +--------------------------------------------------------------------------------- + +The Start Menu has shortcuts for opening a terminal and a web browser in dedicated DispVMs, since these are very common tasks. +However, it is possible to start an arbitrary application in a DispVM directly from Dom0 by running + +~~~ +[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red +~~~ + +(The Disposable VM appmenu used for starting Firefox runs a very similar command to the one above.) Customizing Disposable VMs ---------------------------------------------------------- - -You can change the template used to generate the Disposable VM, and change settings used in the Disposable VM savefile. These changes will be reflected in every new Disposable VM. -Full instructions are [here](/doc/dispvm-customization/) +-------------------------- +You can change the template used to generate the Disposable VM, and change settings used in the Disposable VM savefile. +These changes will be reflected in every new Disposable VM. +Full instructions can be found [here](/doc/dispvm-customization/). Disposable VMs and Local Forensics ---------------------------------- -At this time, DispVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion). +At this time, DispVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. +For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion). + +When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/). diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 7ebef52d..85974a4d 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -14,7 +14,7 @@ Updating software in dom0 Why would one want to update software in dom0? ---------------------------------------------- -Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the 3rd party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan to move the disk backends to an untrusted domain in a future Qubes release) Of course, we believe this software is reasonably secure, and we hope it will not need patching. +Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching. However, we anticipate some other situations in which updating dom0 software might be necessary or desirable: @@ -58,12 +58,12 @@ Of course, command line tools are still available for accomplishing various upda sudo qubes-dom0-update package-version ~~~ - Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. + Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0. 2. Downgrade the package: ~~~ - sudo yum downgrade package-version + sudo dnf downgrade package-version ~~~ ### How to re-install a package @@ -76,21 +76,21 @@ You can re-install in a similar fashion to downgrading. sudo qubes-dom0-update package ~~~ - Yum will say that there is no update, but the package will nonetheless be downloaded to dom0. + Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0. 2. Re-install the package: ~~~ - sudo yum reinstall package + sudo dnf reinstall package ~~~ - Note that yum will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. + Note that Dnf will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. ### How to uninstall a package If you've installed a package such as anti-evil-maid, you can remove it with the following command: - sudo yum remove anti-evil-maid + sudo dnf remove anti-evil-maid ### Testing repositories @@ -124,8 +124,16 @@ is needed for the VMs. (Note that the following example enables the unstable rep sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm ~~~ -Rebuild grub config. +If the update process does not automatically do it (you should see it mentioned in the CLI output +from the update command), you may need to manually rebuild the EFI or grub config depending on which +your system uses. +EFI (Replace the file names with the correct versions for your updated kernel) +~~~ +sudo /usr/bin/dracut -f /boot/efi/EFI/qubes/initramfs-4.4.31-11.pvops.qubes.x86_64.img 4.4.31-11.pvops.qubes.x86_64 +~~~ + +Grub2 ~~~ sudo grub2-mkconfig -o /boot/grub2/grub.cfg ~~~ diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index bbb189ac..2f04d888 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -18,20 +18,24 @@ Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their In addition to saving on the disk space, and reducing domain creation time, another advantage of such scheme is the possibility for centralized software update. It's just enough to do the update in the template VM, and then all the AppVMs based on this template get updates automatically after they are restarted. -The default template is called **fedora-14-x64** in Qubes R1 and **fedora-20-x64** in Qubes R2. +The default template is called **fedora-23** in Qubes R3.2 and **fedora-26** in Qubes R4.0. -The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home` or `/usr/local` then it will disappear after the AppVM reboot (as the root filesystem for this AppVM will again be "taken" from the TemplateVM). **This means one normally installs software in the TemplateVM, not in AppVMs.** +The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home`, `/usr/local`, or `/rw` then it will disappear after the AppVM reboots (as the root filesystem for this AppVM will again be "taken" from the TemplateVM). **This means one normally installs software in the TemplateVM, not in AppVMs.** -Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/template/fedora/upgrade-23-to-24/#compacting-the-upgraded-template) to recover space in dom0. +Unlike VM private filesystems, under R3.x the template VM root filesystem does not support discard by default, so deleting files does not free the space in dom0. See [these instructions](/doc/template/fedora/upgrade-23-to-24/#compacting-the-upgraded-template) to recover space in dom0. + +In R4.0 and higher, the template root filesystem is created in a thin pool so manual trims are no longer needed. + +See [here](/doc/disk-trim) for further discussion on enabling discards/trim support under all versions. Installing (or updating) software in the TemplateVM ---------------------------------------------------- In order to permanently install new software, you should: -- Start the template VM and then start either console (e.g. `gnome-terminal`) or dedicated software management application, such as `gpk-application` (*Start-\>Applications-\>Template: fedora-XX-x64-\>Add/Remove software*), +- Start the template VM and then start either console (e.g. `gnome-terminal`) or dedicated software management application, such as `gpk-application` (*Start-\>Applications-\>Template: fedora-XX-\>Add/Remove software*), -- Install/update software as usual (e.g. using yum, or the dedicated GUI application). Then, shutdown the template VM, +- Install/update software as usual (e.g. using dnf, or the dedicated GUI application). Then, shutdown the template VM, - You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You can restart others whenever this will be convenient to you. @@ -73,9 +77,14 @@ Debian also has three Qubes VM testing repositories (where `*` denotes the Relea repository; mostly experimental debugging packages To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in -`/etc/apt/sources.list.d/qubes-r3.list` +`/etc/apt/sources.list.d/qubes-r*.list` -Reverting changes to a TemplateVM +Reverting changes to a TemplateVM (R4.0) +--------------------------------- + +TBD- Qubes 4.0 uses a CoW system that permits snapshotting. To revert changes, one would... + +Reverting changes to a TemplateVM (R3.2) --------------------------------- Perhaps you've just updated your TemplateVM, and the update broke your template. @@ -123,7 +132,7 @@ There are several ways to deal with this problem: Some popular questions: -- So, why should we actually trust Fedora repos -- it also contains large amount of 3rd party software that might buggy, right? +- So, why should we actually trust Fedora repos -- it also contains large amount of third-party software that might buggy, right? As far as the template's compromise is concerned, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and get infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise. @@ -168,14 +177,14 @@ qvm-create --template --label