diff --git a/about/experts.md b/about/experts.md index eb1d15d9..efb79623 100644 --- a/about/experts.md +++ b/about/experts.md @@ -7,7 +7,7 @@ permalink: /experts/
-

What the experts are saying about Qubes

+

What the experts are saying about Qubes

diff --git a/about/faq.md b/about/faq.md index 556bfbae..1feb568f 100644 --- a/about/faq.md +++ b/about/faq.md @@ -431,7 +431,7 @@ The encrypted partitions are identified and the user is prompted for password on A fully encrypted drive does not appear in Nautilus. -The work round is to manually decrypt and mount the drive: +The workaround is to manually decrypt and mount the drive: 1. attach usb device to qube - it should be attached as /dev/xvdi or similar. 2. sudo cryptsetup open /dev/xvdi bk --type luks @@ -461,6 +461,15 @@ If it seems like the issue described in [this thread](https://github.com/QubesOS 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 diff --git a/basics_dev/coding-style.md b/basics_dev/coding-style.md index 35477e43..f37e2b90 100644 --- a/basics_dev/coding-style.md +++ b/basics_dev/coding-style.md @@ -97,7 +97,7 @@ General programming style guidelines } ~~~ -- Do **not** use comments to disable code fragments. In a production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.: +- Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.: ~~~ #if 0 @@ -130,7 +130,7 @@ Source Code management (Git) guidelines - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. - By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code. - Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source. - - We have drastically changes the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html). + - We have drastically changed the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html). Commit message guidelines ------------------------- @@ -165,7 +165,7 @@ Security coding guidelines height = untrusted_conf.height; ~~~ -- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above. +- Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above. Python-specific guidelines -------------------------- @@ -178,7 +178,7 @@ C and C++ specific guidelines - Do not place code in `*.h` files. - Use `const` whenever possible, e.g. in function arguments passed via pointers. - Do not mix procedural and objective code together -- if you write in C++, use classes and objects. -- Think about classes hierarchy, before start implementing specific methods. +- Think about classes hierarchy, before starting to implement specific methods. Bash-specific guidelines ------------------------ diff --git a/basics_dev/style-guide.md b/basics_dev/style-guide.md index 160e8666..32f0259a 100644 --- a/basics_dev/style-guide.md +++ b/basics_dev/style-guide.md @@ -68,7 +68,7 @@ Currently, all the icons on the Qubes-OS.org website are generated using [FontAw ## Logos -The following is a collection of various sizes & versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork). +The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
{% for logo in site.data.styleguide.logos %} diff --git a/basics_dev/usability-ux.md b/basics_dev/usability-ux.md index b8762d0e..03747bd0 100644 --- a/basics_dev/usability-ux.md +++ b/basics_dev/usability-ux.md @@ -44,7 +44,7 @@ In making software easy to use, it is crucial to be mindful of [cognitive load]( ## Easy to Understand -There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none these are absolute maxims! +There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none of these are absolute maxims!
Avoid Acronyms @@ -82,7 +82,7 @@ Technical words are usually more accurate, but they often *only* make sense to t - `savefile` - `qrexec-daemon` -These are all terms that have at some point showed up in users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpet. +These are all terms that have at some point showed up in users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpret.
Use Common Concepts @@ -195,7 +195,7 @@ There are many cases where a user wants to perform an action on more than one fi 3. Select proper file 4. Complete task on file -That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couples files in the same directory. We can alleviate some of the work by changing the process: +That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couple files in the same directory. We can alleviate some of the work by changing the process: 1. Click on `Open File` from a menu or button 2. Remember last open folder/file system diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index 428dd376..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 GitHub's 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,18 @@ 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 ------------------------------ diff --git a/basics_user/getting-started.md b/basics_user/getting-started.md index 691e8ebd..31d345ea 100644 --- a/basics_user/getting-started.md +++ b/basics_user/getting-started.md @@ -134,10 +134,6 @@ Otherwise, a compromised qube which is able to occupy the entire screen could tr Since a compromised qube can draw pixels within its own windows however it likes, it could draw a fake password prompt, for example, which appears to have a different colored border so that it looks like it belongs to a different qube. This is why you should always drag such prompts away from other windows (or use some other means of manipulating the windows) to ensure that they belong to the qube to which they appear to belong. -However, if the user makes use of an "expose-like" desktop switcher, such as the "Desktop Grid" effect that is enabled by default under KDE (default activation command: Ctrl-F8), then we can safely allow qubes to enter full screen mode, as we have assurance that we can always "preempt" them by hitting the magic key combination (e.g., Ctrl-F8), which will be consumed by the trusted window manager and not passed down to the fullscreen qube. -This means that the qube has no way of effectively "faking" the fullscreen view of the system, as the user can easily identify it as "just another qube." -Theoretically, this could be achieved even with primitive Alt-Tab like switching, which should be available on simpler Window Managers (such as Xfce4, which we also support as an alternative dom0 Desktop Environment), but this might be less obvious to the user. - To allow a qube to enter full screen mode, one should edit the `/etc/qubes/guid.conf` file in dom0. To allow all qubes to enter full screen mode, set `allow_fullscreen` flag to `true` in the `global` section: diff --git a/building/building-archlinux-template.md b/building/building-archlinux-template.md index ff701a4d..a9989c0d 100644 --- a/building/building-archlinux-template.md +++ b/building/building-archlinux-template.md @@ -362,7 +362,7 @@ redirect_from: The `qubes-mgmt-salt` repo is not currently forked under the marmarek user on GitHub, to whom the above instructions set the `GIT_PREFIX`. As Archlinux is not yet supported by mgmt-salt, simply leave it out of the build (when building -the Archlinux template on it's own) by appending the following to your `override.conf` file: +the Archlinux template on its own) by appending the following to your `override.conf` file: `BUILDER_PLUGINS := $(filter-out mgmt-salt,$(BUILDER_PLUGINS))` diff --git a/building/development-workflow.md b/building/development-workflow.md index 4ddce81f..3f9b2fcd 100644 --- a/building/development-workflow.md +++ b/building/development-workflow.md @@ -419,7 +419,7 @@ Remember to also import gpg public key using `rpm --import`. ### Deb packages - Apt repo -Steps are mostly the same as in case of yum repo. Only details differs: +Steps are mostly the same as in the case of yum repo. The only details that differ: - use [linux-deb] instead of [linux-yum] as a base - both in source and target VM - use different `update_repo.sh` script in source VM (below) diff --git a/building/qubes-builder-details.md b/building/qubes-builder-details.md index 735c4cc5..48e5e7d6 100644 --- a/building/qubes-builder-details.md +++ b/building/qubes-builder-details.md @@ -33,8 +33,8 @@ Variables for Windows build: - `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables: - `CERT_FILENAME` Path to key file (pfx format) - `CERT_PASSWORD` Key password - - `CERT_PUBLIC_FILENAME` Certificate path in case of self-signed cert - - `CERT_CROSS_CERT_FILENAME` Certificate path in case of correct autheticode cert + - `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert + - `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert - `SIGNTOOL` Path to signtool - `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command. - `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components. diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 24be5e44..4d9bd8f8 100644 --- a/common-tasks/backup-restore.md +++ b/common-tasks/backup-restore.md @@ -215,7 +215,7 @@ Here are some things to consider when selecting a passphrase for your backups: 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 othe 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. + 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 ----- diff --git a/common-tasks/copy-from-dom0.md b/common-tasks/copy-from-dom0.md index 524b553a..2e9dd92e 100644 --- a/common-tasks/copy-from-dom0.md +++ b/common-tasks/copy-from-dom0.md @@ -21,66 +21,49 @@ To copy a file from dom0 to a VM (domU), simply use `qvm-copy-to-vm`: qvm-copy-to-vm ~~~ -The file will arrive in your destination VM in the `~/QubesIncoming/dom0/` -directory. +The file will arrive in your destination VM in the `~/QubesIncoming/dom0/` directory. ### Copying logs from Dom0 ### -In order to easily copy/paste the contents of logs from dom0 to the inter-VM -clipboard, you can simply: +In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard, you can simply: 1. Right-click on the desired VM in the Qubes VM Manager. 2. Click "Logs." 3. Click on the desired log. 4. Click "Copy to Qubes clipboard." -You may now paste the log contents to any VM as you normally would (i.e., -Ctrl-Shift-V, then Ctrl-V). +You may now paste the log contents to any VM as you normally would (i.e., Ctrl-Shift-V, then Ctrl-V). ### Copy/paste from Dom0 ### For data other than logs, there are several options: 1. Copy it as a file (see above) -2. Since updated versions of 3.2 you can copy text to the dom0 clipboard - (Ctrl-C as normal), then click "Copy Dom0 clipboard" in the Qubes menu: +2. In Qubes 3.2 you can copy text to the dom0 clipboard (Ctrl-C as normal), then click "Copy Dom0 clipboard" in the Qubes menu: ![copy-dom0-clipboard](/attachment/wiki/QubesScreenshots/r3.2-dom0-copyout.png) which is equivelant to Ctrl-Shift-C from a normal AppVM. - Then you can use Ctrl-Shift-V and Ctrl-V to paste the copied text into an - AppVM as normal. -3. In older versions, write the data you wish to copy into - `/var/run/qubes/qubes-clipboard.bin`, then write "dom0" to - `/var/run/qubes/qubes-clipboard.bin.source`. + Then you can use Ctrl-Shift-V and Ctrl-V to paste the copied text into an AppVM as normal. +3. In other versions, write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`. Then use Ctrl-Shift-V to paste the data to the desired VM. Copying **to** Dom0 ------------------- -There should normally be few reasons for the user to want to copy files from VMs -to Dom0, as Dom0 only acts as a "thin trusted terminal", and no user -applications run there. Copying untrusted files to Dom0 is not advised and may -compromise the security of your Qubes system. Because of this, we do not provide -a graphical user interface for it, unlike [copying files between -VMs](/doc/copying-files/). +There should normally be few reasons for the user to want to copy files from VMs to Dom0, as Dom0 only acts as a "thin trusted terminal", and no user applications run there. +Copying untrusted files to Dom0 is not advised and may compromise the security of your Qubes system. +Because of this, we do not provide a graphical user interface for it, unlike [copying files between VMs](/doc/copying-files/). -One common use-case for this is if we want to use a desktop wallpaper in Dom0 we -have located in one of our AppVMs (e.g. in the 'personal' AppVM where we got the -wallpaper from our camera or downloaded it from the Internet). While it's a -well-justified reason, imagine what would happen if the wallpaper (e.g. a JPEG -file) was somehow malformed or malicious and attempted to exploit a hypothetical -JPEG parser bug in Dom0 code (e.g. in the Dom0's Xorg/KDE code that parses the -wallpaper and displays it). +One common use-case for this is if we want to use a desktop wallpaper in Dom0 we have located in one of our AppVMs (e.g. in the 'personal' AppVM where we got the wallpaper from our camera or downloaded it from the Internet). +While it's a well-justified reason, imagine what would happen if the wallpaper (e.g. a JPEG file) was somehow malformed or malicious and attempted to exploit a hypothetical JPEG parser bug in Dom0 code (e.g. in the Dom0's Xorg/KDE code that parses the wallpaper and displays it). -If you are determined to copy some files to Dom0 anyway, you can use the -following method (run this command from Dom0's console): +If you are determined to copy some files to Dom0 anyway, you can use the following method (run this command from Dom0's console): ~~~ qvm-run --pass-io 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0 ~~~ -You can use the same method to copy files from Dom0 to VMs (if, for some reason, -you don't want to use `qvm-copy-to-vm`): +You can use the same method to copy files from Dom0 to VMs (if, for some reason, you don't want to use `qvm-copy-to-vm`): ~~~ cat /path/to/file_in_dom0 | qvm-run --pass-io 'cat > /path/to/file_name_in_appvm' diff --git a/common-tasks/dispvm.md b/common-tasks/dispvm.md index cda6ce0c..31e477a6 100644 --- a/common-tasks/dispvm.md +++ b/common-tasks/dispvm.md @@ -11,16 +11,56 @@ redirect_from: Disposable VMs (DispVMs) ======================== -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 will disappear when closed. +Disposable VMs are usually created in order to host a single application, like a viewer, editor, or web browser. + +From inside an AppVM, choosing the `Open in Disposable VM` option on a file will launch a DispVM for just that file. +Changes made to a file opened in a DispVM 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 launched either directly from Dom0's Start Menu or terminal window, or from within AppVMs. +While running, DispVMs will appear in Qubes VM Manager with the name `disp####`. 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. -Disposable VMs and Networking + +Disposable VMs and Networking (R4.0 and later) +----------------------------- + +Similarly to how AppVMs are based on their underlying [TemplateVM](https://www.qubes-os.org/doc/glossary/#templatevm), DispVMs are based on their underlying [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template). +R4.0 introduces the concept of multiple DVM Templates, whereas R3.2 was limited to only one. + +On a fresh installation of Qubes, the default DVM Template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM). +If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` DVM Template available for your use. + +You can set any AppVM to have the ability to act as a DVM Template with: + + qvm-prefs template_for_dispvms true + +The default system wide DVM Template can be changed with `qubes-prefs default_dispvm`. +By combining the two, choosing `Open in Disposable VM` from inside an AppVM will open the document in a DispVM based on the default DVM Template you specified. + +You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab. +Here you can edit the "Default DispVM" setting to specify which DVM Template will be used to launch DispVMs from that VM. +This can also be changed from the command line with: + + qvm-prefs default_dispvm + +For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default. +You can even set an AppVM that has also been configured as a DVM Template to use itself, so DispVMs launched from within the AppVM/DVM Template would inherit the same settings. + +NetVM and firewall rules for DVM Templates can be set as they can for a normal VM. +By default a DispVM will inherit the NetVM and firewall settings of the DVM Template on which it is based. +This is a change in behaviour from R3.2, where DispVMs would inherit the settings of the AppVM from which they were launched. +Therefore, launching a DispVM from an AppVM will result in it using the network/firewall settings of the DVM Template on which it is based. +For example, if an AppVM uses sys-net as its NetVM, but the default system DispVM uses sys-whonix, any DispVM launched from this AppVM will have sys-whonix as its NetVM. + +**Warning:** The opposite is also true. This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DispVM uses sys-net, launching a DispVM from inside anon-whonix will result in the DispVM using sys-net. + +A Disposable VM launched from the Start Menu inherits the NetVM and firewall settings of the DVM Template on which it is based. +Note that changing the "NetVM" setting for the system default DVM Template *does* affect the NetVM of DispVMs launched from the Start Menu. +Different DVM Templates with individual NetVM settings can be added to the Start Menu. + +Disposable VMs and Networking (R3.2 and earlier) ----------------------------- NetVM and firewall rules for Disposable VMs can be set as they can for a normal VM. @@ -49,7 +89,7 @@ Opening a fresh web browser instance in a new Disposable VM ----------------------------------------------------------- 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. +This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> 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. @@ -75,7 +115,7 @@ Sometimes it can be useful to start an arbitrary program in a DispVM. This can b [user@vault ~]$ qvm-run '$dispvm' xterm ~~~ -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`. +The created Disposable VM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`. Starting an arbitrary application in a Disposable VM via command line (from Dom0) --------------------------------------------------------------------------------- @@ -83,6 +123,12 @@ 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 +R4.0 (border colour will be inherited from that set in the `dispvm-template`) +~~~ +[joanna@dom0 ~]$ qvm-run --dispvm=dispvm-template --service qubes.StartApp+xterm +~~~ + +R3.2 (border colour can be specified in the command) ~~~ [joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red ~~~ @@ -92,8 +138,8 @@ However, it is possible to start an arbitrary application in a DispVM directly f 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. +You can change the template used to generate the Disposable VMs, and change settings used in the Disposable VM savefile. +These changes will be reflected in every new Disposable VM based on that template. Full instructions can be found [here](/doc/dispvm-customization/). Disposable VMs and Local Forensics diff --git a/common-tasks/full-screen-mode.md b/common-tasks/full-screen-mode.md index b0fef0cc..e5542918 100644 --- a/common-tasks/full-screen-mode.md +++ b/common-tasks/full-screen-mode.md @@ -24,7 +24,7 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on Secure use of full screen mode ------------------------------ -However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such q mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts. +However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts. Another option is to use Alt+Tab for switching windows. This shortcut is also handled by dom0. Enabling full screen mode for select VMs diff --git a/common-tasks/managing-appvm-shortcuts.md b/common-tasks/managing-appvm-shortcuts.md index e289ae79..dcbf3613 100644 --- a/common-tasks/managing-appvm-shortcuts.md +++ b/common-tasks/managing-appvm-shortcuts.md @@ -11,15 +11,16 @@ redirect_from: Managing shortcuts to applications in AppVMs ============================================ -For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0. Clicking on such shortcut runs the assigned application in its AppVM. +For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0. +Clicking on such shortcut runs the assigned application in its AppVM. ![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-menu.png) -To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs does this automatically): +To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs do this automatically): `qvm-sync-appmenus vmname` -After that, select the *Add more shortcuts* entry in VM's submenu to customize which applications are shown: +After that, select the *Add more shortcuts* entry in the VM's submenu to customize which applications are shown: ![dom0-appmenu-select.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-appmenu-select.png) @@ -33,16 +34,37 @@ What about applications in DispVMs? Behind the scenes ----------------- -The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`. +`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain. +This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory. -Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'` -Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'` +For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. +In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default. -`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain. This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory. + * R4.0 + + The list of installed applications for each AppVM is stored in dom0's `~/.local/share/qubes-appmenus/vmname/apps.templates`. + Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). + Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/vmname/apps`. + + Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. + Examples: `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager` or `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox` -For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default. + Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox` + + * R3.2 + + The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). + Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). + Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`. + + Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. + Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'` + + Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'`. What if my application has not been automatically included in the list of available apps? ----------------------------------------------------------------------------------------- -You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a worked example of creating a new menu item for a Chrome .desktop shortcut. +You can manually create new entries in the "available applications" list of shortcuts. +See [Signal](/doc/signal/) for a working example of creating a new menu item for a Chrome .desktop shortcut. + diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index e39a1f2c..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 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.) 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: diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index 2feab516..06f49226 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -14,15 +14,20 @@ Installing and updating software in VMs How TemplateVMs work in Qubes ------------------------------ -Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way. +Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. +This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). +Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way. -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. +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-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`, `/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.** +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, 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. +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. @@ -35,9 +40,13 @@ 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-\>Add/Remove software*), -- Install/update software as usual (e.g. using dnf, 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 will restart others whenever this will be convenient to you. +- 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. Testing repositories -------------------- @@ -46,15 +55,12 @@ Testing repositories There are three Qubes VM testing repositories (where `*` denotes the Release): -* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable - (`current`) repository -* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages - that qualify as security fixes -* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) - repository; mostly experimental debugging packages +* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository +* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes +* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages -To temporarily enable any of these repos, use the `--enablerepo=` -option. Example commands: +To temporarily enable any of these repos, use the `--enablerepo=` option. +Example commands: ~~~ sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing @@ -62,50 +68,42 @@ sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing sudo dnf upgrade --enablerepo=qubes-vm-*-unstable ~~~ -To enable or disable any of these repos permanently, change the corresponding boolean in -`/etc/yum.repos.d/qubes-*.repo`. +To enable or disable any of these repos permanently, change the corresponding boolean in `/etc/yum.repos.d/qubes-*.repo`. ### Debian ### Debian also has three Qubes VM testing repositories (where `*` denotes the Release): -* `*-testing` -- testing packages that will eventually land in the stable - (`current`) repository -* `*-securitytesting` -- a subset of `*-testing` that contains packages - that qualify as security fixes -* `*-unstable` -- packages that are not intended to land in the stable - repository; mostly experimental debugging packages +* `*-testing` -- testing packages that will eventually land in the stable (`current`) repository +* `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes +* `*-unstable` -- packages that are not intended to land in the stable 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-r*.list` +To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list` Reverting changes to a TemplateVM (R4.0) --------------------------------- -TBD- Qubes 4.0 uses a CoW system that permits snapshotting. To revert changes, one would... +Qubes 4.0 uses a CoW system that permits snapshotting. +Reversion functionality is still being developed at the time of writing. +See [issue #3256](https://github.com/QubesOS/qubes-issues/issues/3256) for details. Reverting changes to a TemplateVM (R3.2) --------------------------------- Perhaps you've just updated your TemplateVM, and the update broke your template. -Or perhaps you've made a terrible mistake, like accidentally confirming the -installation of an unsigned package that could be malicious. Fortunately, -it's easy to revert changes to TemplateVMs using the -`qvm-revert-template-changes` command. +Or perhaps you've made a terrible mistake, like accidentally confirming the installation of an unsigned package that could be malicious. +Fortunately, it's easy to revert changes to TemplateVMs using the `qvm-revert-template-changes` command. -**Important:** This command will roll back any changes made *during the last -time the TemplateVM was run, but **not** before.* This means that if you have -already restarted the TemplateVM, using this command is unlikely to help, and -you'll likely want to reinstall it from the repository instead. On the other -hand, if the template is already broken or compromised, it won't hurt to try -reverting first. Just make sure to **back up** all of your data and changes -first! +**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.* +This means that if you have already restarted the TemplateVM, using this command is unlikely to help, and you'll likely want to reinstall it from the repository instead. +On the other hand, if the template is already broken or compromised, it won't hurt to try reverting first. +Just make sure to **back up** all of your data and changes first! For example, to revert changes to the `fedora-23` TemplateVM: 1. Shut down all VMs based on `fedora-23`. -2. Shut down `fedora-23`. If you've already just shut it down, do **not** start - it again (see above). +2. Shut down `fedora-23`. + If you've already just shut it down, do **not** start it again (see above). 3. In a dom0 terminal, type: qvm-revert-template-changes fedora-23 @@ -114,46 +112,63 @@ For example, to revert changes to the `fedora-23` TemplateVM: qvm-revert-template-changes --force fedora-23 -For the technical details about how this command works and the steps it -performs, see [here](/doc/template-implementation/#rollback-template-changes). +For the technical details about how this command works and the steps it performs, see [here](/doc/template-implementation/#rollback-template-changes). Notes on trusting your TemplateVM(s) ------------------------------------- -As the TemplateVM is used for creating filesystems for other AppVMs, where you actually do the work, it means that the TemplateVM is as trusted as the most trusted AppVM based on this template. In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise. +As the TemplateVM is used for creating filesystems for other AppVMs where you actually do the work, it means that the TemplateVM is as trusted as the most trusted AppVM based on this template. +In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise. There are several ways to deal with this problem: -- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos. +- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. + All those packages are signed by Fedora, and we expect that at least the package's installation scripts are not malicious. + This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos. - Use *standalone VMs* (see below) for installation of untrusted software packages. -- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from somehow less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos. +- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos. Some popular questions: -- So, why should we actually trust Fedora repos -- it also contains large amount of third-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 be buggy, right? -As long as template's compromise is considered, 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 got 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. +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 `/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. - But why trust Fedora? -Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages). We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0. We had to trust *somebody* as we are unable to write all the software from scratch ourselves. But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-exploitable. We certainly do not assume the latter. +Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages). +We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0. +We had to trust *somebody* as we are unable to write all the software from scratch ourselves. +But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-exploitable. +We certainly do not assume the latter. - So, are the template VMs as trusted as Dom0? -Not quite. Dom0 compromise is absolutely fatal, and it leads to Game OverTM. However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM. Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow. +Not quite. +Dom0 compromise is absolutely fatal, and it leads to Game OverTM. +However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). +Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM. +Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow. Standalone VMs -------------- -Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on its own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them. +Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own. +But this means that they take a few GBs on disk, and also that centralized updates do not apply to them. -Sometime it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.: +Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. +Such situations include e.g.: -- VMs used for development (devel environments requires a lot of \*-devel packages and specific devel tools) +- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools) -- VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages form less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way. +- VMs used for installing untrusted packages. + Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). + However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way. In order to create a standalone VM you can use a command line like this (from console in Dom0): @@ -166,9 +181,14 @@ qvm-create --standalone --label