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/about/faq.md b/about/faq.md index b21f41c2..1feb568f 100644 --- a/about/faq.md +++ b/about/faq.md @@ -113,7 +113,7 @@ At the same time, due to the smart use of Xen shared memory, our GUI implementat ### 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? @@ -193,7 +193,7 @@ 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](https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/) and [Core Stack](https://www.qubes-os.org/news/2017/10/03/core3/) for more 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? @@ -345,14 +345,14 @@ Another solution would be to set the pci_strictreset option in dom0: - 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/)): - qvm-pci attach -persistent -option no-strict-reset=true usbVM dom0: + 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 note on [this page](https://www.qubes-os.org/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk. +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? @@ -371,6 +371,8 @@ or 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. @@ -413,7 +415,7 @@ For Fedora: 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. -In Qubes 4.0, this is accomplished with the 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 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. @@ -429,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 @@ -459,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/gsoc.md b/basics_dev/gsoc.md index f285fcf8..9ed852cc 100644 --- a/basics_dev/gsoc.md +++ b/basics_dev/gsoc.md @@ -36,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: @@ -86,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 @@ -166,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. @@ -181,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 @@ -231,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 @@ -315,31 +326,7 @@ immune to altering past entries. See - systemd - Python/Bash scripting -**Mentor**: Inquire on [qubes-devel][ml-devel]. - -### 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**: Inquire on [qubes-devel][ml-devel]. +**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) @@ -379,7 +366,7 @@ 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 @@ -387,7 +374,11 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). - make connections to IPv6 Tor relays work - make connections to IPv6 destinations work -**Knowledge prerequisite**: +**Knowledge prerequisite**: + +- nftables +- iptables +- IPv6 **Mentor**: [Patrick Schleizer](/team/) @@ -413,8 +404,8 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **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) @@ -424,27 +415,7 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **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 @@ -480,6 +451,18 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **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 @@ -489,14 +472,14 @@ details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618). **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/) @@ -504,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 @@ -521,19 +504,8 @@ Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233) **Knowledge prerequisite**: -**Mentor**: +**Mentor**: Inquire on [qubes-devel][ml-devel]. -### 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 ---- We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC). @@ -541,17 +513,17 @@ We adapted some of the language here about GSoC from the [KDE GSoC page](https:/ [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/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/contributing.md b/basics_user/contributing.md index b3e13b22..5a7568b1 100644 --- a/basics_user/contributing.md +++ b/basics_user/contributing.md @@ -75,6 +75,6 @@ be grateful to [receive your patch][patch]. [Facebook]: https://www.facebook.com/QubesOS [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 2c34e0c4..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 ------------------------------ @@ -146,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` @@ -188,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 7a8ebf85..691e8ebd 100644 --- a/basics_user/getting-started.md +++ b/basics_user/getting-started.md @@ -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/reporting-bugs.md b/basics_user/reporting-bugs.md index 7cd31084..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 -your'e 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 2cf48842..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 --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`... @@ -361,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/building/qubes-builder.md b/building/qubes-builder.md index 8ee0172e..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 =========================== diff --git a/common-tasks/backup-restore.md b/common-tasks/backup-restore.md index 0b2ecaa7..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 version, 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 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. + * 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/dispvm.md b/common-tasks/dispvm.md index 3dc72eaa..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. @@ -29,7 +69,7 @@ Thus if an AppVM uses sys-net as its NetVM, any DispVM launched from this AppVM 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. -A Disposable VM launched from the Start Menu inherits the NetVM of the [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template). +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. @@ -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..237d9368 100644 --- a/common-tasks/managing-appvm-shortcuts.md +++ b/common-tasks/managing-appvm-shortcuts.md @@ -15,11 +15,11 @@ For ease of use Qubes aggregates shortcuts to applications that are installed in ![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,7 +33,7 @@ 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`. +The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in the 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'` @@ -45,4 +45,4 @@ For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Wi 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 1c59390f..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 in Qubes 2.0.) 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 6182ff51..f146d312 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -37,7 +37,7 @@ In order to permanently install new software, you should: - 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 -------------------- @@ -125,17 +125,17 @@ As the TemplateVM is used for creating filesystems for other AppVMs, where you a 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? -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 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. - But why trust Fedora? @@ -148,13 +148,13 @@ Not quite. Dom0 compromise is absolutely fatal, and it leads to Game OverTM 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): @@ -178,15 +178,18 @@ qvm-create --template --label