Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-27 16:29:28 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'upstream/master'

Browse Source 
Conflicts:
	managing-os/kali.md
This commit is contained in:
Lorenzo 2017-01-12 10:49:18 +00:00
commit b3c9713842
144 changed files with 4526 additions and 1297 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
CONTRIBUTING.md
View File

@ -2,58 +2,8 @@ Contributing to `qubes-doc`
===========================
Thank you for your interest in contributing to `qubes-doc`, the Qubes OS
Project's dedicated documentation repository! Please take a moment to
familiarize yourself with the terms defined in the [glossary], and try to use
these terms consistently and accurately throughout your writing and editing.
Please report all documentation issues in [qubes-issues].
Markdown 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.
* Hard wrap Markdown lines at 80 characters.
* 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 `[reference-style][ref]` links.
`[ref]: https://daringfireball.net/projects/markdown/syntax#link`
([This][md] is a great source for learning about Markdown.)
Git Conventions
---------------
Please attempt to follow these conventions when writing your Git commit
messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions,
please see [this blog post][git-commit], which is the source of this list.
[glossary]: https://www.qubes-os.org/doc/glossary/
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: http://chris.beams.io/posts/git-commit/
Project's dedicated documentation repository! Please take a moment to read our
[Documentation Guidelines] before you begin writing. These guidelines are
important to maintaining high quality documentation, and following them will
increase the likelihood that your contribution will be accepted.

0
developers/code-signing.md → basics_dev/code-signing.md
View File

15
developers/coding-style.md → basics_dev/coding-style.md
View File

@ -132,6 +132,21 @@ Source Code management (Git) guidelines
- 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](http://theinvisiblethings.blogspot.com/2013/03/introducing-qubes-odyssey-framework.html).
Commit message guidelines
-------------------------
Please attempt to follow these conventions when writing your Git commit messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions, please see [this blog post](http://chris.beams.io/posts/git-commit/), which is the source of this list.
Security coding guidelines
--------------------------

76
basics_dev/contributing.md Normal file
View File

@ -0,0 +1,76 @@
---
layout: doc
title: Contributing to the Qubes OS Project
permalink: /doc/contributing/
redirect_from:
- /en/doc/contributing/
- /doc/ContributingHowto/
- /wiki/ContributingHowto/
---
How to Contribute to the Qubes OS Project
=========================================
Thank you for your interest in contributing to Qubes! Here are some of the many
ways in which you can help:
* Audit the [source code]
* [Report security issues]
* [Send patches][patch] to fix bugs or implement features
* [Report bugs]
* Submit [HCL reports] for your hardware
* Record [video tours]
* Create [artwork] (plymouth themes, installer themes, wallpapers, etc.)
* [Write and edit the documentation]
* [Donate] to the project
* If you represent an organization, become a [Qubes partner]
* Answer questions on the [mailing lists]
* Engage with us on social media:
* Follow us on [Twitter]
* Join us on [Reddit]
* Like us on [Facebook]
* Support our [StackExchange] proposal
* And last but not least, tell your friends and colleagues about how Qubes
can help them secure their digital lives!
Contributing Code
-----------------
If you're interested in contributing code, the best starting point is to have a
look at our [GitHub issues] to see which tasks are the most urgent. You can
filter issues depending on your interest and experience. For example, here are
some common issue labels:
* [Help wanted](https://github.com/QubesOS/qubes-issues/issues?page=3&q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22&utf8=%E2%9C%93)
* [UX and usability](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3AUX)
* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows+tools%22)
* [Documentation](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+doc%22)
* [Privacy](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22privacy%22%20)
* [Debian](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%22)
Before you engage in an activity that will take you a significant amount of
time, e.g. implementing a new feature, it's always good to contact us first,
preferably via the [qubes-devel] mailing list. Once we've worked out the
details, we'll add you to our [Community-Developed Feature Tracker]. We'll then
be grateful to [receive your patch][patch].
[source code]: /doc/source-code/
[Report security issues]: /security/
[patch]: /doc/source-code/#how-to-send-patches
[Report bugs]: /doc/reporting-bugs/
[HCL reports]: /doc/hcl/
[video tours]: /video-tours/
[artwork]: https://github.com/QubesOS/qubes-artwork
[Write and edit the documentation]: /doc/doc-guidelines
[mailing lists]: /mailing-lists/
[Donate]: /donate/
[Qubes partner]: /partners/
[Twitter]: https://twitter.com/QubesOS
[Reddit]: https://www.reddit.com/r/Qubes/
[Facebook]: https://www.facebook.com/QubesOS
[StackExchange]: https://area51.stackexchange.com/proposals/98519/qubes-os
[GitHub issues]: https://github.com/QubesOS/qubes-issues/issues
[qubes-devel]: /mailing-lists/#qubes-devel
[Community-Developed Feature Tracker]: https://www.qubes-os.org/qubes-issues/

8
developers/devel-books.md → basics_dev/devel-books.md
View File

@ -11,14 +11,14 @@ redirect_from:
Below is a list of various books that might be useful in learning some basics needed for Qubes development.
- A must-read about Xen internals:
- [http://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X](http://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)
- [https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)
- Some good books about Linux kernel:
- [http://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672327201](http://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672327201)
- [http://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903](http://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)
- [https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468]
- [https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)
- Solid intro into Trusted Computing by David Grawrock (original Intel architect for TXT):
- [http://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082](http://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)
- [https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)
- Good book about GIT:
- [http://progit.org/book/](http://progit.org/book/)

31
developers/devel-faq.md → basics_dev/devel-faq.md
View File

@ -18,19 +18,6 @@ Since 2013 [Xen has not supported 32-bit x86 architecture](http://wiki.xenprojec
In addition, often it is more difficult to exploit a bug on the x64 Linux than it is on x86 Linux (e.g. ASLR is sometimes harder to get around). While we designed Qubes with the emphasis on limiting any potential attack vectors in the first place, still we realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, even though it is very simple code, might contain some bugs. Plus currently we haven't implemented a separate storage domain, so also the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface. So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer, as the 64-bit option provides some (little perhaps, but still) more protection against some classes of attacks, and at the same time does not have any disadvantages (except that it requires a 64-bit processor, but all systems on which it makes sense to run Qubes, e.g. that have at least 3-4GB memory, they do have 64-bit CPUs anyway).
Q: Why do you use KDE in Dom0? What is the roadmap for Gnome support?
---------------------------------------------------------------------
There are a few things that are KDE-specific, but generally it should not be a big problem to also add Gnome support to Qubes (in Dom0 of course). Those KDE-specific things are:
- Qubes requires KDM (KDE Login Manager), rather than GDM, for the very simple reason that GDM doesn't obey standards and start `/usr/bin/Xorg` instead of `/usr/bin/X`. This is important for Qubes, because we need to load a special "X wrapper" (to make it possible to use Linux usermode shared memory to access Xen shared memory pages in our App Viewers -- see the sources [here](https://github.com/QubesOS/qubes-gui-daemon/tree/master/shmoverride)). So, Qubes makes the `/usr/bin/X` to be a symlink to the Qubes X Wrapper, which, in turn, executes the `/usr/bin/Xorg`. This works well with KDM (and would probably also work with other X login managers), but not with GDM. If somebody succeeded in makeing GDM to execute `/usr/bin/X` instead of `/usr/bin/Xorg`, we would love to hear about it!
- We maintain a special [repository](/doc/kde-dom0/) for building packages specifically for Qubes Dom0.
- We've patched the KDE's Window Manager (specifically [one of the decoration plugins](https://github.com/QubesOS/qubes-desktop-linux-kde/tree/master/plastik-for-qubes)) to draw window decorations in the color of the specific AppVM's label.
If you're interested in porting GNOME for Qubes Dom0 use, let us know -- we will most likely welcome patches in this area.
Q: What is the recommended build environment?
---------------------------------------------
@ -45,3 +32,21 @@ Q: How do I submit a patch?
---------------------------
See [Qubes Source Code Repositories](/doc/source-code/).
Q: What is Qubes' attitude toward changing guest distros?
---------------------------------------------------------
We try to respect each distro's culture, where possible. See the discussion on
issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an
example.
The policy is there mostly to ease maintenance, on several levels:
* Less modifications means easier migration to new upstream distribution
releases
* Upstream documentation matching the distribution running in Qubes VM
* Less likely to introduce Qubes-specific issues
* Each officially supported distribution (ideally) should offer the same set of
Qubes-specific features - a change in one supported distribution should be
followed also in others (including some new in the future)

17
developers/doc-guidelines.md → basics_dev/doc-guidelines.md
View File

@ -141,19 +141,8 @@ making contributions, please try to observe the following style conventions:
Git Conventions
---------------
Please attempt to follow these conventions when writing your Git commit
messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions,
please see [this blog post][git-commit], which is the source of this list.
Please try to write good commit messages, according to the
[instructions in our coding style guidelines][git-commit].
[qubes-doc]: https://github.com/QubesOS/qubes-doc
@ -165,4 +154,4 @@ please see [this blog post][git-commit], which is the source of this list.
[gh-pull]: https://help.github.com/articles/using-pull-requests/
[GitHub]: https://github.com/
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: http://chris.beams.io/posts/git-commit/
[git-commit]: /doc/coding-style/#commit-message-guidelines

0
developers/license.md → basics_dev/license.md
View File

90
basics_dev/reporting-bugs.md Normal file
View File

@ -0,0 +1,90 @@
---
layout: doc
title: Reporting Bugs
permalink: /doc/reporting-bugs/
redirect_from:
- /en/doc/reporting-bugs/
- /doc/BugReportingGuide/
- /wiki/BugReportingGuide/
- /reporting-bugs/
- /bug/
- /bugs/
- /bug-report/
- /bug-reports/
---
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/).
Before you submit a report
--------------------------
Before you submit a bug report, please take a moment to check whether your issue
has already been reported and to determine which venue is most approriate 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].
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 submit a report on the mailing lists
-------------------------------------------
Please see the [mailing list guidelines][mailing list].
How to submit a report on GitHub
--------------------------------
We track all bugs in the [qubes-issues] tracker on GitHub.
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`.
Project maintainers really appreciate thorough explanations. It usually
helps them address the problem more quickly, so everyone wins!
Improving the Code
------------------
Please see our guidelines on [how to contribute code].
[contribute to the Qubes OS Project]: /doc/contributing/
[documentation]: /doc/
[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
[how to contribute code]: /doc/contributing/#contributing-code

13
developers/source-code.md → basics_dev/source-code.md
View File

@ -53,11 +53,17 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su
How to Send Patches
-------------------
If you want to contribute code to the project, there are two ways. Whichever
If you want to [contribute code] to the project, there are two ways. Whichever
method you choose, you must [sign your code] before it can be accepted.
* **Preferred**: Use GitHub's [fork & pull requests].
* Send a patch to our developer [mailing list] (`git format-patch`).
Opening a pull request on GitHub greatly eases the code review and tracking
process. In addition, especially for bigger changes, it's a good idea to send
a message to the [qubes-devel mailing list] in order to notify people who
do not receive GitHub notifications.
* Send a patch to the [qubes-devel mailing list] (`git format-patch`).
1. Make all the changes in your working directory, i.e. edit files, move them
around (you can use 'git mv' for this), etc.
@ -75,7 +81,8 @@ method you choose, you must [sign your code] before it can be accepted.
[QubesOS GitHub account]: https://github.com/QubesOS/
[contribute code]: /doc/contributing/#contributing-code
[sign your code]: /doc/code-signing/
[fork & pull requests]: https://guides.github.com/activities/forking/
[mailing list]: /doc/mailing-lists/
[qubes-devel mailing list]: /mailing-lists/#qubes-devel

0
developers/style-guide.md → basics_dev/style-guide.md
View File

12
basics_dev/system-doc.md Normal file
View File

@ -0,0 +1,12 @@
---
layout: doc
title: System Documentation
permalink: /doc/system-doc/
redirect_from:
- /en/doc/system-doc/
- /doc/SystemDoc/
- /wiki/SystemDoc/
redirect_to:
- /doc/#developer-documentation
---

2
developers/usability-ux.md → basics_dev/usability-ux.md
View File

@ -212,6 +212,8 @@ Clearly, cutting out navigating through the file system can save a user quite a
The the desktop GUIs which QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org), as well as [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, however, we believe the overalluser experience of GNOME is more focused on simplicity and ease of use for average non-technical users. Xfce will always be supported, and technical users will always be able to still use KDE or other desktop environments.
This means you should use GTK rather than Qt for new GUIs.
All three desktop environments have their own [human interface guidelines](https://en.wikipedia.org/wiki/Human_interface_guidelines) and we suggest you familiarize yourself with the platform you developing for.
- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/3.18/)

86
basics/user-faq.md → basics_user/user-faq.md
View File

@ -15,6 +15,7 @@ Qubes Users' FAQ
---------------------------------------
* [Is Qubes just another Linux distribution?](#is-qubes-just-another-linux-distribution)
* [How is Qubes different from other security solutions?](#how-is-qubes-different-from-other-security-solutions)
* [Does Qubes use full disk encryption (FDE)?](#does-qubes-use-full-disk-encryption-fde)
* [What is the main concept behind Qubes?](#what-is-the-main-concept-behind-qubes)
* [What about other approaches to security?](#what-about-other-approaches-to-security)
* [What about safe languages and formally verified microkernels?](#what-about-safe-languages-and-formally-verified-microkernels)
@ -29,7 +30,8 @@ Qubes Users' FAQ
* [Is Qubes a multi-user system?](#is-qubes-a-multi-user-system)
* [Why passwordless sudo?](#why-passwordless-sudo)
* [How should I report documentation issues?](#how-should-i-report-documentation-issues)
* [Will Qubes seek to get certified on the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-gnu-fsdg)
* [Will Qubes seek to get certified on the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-to-get-certified-under-the-gnu-free-system-distribution-guidelines-gnu-fsdg)
* [What does it mean to "distrust the infrastructure"?](#what-does-it-mean-to-distrust-the-infrastructure)
[Installation & Hardware Compatibility](#installation--hardware-compatibility)
------------------------------------------------------------------------------
@ -37,6 +39,7 @@ Qubes Users' FAQ
* [How much memory is recommended for Qubes?](#how-much-memory-is-recommended-for-qubes)
* [Can I install Qubes on a system without VT-x?](#can-i-install-qubes-on-a-system-without-vt-x)
* [Can I install Qubes on a system without VT-d?](#can-i-install-qubes-on-a-system-without-vt-d)
* [What is a DMA attack?](#what-is-a-dma-attack)
* [Can I use AMD-v instead of VT-x?](#can-i-use-amd-v-instead-of-vt-x)
* [Can I install Qubes in a virtual machine (e.g., on VMWare)?](#can-i-install-qubes-in-a-virtual-machine-eg-on-vmware)
* [Why does my network adapter not work?](#why-does-my-network-adapter-not-work)
@ -49,8 +52,9 @@ Qubes Users' FAQ
* [My dom0 and/or TemplateVM update stalls when attempting to update via …](#my-dom0-andor-templatevm-update-stalls-when-attempting-to-update-via-the-gui-tool-what-should-i-do)
* [How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?](#how-do-i-run-a-windows-hvm-in-non-seamless-mode-ie-as-a-single-window)
* [I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.](#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot)
* [I assigned a PCI device to a qube, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube`-why-isnt-the-device-available-in-dom0)
* [How do I install Flash in a Debian qube?](#how-do-i-install-flash-in-a Debian-qube)
* [I assigned a PCI device to a qube, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube-why-isnt-the-device-available-in-dom0)
* [How do I install Flash in a Debian qube?](#how-do-i-install-flash-in-a-debian-qube)
* [How do I play video files?](#how-do-i-play-video-files)
-----------------
@ -66,6 +70,10 @@ If you really want to call it a distribution, then it's more of a "Xen distribut
Please see [this article](http://theinvisiblethings.blogspot.com/2012/09/how-is-qubes-os-different-from.html) for a thorough discussion.
### Does Qubes use full disk encryption (FDE)?
Yes, of course! Full disk encryption is enabled by default. Specifically, we use [`LUKS`](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[`dm-crypt`](https://en.wikipedia.org/wiki/Dm-crypt). You can even [manually configure your encryption parameters](/doc/encryption-config/), if you like!
### What is the main concept behind Qubes?
To build security on the “Security by Compartmentalization (or Isolation)” principle.
@ -151,6 +159,28 @@ Please see the [documentation guidelines](/doc/doc-guidelines).
Not currently, for the same reasons that [Debian is not certified](https://www.gnu.org/distros/common-distros.en.html).
### What does it mean to "distrust the infrastructure"?
A core tenet of the Qubes philosophy is "distrust the infrastructure," where
"the infrastructure" refers to things like hosting providers, CDNs, DNS
services, package repositories, email servers, PGP keyservers, etc. As a
project, we focus on securing endpoints instead of attempting to secure "the
middle" (i.e., the infrastructure), since one of our primary goals is to free
users from being forced to entrust their security to unknown third parties.
Instead, our aim is for users to be required to trust as few entities as
possible (ideally, only themselves and any known persons whom they voluntarily
decide to trust).
Users can never fully control all the infrastructure they rely upon, and they
can never fully trust all the entities who do control it. Therefore, we believe
the best solution is not to attempt to make the infrastructure trustworthy, but
instead to concentrate on solutions that obviate the need to do so. We believe
that many attempts to make the infrastructure appear trustworthy actually
provide only the illusion of security and are ultimately a disservice to real
users. Since we don't want to encourage or endorse this, we make our distrust of
the infrastructure explicit.
Installation & Hardware Compatibility
-------------------------------------
@ -172,6 +202,27 @@ Yes. Xen doesn't use VT-x (or AMD-v) for PV guest virtualization. (It uses ring0
Yes. You can even run a NetVM, but you will not benefit from DMA protection for driver domains. On a system without VT-d, everything should work in the same way, except there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple DMA attack to go from the NetVM to Dom0. **Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d. Therefore, a system running Qubes will still be significantly more secure than one running Windows, Mac, or Linux, even if it lacks VT-d.**
### What is a DMA attack?
DMA is mechanism for PCI devices to access system memory (read/write).
Without VT-d, any PCI device can access all the memory, regardless to
which VM it is assigned (or if it is left in dom0). Most PCI devices allow the
driver to request an arbitrary DMA operation (like "put received network packets
at this address in memory", or "get this memory area and send it to the
network"). So, without VT-d, it gives unlimited access to the whole
system. Now, it is only a matter of knowing where to read/write to take
over the system, instead of just crashing. But since you can read the
whole memory, it isn't that hard.
Now, how does this apply to Qubes OS? The above attack requires access to a PCI
device, which means that it can be performed only from NetVM / UsbVM, so
someone must first break into one of those VMs. But this isn't that hard,
because there is a lot of complex code handling network traffic. Recent
bugs includes DHCP client, DNS client, etc. Most attacks on NetVM /
UsbVM (but not all!) require being somewhat close to the target system -
for example connected to the same WiFi network, or in the case of a UsbVM,
having physical acccess to a USB port.
### Can I use AMD-v instead of VT-x?
See [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5).
@ -226,6 +277,18 @@ A device that does not support reset is not safe and generally should not be ass
Most likely the offending controller is a USB3.0 device. You can remove this controller from the usbVM, and see if this allows the VM to boot.
Alternatively you may be able to disable USB 3.0 in the BIOS.
Errors suggesting this issue:
- in `xl dmesg` output:
(XEN) [VT-D] It's disallowed to assign 0000:00:1a.0 with shared RMRR at dbe9a000 for Dom19.
(XEN) XEN_DOMCTL_assign_device: assign 0000:00:1a.0 to dom19 failed (-1)
- during `qvm-start sys-usb`:
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
Another solution would be to set the pci_strictreset option using qvm-prefs in dom0:
`qvm-prefs usbVM -s pci_strictreset false`
@ -263,3 +326,20 @@ If you only want Flash available in one qube:
- untar the downloaded file ```tar xf install_flash_player_11_linux.x86_64.tar.gz```
- create ~/.mozilla/plugins if it does not exist
- move libflashhplayer.so to ~/.mozilla/plugins, and restart iceweasel.
### How do I play video files?
If you're having trouble playing a video file in a qube, you're probably
missing the required codecs. The easiest way to resolve this is to install VLC
Media Player and use that to play your video files. You can do this in multiple
different TemplateVM distros (Fedora, Debian, etc.), but for simplicity, we'll
assume you're using Fedora:
1. (Recommended) Clone an existing Fedora TemplateVM.
2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM.](/doc/software-update-vm/#rpmfusion-for-a-fedora-templatevm)
3. Install VLC in that TemplateVM:
$ sudo dnf install vlc
4. Use VLC to play your video files.

0
developers/building/building-archlinux-template.md → building/building-archlinux-template.md
View File

0
developers/building/building-non-fedora-template.md → building/building-non-fedora-template.md
View File

2
developers/building/development-workflow.md → building/development-workflow.md
View File

@ -541,6 +541,6 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and
deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main
~~~
[port-forwarding]: /doc/qubes-firewall/#tocAnchor-1-1-5
[port-forwarding]: /doc/firewall/#port-forwarding-to-a-qube-from-the-outside-world
[linux-yum]: https://github.com/QubesOS/qubes-linux-yum
[linux-deb]: https://github.com/QubesOS/qubes-linux-deb

0
developers/building/pvusb.md → building/pvusb.md
View File

0
developers/building/qubes-builder-details.md → building/qubes-builder-details.md
View File

2
developers/building/qubes-builder.md → building/qubes-builder.md
View File

@ -126,7 +126,7 @@ If you want to somehow modify sources, you can also do it, here are some basic s
make iso
Code verification keys management
=================================
---------------------------------
[QubesBuilder](/doc/qubes-builder/) by default verifies signed tags on every downloaded code. Public keys used for that are stored in `keyrings/git`. By default Qubes developers' keys are imported automatically, but if you need some additional keys (for example your own), you can add them using:

0
developers/building/qubes-r3-building.md → building/qubes-r3-building.md
View File

98
common-tasks/backup-emergency-restore-v4.md Normal file
View File

@ -0,0 +1,98 @@
---
layout: doc
title: Emergency Backup Recovery - format version 4
permalink: /doc/backup-emergency-restore-v4/
redirect_from:
- /en/doc/backup-emergency-restore-v4/
- /doc/BackupEmergencyRestoreV4/
---
Emergency Backup Recovery without Qubes - format version 4
==========================================================
This page describes how to perform an emergency restore of a backup created on Qubes R4.0 or later (which uses backup format version 4).
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.
**Note:** In the following example, the backup file is both *encrypted* and *compressed*.
1. Backup content is encrypted and integrity protected using [scrypt
utility](https://www.tarsnap.com/scrypt.html). You need to obtain it to
restore your data. If your distribution have it packaged (like on Debian),
install the package standard way, otherwise you need to compile it yourself
(verify its signature first!).
Versions up to 1.2.0 (inclusive) do not support `-P` option for easier
scripting - which means you'll need to enter the passphrase for each file
separately, instead of using `echo ... | scrypt`.
2. Untar the main backup file.
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
backup-header.hmac
qubes.xml.000.enc
vm1/private.img.000.enc
vm1/private.img.001.enc
vm1/private.img.002.enc
vm1/icon.png.000.enc
vm1/firewall.xml.000.enc
vm1/whitelisted-appmenus.list.000.enc
dom0-home/dom0user.000.enc
3. Set backup passhprase environment variable. While this isn't strictly required, it will be handy later and will avoid saving the passphrase into shell history.
read backup_pass
4. Verify integrity of `backup-header`. For compatibility reasons `backup-header.hmac` is in fact is an encrypted *and integrity protected* version of `backup-header`.
[user@restore ~]$ echo "backup-header!$backup_pass" |\
scrypt -P dec backup-header.hmac backup-header.verified && \
diff -qs backup-header backup-header.verified
Files backup-header and backup-header.verified are identical
**Note:** If the above fail, it may be either mean that backup was tampered
with, or it is in different format (see point 3 above). In that case, look into
`backup-header`, at `version` field. If it contains anything else than
`version=4`, go to other version of instruction: [Emergency Backup Recovery -
format version 2](/doc/backup-emergency-restore-v2/), [Emergency Backup
Recovery - format version 3](/doc/backup-emergency-restore-v3/)
5. Read the `backup-header`. You'll need some of this information later. The file will look similar to this:
[user@restore ~]$ cat backup-header
version=4
encrypted=True
compressed=True
compression-filter=gzip
backup_id=20161020T123455-1234
6. Verify the integrity and decrypt the `private.img` file which houses your data.
[user@restore ~]$ backup_id=20161020T123455-1234 # see backup-header above
[user@restore ~]$ for f_enc in vm1/private.img.???.enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt -P dec $f_enc $f_dec || break; \
done
**Note:** If the above fail, most likely your backup is corrupted, or been tampered with.
7. Decompress and untar the decrypted `private.img` file.
[user@restore ~]$ cat vm1/private.img.??? | gzip -d | tar -xv
vm1/private.img
**Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program. This information is contained in the `backup-header` file (see step 3).
8. Mount the private.img file and access your data.
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
[user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
This data has been successfully recovered!
9. Success! If you wish to recover data from more than one VM in your backup, simply repeat steps 5--8 for each additional VM.
**Note:** You may wish to store a copy of these instructions with your Qubes backups in the event that you fail to recall the above procedure while this web page is inaccessible. All Qubes documentation, including this page, is available in plain text format in the following Git repository:
https://github.com/QubesOS/qubes-doc.git

14
common-tasks/backup-restore.md
View File

@ -32,8 +32,8 @@ Creating a Backup
3. Select the destination for the backup:
- If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device** (feature removed in R3, select appropriate **Target AppVM** and mount the stick with one click in file selection dialog).
- If you wish to send your backup to a (currently running) AppVM, select the AppVM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a (currently running) AppVM, select the AppVM 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 an AppVM, then select the mount point inside that AppVM as the backup destination.
You must also specify a directory on the device or in the AppVM, or a command to be executed in the AppVM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target AppVM, 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.
@ -87,8 +87,16 @@ For emergency restore of backup created on Qubes R2 or newer take a look [here](
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](/doc/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 AppVM. 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.
Notes
-----

14
common-tasks/copy-paste.md
View File

@ -36,19 +36,7 @@ And [this message](https://groups.google.com/group/qubes-devel/msg/48b4b532cee06
Copy/Paste between dom0 and other domains
-----------------------------------------
Copy/Paste between dom0 and other domains is intentionally prohibited by default. There should normally be no reason for any data exchange between dom0 and other VMs (except for the reporting of error logs). In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard:
1. Right-click on the desired VM in the Qubes VM Manager.
2. Click "Logs."
3. Click on the desired log.
4. Click "Copy to Qubes clipboard."
You may now paste the log contents to any VM as you normally would (i.e., Ctrl-Shift-V, then Ctrl-V).
For data other than logs, there are two options:
1. [Copy it as a file.](/doc/copy-to-dom0/)
2. Paste the data to `/var/run/qubes/qubes-clipboard.bin`, then write "dom0" to `/var/run/qubes/qubes-clipboard.bin.source`. Then use Ctrl-Shift-V to paste the data to the desired VM.
See ["Copying from (and to) dom0"](/doc/copy-from-dom0/).
Clipboard automatic policy enforcement
--------------------------------------

2
common-tasks/copying-files.md
View File

@ -43,4 +43,4 @@ However, one should keep in mind that performing a data transfer from *less trus
See also [this article](http://theinvisiblethings.blogspot.com/2011/03/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
You may also want to read how to [revoke "Yes to All" authorization](/doc/Qrexec/#revoking-yes-to-all-authorization)
You may also want to read how to [revoke "Yes to All" authorization](/doc/qrexec3/#revoking-yes-to-all-authorization)

8
common-tasks/full-screen-mode.md
View File

@ -32,6 +32,14 @@ Enabling full screen mode for select VMs
If you want to enable full screen mode for select VMs, you can do that by creating the following entry in the /etc/qubes/guid.conf file in Dom0:
**Note:** Regardless of the settings below, you can always put a window into
fullscreen mode in Xfce4 using the trusted window manager by right-clicking on
a window's title bar and selecting "Fullscreen". This functionality should still
be considered safe, since a VM window still can't voluntarily enter fullscreen
mode. The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title
bar menu again, then select "Leave Fullscreen".
**Note:** There should be only one `VM: {}` block in the file (or you will [get into problems](https://groups.google.com/d/msg/qubes-users/-Yf9yNvTsVI/xXsEm8y2lrYJ))
~~~

10
common-tasks/managing-appvm-shortcuts.md
View File

@ -28,10 +28,16 @@ The above image shows that Windows HVMs are also supported (provided that Qubes
Behind the scenes
-----------------
List of installed applications for each AppVM is stored in its template'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](http://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 case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](http://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. Example: `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'`
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'`
`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain. This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory.
For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
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.

4
common-tasks/software-update-dom0.md
View File

@ -131,6 +131,10 @@ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
Reboot required.
If you wish to upgrade to a kernel that is not available from the repos, then
there is no easy way to do so, but [it may still be possible if you're willing
to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoyV58_E/HYdReRIYBAAJ).
### Upgrading over Tor ###
Requires installed [Whonix](/doc/privacy/whonix/).

18
common-tasks/software-update-vm.md
View File

@ -11,20 +11,20 @@ redirect_from:
Installing and updating software in VMs
=======================================
How Template VM works in Qubes
How TemplateVMs work in Qubes
------------------------------
Most of the AppVMs (domains) are based on a *template VM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way.
Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way.
In addition to saving on the disk space, and reducing domain creation time, another advantage of such scheme is the possibility for centralized software update. It's just enough to do the update in the template VM, and then all the AppVMs based on this template get updates automatically after they are restarted.
The default template is called **fedora-14-x64** in Qubes R1 and **fedora-20-x64** in Qubes R2.
The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home` or `/usr/local` then it will disappear after the AppVM reboot (as the root filesystem for this AppVM will again be "taken" from the Template VM). **This means one normally install software in the Template VM, not in AppVMs.**
The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home` or `/usr/local` then it will disappear after the AppVM reboot (as the root filesystem for this AppVM will again be "taken" from the TemplateVM). **This means one normally install software in the TemplateVM, not in AppVMs.**
Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/FedoraTemplateUpgrade/#compacting-templates-rootimg) to recover space in dom0.
Unlike VM private filesystems, the template VM root filesystem does not support discard, so deleting files does not free the space in dom0. See [these instructions](/doc/template/fedora/upgrade-23-to-24/#compacting-the-upgraded-template) to recover space in dom0.
Installing (or updating) software in the template VM
Installing (or updating) software in the TemplateVM
----------------------------------------------------
In order to permanently install new software, you should:
@ -92,14 +92,14 @@ For example, to revert changes to the `fedora-23` TemplateVM:
For the technical details about how this command works and the steps it
performs, see [here](/doc/template-implementation/#rollback-template-changes).
Notes on trusting your Template VM(s)
Notes on trusting your TemplateVM(s)
-------------------------------------
As the template VM is used for creating filesystems for other AppVMs, where you actually do the work, it means that the template VM is as trusted as the most trusted AppVM based on this template. In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise.
As the TemplateVM is used for creating filesystems for other AppVMs, where you actually do the work, it means that the TemplateVM is as trusted as the most trusted AppVM based on this template. In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise.
There are several ways to deal with this problem:
- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/qubes-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 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.
- Use *standalone VMs* (see below) for installation of untrusted software packages.
@ -109,7 +109,7 @@ Some popular questions:
- So, why should we actually trust Fedora repos -- it also contains large amount of 3rd 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/qubes-firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
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.
- But why trusting Fedora?

102
common-tasks/usb.md
View File

@ -152,9 +152,7 @@ USB stack is put to work to parse the data presented by the USB device in order
to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
To avoid this risk, it is possible to prepare and utilize a USB qube. However,
Xen does not yet provide working PVUSB functionality, so only USB mass storage
devices can be passed to individual qubes.
To avoid this risk, it is possible to prepare and utilize a USB qube.
For this reason, you may wish to avoid using a USB qube if you do not have a USB
controller free of input devices and programmable devices, although Qubes R3.1
@ -180,6 +178,8 @@ steps as root in dom0:
qubesctl state.highstate
(Note: This automatically [hides all USB controllers from dom0][hide-usb].)
Alternatively, you can create a USB qube manually as follows:
1. Read the [Assigning Devices] page to learn how to list and identify your
@ -210,6 +210,53 @@ Alternatively, you can create a USB qube manually as follows:
If the USB qube will not start, see [here][faq-usbvm].
Removing a USB qube
-------------------
**Warning:** This procedure will result in your USB controller(s) being attached
directly to dom0.
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
How to hide all USB controllers from dom0
-----------------------------------------
Even if you create a USB qube, there will be a brief period of time during the
boot process during which dom0 will be exposed to your USB controllers (and any
attached devices). This is a potential security risk, since even brief exposure
to a malicious USB device could result in dom0 being compromised. There are two
approaches to this problem:
1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0.
**Warning:** If you use a USB [AEM] device, do not use the second option. Using
a USB AEM device requires dom0 to have access to the USB controller to which
your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM
will hang.
The procedure to hide all USB controllers from dom0 is as follows:
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
6. Reboot.
(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you
opt to create a USB qube during installation. This also occurs automatically if
you choose to [create a USB qube] using the `qubesctl` method, which is the
first pair of steps in the linked section.)
Supported USB device types
--------------------------
@ -246,12 +293,54 @@ If you are sure you wish to proceed, then you must edit the
Add a line like this one to the top of the file:
sys-usb dom0 ask
sys-usb dom0 ask,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard.
Attaching a single USB device to a qube (USB passthrough)
---------------------------------------------------------
Stating with Qubes 3.2, it is possible to attach a single USB device to any
Qube. While this is useful feature, it should be used with care, because there
are [many security implications][usb-challenges] from using USB devices and USB
passthrough will **expose your target qube** for most of them. If possible, use
method specific for particular device type (for example block devices described
above), instead of this generic one.
To use this feature, you need to install `qubes-usb-proxy` package in the
templates used for USB qube and qubes you want to connect USB devices to. Note
you cannot pass through devices from dom0 (in other words: USB VM is required).
Listing available USB devices:
[user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Attaching selected USB device:
[user@dom0 ~]$ qvm-usb -a conferences sys-usb:2-5
[user@dom0 ~]$ qvm-usb
conferences:2-1 058f:3822 058f_USB_2.0_Camera
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences)
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Now, you can use your USB device (camera in this case) in `conferences` qube.
When you finish, detach the device:
[user@dom0 ~]$ qvm-usb -d sys-usb:2-5
[user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
This feature is not yet available in Qubes Manager.
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[Assigning Devices]: /doc/assigning-devices/
@ -260,7 +349,10 @@ You can now use your USB keyboard.
[1072-comm1]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124270051
[1072-comm2]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124119309
[1082]: https://github.com/QubesOS/qubes-issues/issues/1082
[hide-usb]: #how-to-hide-all-usb-controllers-from-dom0
[faq-usbvm]: /doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
[AEM]: /doc/anti-evil-maid/
[1618]: https://github.com/QubesOS/qubes-issues/issues/1618
[create a USB qube]: #creating-and-using-a-usb-qube
[input-proxy]: https://github.com/qubesos/qubes-app-linux-input-proxy
[usb-challenges]: http://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html

2
configuration/assigning-devices.md
View File

@ -173,7 +173,7 @@ or
[usb]: /doc/usb/
[ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3
[ml2]: https://groups.google.com/forum/\#!topic/qubes-users/Fs94QAc3vQI
[ml2]: https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI
[PCI passthrough]: http://wiki.xen.org/wiki/Xen_PCI_Passthrough
[Software Attacks on Intel VT-d]: http://www.invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf

55
configuration/config-files.md
View File

@ -12,9 +12,13 @@ redirect_from:
Qubes specific VM config files
==============================
Those files are placed in /rw, which survives VM restart, so can be used to customize single VM (not all VMs based on the same template).
Those files are placed in /rw, which survives VM restart, so can be
used to customize single VM (not all VMs based on the same template).
The scripts here all run as root.
- `/rw/config/rc.local` - script run at VM startup. Good place to change some service settings, replace config files with its copy stored in /rw/config etc. Example usage:
- `/rw/config/rc.local` - script run at VM startup. Good place to
change some service settings, replace config files with its copy stored
in /rw/config etc. Example usage:
~~~
# Store bluetooth keys in /rw to keep them across VM restarts
@ -22,16 +26,29 @@ Those files are placed in /rw, which survives VM restart, so can be used to cust
ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
~~~
- `/rw/config/qubes-ip-change-hook` - script run in NetVM after external IP change (or connection to the network)
- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM after firewall update. Good place to write own custom firewall rules
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system going to sleep. The file is used only in VM with some PCI devices attached. Supposed to be used for problematic device drivers.
- `/rw/config/qubes-ip-change-hook` - script run in NetVM after
external IP change (or connection to the network)
- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM
after each firewall update. Good place to write own custom firewall
rules
- `/rw/config/suspend-module-blacklist` - list of modules (one per
line) to be unloaded before system going to sleep. The file is used
only in VM with some PCI devices attached. Supposed to be used for
problematic device drivers.
Note that scripts need to be executable (chmod +x) to be used.
Also take a look at [bind-dirs][/doc/bind-dirs] for instruction how to easily
modify arbitrary system file in AppVM and have those changes persistent.
GUI and audio configuration in dom0
===================================
GUI configuration file `/etc/qubes/guid.conf` in one of few not managed by qubes-prefs nor Qubes Manager tool. Sample config (included in default installation):
GUI configuration file `/etc/qubes/guid.conf` in one of few not managed
by qubes-prefs nor Qubes Manager tool. Sample config (included in
default installation):
~~~
# Sample configuration file for Qubes GUI daemon
@ -61,9 +78,25 @@ VM: {
Currently supported settings:
- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame). Regardless of this setting, you can also set window fullscreen using trusted window manager settings (right click on title bar).
- `allow_utf8_titles` - allow to use UTF-8 in window titles, otherwise non-ASCII characters are replaced by underscore.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste
- `windows_count_limit` - limit on concurrent windows count.
- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). Note that this will cause much higher CPU usage in dom0.
- `allow_fullscreen` - allow VM to request its windows to go
fullscreen (without any colorful frame).
**Note:** Regardless of this setting, you can always put a window into
fullscreen mode in Xfce4 using the trusted window manager by right-clicking on
a window's title bar and selecting "Fullscreen". This functionality should still
be considered safe, since a VM window still can't voluntarily enter fullscreen
mode. The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title
bar menu again, then select "Leave Fullscreen".
- `allow_utf8_titles` - allow to use UTF-8 in window titles,
otherwise non-ASCII characters are replaced by underscore.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences
used to trigger secure copy and paste
- `windows_count_limit` - limit on concurrent windows count.
- `audio_low_latency` - force low-latency audio mode (about 40ms
compared to 200-500ms by default). Note that this will cause much
higher CPU usage in dom0.

6
configuration/http-filtering-proxy.md
View File

@ -162,7 +162,7 @@ Setup
to restart all proxy processes.
7. To make sure that the proxy is started automatically when the AppVM
starts change `/rw/config/qubes_firewall_user_script` to include the
starts change `/rw/config/qubes-firewall-user-script` to include the
following line:
/rw/config/tinyproxy/proxyctl.py update
@ -174,8 +174,8 @@ Setup
Make sure that the script is owned by root and executable:
sudo chown root:root /rw/config/qubes_firewall_user_script
sudo chmod 755 /rw/config/qubes_firewall_user_script
sudo chown root:root /rw/config/qubes-firewall-user-script
sudo chmod 755 /rw/config/qubes-firewall-user-script
8. In Qubes VM manager adjust Firewall rules for each AppVM with a
proxy. In a typical case when only HTTP proxy should be used for

42
configuration/managing-vm-kernel.md
View File

@ -7,7 +7,7 @@ redirect_from:
---
VM kernel managed by dom0
-------------------------
=========================
By default VMs kernels are provided by dom0. This means that:
@ -47,7 +47,7 @@ updatevm : sys-firewall
~~~
Installing different kernel using Qubes kernel package
==================================
----------------------------------
VM kernels are packages by Qubes team in `kernel-qubes-vm` packages. Generally system will keep the 3 newest available versions. You can list them with the `rpm` command:
@ -135,7 +135,7 @@ In the above example, it tries to remove 3.18.10-2.pvops.qubes kernel (to keep o
The newly installed package is set as default VM kernel.
Installing different VM kernel based on dom0 kernel
===================================================
---------------------------------------------------
It is possible to package kernel installed in dom0 as VM kernel. This makes it
possible to use VM kernel, which is not packaged by Qubes team. This includes:
@ -203,7 +203,7 @@ mke2fs 1.42.12 (29-Aug-2014)
~~~
Using kernel installed in the VM
================================
--------------------------------
**This option is available only in Qubes R3.1 or newer**
@ -239,8 +239,10 @@ sudo yum install qubes-kernel-vm-support grub2-tools
Then install whatever kernel you want. If you are using distribution kernel
package (`kernel` package), initramfs and kernel module should be handled
automatically. If you are using manually build kernel, you need to handle this
on your own. Take a look at `dkms` and `dracut` documentation.
automatically, but you need to ensure you have `kernel-devel` package for the
same kernel version installed. If you are using manually build kernel, you need
to handle this on your own. Take a look at `dkms` and `dracut` documentation.
Especially `dkms autoinstall` command may be useful.
When kernel is installed, you need to create GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`, for example lower
@ -278,8 +280,28 @@ Ignore warnings about `version '...' has bad syntax`.
Then install whatever kernel you want. If you are using distribution kernel
package (`linux-image-amd64` package), initramfs and kernel module should be
handled automatically. If you are using manually build kernel, you need to
handle this on your own. Take a look at `dkms` and `initramfs-tools` documentation.
handled automatically. If not, or you are building kernel manually, do this on
using `dkms` and `initramfs-tools`:
sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
sudo update-initramfs -u
The output should look like this:
$ sudo dkms autoinstall -k 3.16.0-4-amd64
u2mfn:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
When kernel is installed, you need to create GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`, for example lower
@ -298,7 +320,9 @@ grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your
~~~
Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will
start kernel configured within VM.
start kernel configured within VM.
When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd'
### Troubleshooting

12
configuration/multiboot.md
View File

@ -40,18 +40,6 @@ If you are really paranoid clone your disc.
Make sure you have install discs to hand for the existing operating system.
Qubes 3.0 does not support UEFI boot. If you are already using it the first step
is to change boot mode.
Most PCs using UEFI firmware and bootloader can be configured to disable
UEFI entirely and instead revert to legacy MBR boot mode.
Two separate steps are often required to achieve this:
* Enabling legacy boot mode
* Disabling Secure Boot
Qubes by default does not include other systems in the generated grub menu,
because handling of other systems has been disabled. This means
that you will have to manually add grub entries for any other OS.

6
configuration/postfix.md
View File

@ -16,9 +16,11 @@ Postfix is full featured MTA (Message Transfer Agent). Here we will configure it
Installation
------------
`yum install postfix procmail make`
`yum install postfix procmail make cyrus-sasl cyrus-sasl-plain`
Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables. You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `yum remove ssmtp` or something.
Cyrus-sasl is installed to authenticate to remote servers. Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables.
You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `yum remove ssmtp` or something
Configuration
-------------

9
configuration/resize-disk-image.md
View File

@ -100,7 +100,9 @@ truncate -s 30GB root.img
ls -lh root.img (<--verify new size of disk image)
~~~
The partition table and file-system must be adjusted after this change:
The partition table and file-system must be adjusted after this change.
Use tools appropriate to the OS in your HVM. Brief instructions for Windows 7,
FreeBSD, and Linux are provided below.
#### Windows 7
@ -119,3 +121,8 @@ sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
~~~
#### Linux
You will see that there is unallocated free space at the end of your primary disk.
You can use standard linux tools like fdisk and mkfs to make this space available.

2
configuration/salt.md
View File

@ -164,7 +164,7 @@ need to create state file (`/srv/salt/mc-everywhere.sls`):
Then appropriate top file (`/srv/salt/mc-everywhere.top`):
base:
- qubes:type:template:
qubes:type:template:
- match: pillar
- mc-everywhere

3
configuration/secondary-storage.md
View File

@ -32,7 +32,8 @@ Known Issues
The same problem may occur if the above procedure is attempted on a
[TemplateVM][]. [[1]]
* After implementing the above procedure, starting `my-new-appvm` will cause
* This issue applies only to R3.1, not R3.2 or later:
After implementing the above procedure, starting `my-new-appvm` will cause
dom0 notifications to occur stating that loop devices have been attached to
dom0. This is normal. (No untrusted devices are actually being mounted to
dom0.) Do not attempt to detach these disks. (They will automatically be

189
configuration/vpn.md
View File

@ -10,11 +10,11 @@ redirect_from:
---
How To make a VPN Gateway in Qubes
----------------------------------
==================================
Setting up a VPN connection is really not Qubes specific and is documented in your operating system documentation. The relevant documentation for the Qubes default Guest OS (Fedora) is [Establishing a VPN Connection](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html)
Although setting up a VPN connection is not by itself Qubes specific, there are a number of Qubes-related details that can make using the connection more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts.
The Qubes specific part is to choose the right VM for the VPN client:
Please refer to guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html)
### NetVM
@ -29,22 +29,18 @@ While the NetworkManager service is not started here (for a good reason), you ca
### ProxyVM
**WARNING:** *You need to use Qubes 3.1-rc2 (or later)! In the previous releases the NetworkManager service was not working in ProxyVMs as expected.* ([#1052](https://github.com/QubesOS/qubes-issues/issues/1052))
One of the best thing in Qubes is that you can use a special type of VM called a ProxyVM (or FirewallVM). The special thing is that your AppVMs see this as a NetVM, and your NetVMs see it as an AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default FirewallVM functions.
One of the best things in Qubes is that you can use a special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions.
Using a ProxyVM to set up a VPN client gives you the ability to:
- Separate your VPN credentials from Your NetVM
- Separate your VPN credentials from Your NetVM.
- Separate your VPN credentials from Your AppVM data.
- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM.
#### Set up a ProxyVM as a VPN gateway
Set up a ProxyVM as a VPN gateway using NetworkManager
------------------------------------------------------
#### Using NetworkManager
1. Create a new VM and check the ProxyVM radio button.
1. Create a new VM: Name it, click the ProxyVM radio button then choose a color and template.
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
@ -60,68 +56,41 @@ Using a ProxyVM to set up a VPN client gives you the ability to:
5. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
#### Using iptables and openvpn
1. Create a new VM and check the ProxyVM radio button.
Set up a ProxyVM as a VPN gateway using iptables and CLI scripts
----------------------------------------------------------------
This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted. It has been tested with Fedora 23 and Debian 8 templates.
1. Create a new VM: Name it, click the ProxyVM radio button then choose a color and template.
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
If your choice of template VM doesn't already have the `openvpn` package, you'll need to install it in the template first. You may also need to `systemctl disable` any openvpn service that comes with the package if you follow the instructions for autostart below.
2. Set up OpenVPN.
Copy your openvpn config files to `/rw/config/openvpn/` folder. The example main config file is `openvpn-client.ovpn`.
It should have one line that reads `dev tun`.
If it does not contain a line `redirect-gateway def1` you may wish to add it. This will route all traffic through your vpn's network device after a connection is created. However, many VPN services will push this instruction to your client automatically -- having a line that says `client` or `pull` in your openvpn config instructs your client to use parameters specified by the VPN server.
Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features. If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM... Create a new one according to this step.
NOTE: If the connection breaks down all traffic will by default be routed through the upstream network device eth0 (we will stop this with iptables in step 3).
If your choice of template VM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding. Disable any auto-starting service that comes with the software package: for example `sudo systemctl disable openvpn.service`.
You may also wish to install `nano` or other simple text editor for entering the scripts below.
Also add the following to accomodate a DNS script:
2. Set up and initial test of the VPN client.
~~~
script-security 2
up 'qubes-vpn-handler.sh up'
down 'qubes-vpn-handler.sh down'
~~~
Make sure the VPN VM and its template VM are not running.
Run a terminal (CLI) in the VPN VM -- this will start the VM. Then make a new 'vpn' folder with `sudo mkdir /rw/config/vpn` and copy your VPN config files here (the example config filename used here is `openvpn-client.ovpn`). Files accompanying the main config such as *.crt and *.pem should also go here, and should not be referenced in the main config by absolute paths such as '/etc/...'.
Notes about VPN config options: The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested. Also, the config should route all traffic through your VPN's interface after a connection is created; For openvpn the directive for this is `redirect-gateway def1`. Lastly, the VPN client may not be able to prompt you for credentials when connecting to the server: Creating a file in the 'vpn' folder with your credentials and using a directive such as openvpn's `auth-user-pass <filename>` is recommended.
__Test your client configuration:__ Run the client from a CLI prompt in the 'vpn' folder, preferably as root. For example:
```
sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn
```
Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping` and `traceroute`. DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete). Diagnose any connection problems using resources such as client documentation and help from your VPN service provider.
Proceed to the next step when you're sure the basic VPN connection is working.
3. Set up iptables.
Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` and add:
~~~
#!/bin/bash
# First, block all outgoing traffic
iptables -P OUTPUT DROP
iptables -F OUTPUT
# Add the `qvpn` group to system, if it doesn't already exist
if ! grep -q "^qvpn:" /etc/group ; then
groupadd -rf qvpn
sync
fi
sleep 2s
# Allow traffic from the `qvpn` group to the uplink interface (eth0);
# Our openvpn will run as group `qvpn`.
iptables -A OUTPUT -p all -o eth0 -m owner --gid-owner qvpn \
-m state --state NEW,ESTABLISHED -j ACCEPT
# Allow internal system connections:
iptables -I OUTPUT -o lo -j ACCEPT
# Block forwarding of connections through upstream network device
# (in case the vpn tunnel breaks):
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
~~~
Now save `/rw/config/qubes-firewall-user-script` and make it executable:
`sudo chmod +x /rw/config/qubes-firewall-user-script`
4. Create the DNS-handling script.
Use `sudo nano /rw/config/openvpn/qubes-vpn-handler.sh` to edit and add:
3. Create the DNS-handling script.
Use `sudo nano /rw/config/vpn/qubes-vpn-handler.sh` to edit and add:
~~~
#!/bin/bash
@ -131,10 +100,10 @@ Using a ProxyVM to set up a VPN client gives you the ability to:
case "$1" in
up)
# To override DHCP DNS, assign static DNS addresses with 'setenv vpn_dns' in openvpn config;
# Format is 'X.X.X.X Y.Y.Y.Y [...]' with quotes.
# To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script;
# Format is 'X.X.X.X Y.Y.Y.Y [...]'
if [[ -z "$vpn_dns" ]] ; then
# Parses DHCP options from openvpn to set DNS address translation:
# Parses DHCP foreign_option_* vars to automatically set DNS address translation:
for optionname in ${!foreign_option_*} ; do
option="${!optionname}"
unset fops; fops=($option)
@ -162,27 +131,93 @@ Using a ProxyVM to set up a VPN client gives you the ability to:
~~~
Now save the script and make it executable:
`sudo chmod +x /rw/config/openvpn/qubes-vpn-handler.sh`
`sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh`
4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config with `sudo nano /rw/config/vpn/openvpn-client.ovpn` and add these lines:
~~~
script-security 2
up 'qubes-vpn-handler.sh up'
down 'qubes-vpn-handler.sh down'
~~~
**Restart the client and test the connection again** ...this time from an AppVM!
5. Set up iptables anti-leak rules.
Edit the firewall script with `sudo nano /rw/config/qubes-firewall-user-script` then clear out the existing lines and add:
~~~
#!/bin/bash
# Block forwarding of connections through upstream network device
# (in case the vpn tunnel breaks):
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
# Block all outgoing traffic
iptables -P OUTPUT DROP
iptables -F OUTPUT
iptables -I OUTPUT -o lo -j ACCEPT
# Add the `qvpn` group to system, if it doesn't already exist
if ! grep -q "^qvpn:" /etc/group ; then
groupadd -rf qvpn
sync
fi
sleep 2s
# Allow traffic from the `qvpn` group to the uplink interface (eth0);
# Our VPN client will run with group `qvpn`.
iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT
~~~
Now save the script and make it executable:
`sudo chmod +x /rw/config/qubes-firewall-user-script`
5. Set up the VPN's autostart.
Use `sudo nano /rw/config/rc.local` to edit and add:
Use `sudo nano /rw/config/rc.local` to clear out the existing lines and add:
~~~
#!/bin/bash
VPN_CLIENT='openvpn'
VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon'
su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user
groupadd -rf qvpn ; sleep 2s
sg qvpn -c 'openvpn --cd /rw/config/openvpn/ --config openvpn-client.ovpn \
--daemon --writepid /var/run/openvpn/openvpn-client.pid'
sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS"
~~~
Change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software.
Now save the script and make it executable:
`sudo chmod +x /rw/config/rc.local`
6. Restart the new VM!
6. Restart the new VM! The link should then be established automatically with a popup notification to that effect.
7. Configure your AppVMs to use the new VM as a NetVM.
Usage
-----
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
Configure your AppVMs to use the VPN VM as a NetVM...
8. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
If you want to be able to use the [Qubes firewall](/doc/firewall), create a new FirewallVM (as a ProxyVM) and set it to use the VPN VM as its NetVM.
Then, configure AppVMs to use your new FirewallVM as their NetVM.
If you want to update your TemplateVMs through the VPN, enable the `qubes-updates-proxy` service in your new FirewallVM.
You can do this in the Services tab in Qubes VM Manager or on the command-line:
$ qvm-service -e <name> qubes-updates-proxy
Then, configure your templates to use your new FirewallVM as their NetVM.
Troubleshooting
---------------
* Always test your basic VPN connection before adding scripts.
* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain.
* For scripting: Ping external IP addresses from inside the VPN VM using `sudo sg qvpn -c 'ping ...'`, then from an appVM using just `ping ...`. Once the firewall rules are in place, you will have to use `sudo sg` to run any IP network commands in the VPN VM.
* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding.

70
customization/bind-dirs.md Normal file
View File

@ -0,0 +1,70 @@
---
layout: doc
title: How to make any file in a TemplateBasedVM persistent using bind-dirs
permalink: /doc/bind-dirs/
redirect_from:
- /en/doc/bind-dirs/
---
# How to make any file in a TemplateBasedVM persistent using bind-dirs #
## What is bind-dirs.sh? ##
With [bind-dirs.sh](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
you can make arbitrary files or folders persistent in TemplateBasedVMs.
## What is it useful for? ##
For example, it is useful for Whonix, sys-whonix, where [Tor's data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5). So sys-whonix does not require to be a StandaloneVM. And therefore can benefit from the Tor anonymity feature 'persistent Tor entry guards' without the overhead of a StandaloneVM.
## Minimum Qubes Version ##
bind-dirs.sh works with Qubes R3.2 and above.
## How to use bind-dirs.sh? ##
1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists.
sudo mkdir -p /rw/config/qubes-bind-dirs.d
2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM.
3. Append a folder or file to the `binds` variable. In the following example we are using folder `/var/lib/tor`. You can replace that folder with a folder or file of your choice.
binds+=( '/var/lib/tor' )
4. Save.
5. Reboot the VM.
6. Done.
## Other Configuration Folders ##
* `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages)
* `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration)
* `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration)
## Limitations ##
* Files that exist in the TemplateVM root image cannot be made deleted in the TemplateBasedVMs root image using bind-dirs.sh.
* Does not work if the file / folder in question does not already exist in the root image. I.e. a file that does not exist in the root image cannot be bind mounted in the TemplateBasedVM.
* Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without previous `sudo /usr/lib/qubes/bind-dirs.sh umount` does not work.
* Running 'sudo /usr/lib/qubes/bind-dirs.sh umount' after boot (before shutdown) is probably not sane and nothing can be done about that.
## How to remove binds from bind-dirs.sh? ##
`binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are `source`d as bash snippets in lexical order. Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file. For example, if you wanted to make `/var/lib/tor` non-persistant in `sys-whonix` without manually editing [`/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf`](https://github.com/Whonix/qubes-whonix/blob/master/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf), you could use the following.
`/rw/config/qubes-bind-dirs.d/50_user.conf`
~~~
binds=( "${binds[@]/'/var/lib/tor'}" )
~~~
(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is recommended against, since such changes get lost when that file is changed in the package on upgrades.)
## Discussion ##
[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)

191
customization/dark-theme.md Normal file
View File

@ -0,0 +1,191 @@
---
layout: doc
title: Dark Theme in Dom0 and DomU
permalink: /doc/dark-theme/
---
Dark Theme in Dom0
==================
Dark KDE in Dom0
----------------
The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste.
The image below shows the default light theme after installation.
![begin light theme](/attachment/wiki/Dark-Theme/kde-fresh-installed-standard.png)
This is the result after applying the steps described here.
![end result dark theme](/attachment/wiki/Dark-Theme/kde-end-result.png)
1. Change `Workspace Appearance`
1. Open the `Workspace Appearance` window
Qubes Menu -> System Tools -> System Settings -> Workspace Appearance
![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png)
2. Go to `Desktop Theme`
![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png)
3. Select `Oxygen` and `Apply` the change
2. (Optional) Remove blue glowing task items
![blue glowing task bar items](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-border.png)
1. Adjust Oxygen `Details`
Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab)
2. Select `Oxygen`
3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items`
![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png)
4. Apply changes
![task bar items blue glowing removed](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-removed.png)
3. Change `Application Appearance`
1. Open the `Application Appearance` window
Qubes Menu -> System Tools -> System Settings -> Application Appearance
2. Go to `Colors`
![colors tab](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors.png)
3. Select `Obsidian Coast`
![set to Obsidian Coast](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors-set.png)
4. Apply Changes
Qubes VM Manager should now look like the image below.
![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png)
**Note:** Chaning the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is, that it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefor hard to read.
Dark XCFE in Dom0
-----------------
The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste.
The image below shows the default light theme after installation.
![begin light theme](/attachment/wiki/Dark-Theme/xfce-fresh-installed.png)
This is the result after applying the steps described here.
![end result dark theme](/attachment/wiki/Dark-Theme/xfce-end-result.png)
1. Change Appearance
1. Open the `Appearance` dialog
Qubes Menu -> System Tools -> Appearance
![appearance dialog](/attachment/wiki/Dark-Theme/xfce-appearance-dialog.png)
2. Change Style to `Albatross`
**Note:** The black appearance theme `Xfce-dusk` makes the VM names in the `Qubes OS Manager` unreadable.
2. *(Optional)* Change Window Manager Style
1. Open the `Window Manager` dialog
Qubes Menu -> System Tools -> Appearance
![window manager dialog](/attachment/wiki/Dark-Theme/xfce-window-manager-theme.png)
2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work.
Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome)
==========================================================
Almost all Qubes VM's are based on the Gnome desktop. Therefor the description below is focused on the Gnome Desktop Environment.
Using "Gnome-Tweak-Tool"
------------------------
The advantage of creating a dark themed Template VM is, that each AppVM which is derived from the Template VM will be dark themed by default.
**Note:** Gnome-Tweak-Tool crashes under Archlinux. A workaround is to assign the AppVM to another TemplateVM (Debian, Fedora) which has Gnome-Tweak-Tool installed. Start the AppVM and configure the settings. Shutdown the machine and switch the template VM back to Archlinux.
1. Start VM
**Note:** In case of App VM start the Template on which the AppVM is based on.
2. Install `Gnome-Tweak-Tool`
- Fedora
sudo dnf install gnome-tweak-tool
- Debian
sudo apt-get install gnome-tweak-tool
3. *(Only AppVM)* Stop template and start AppVM
4. Add `Gnome-Tweak-Tool` to the Application Menu
1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts`
2. Select `Tweak Tool` and press the `>` button to add it
![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png)
5. Enable `Global Dark Theme`
1. *Debian only*
cd ~/.config/
mkdir gtk-3.0
cd gtk-3.0/
touch settings.ini
2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on`
![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png)
6. *(Optional)* Modify Firefox
**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. There are two different ways to avoid this. Either by using a add-on or by overwriting the defaults.
- use the theme [GTK+ Dark Theme Global Fixes](https://userstyles.org/styles/111694/gtk-dark-theme-global-fixes) and the [Stylish](https://addons.mozilla.org/en-US/firefox/addon/stylish/) addon
- or add the following line to `/rw/config/rc.local`
sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop
7. Restart VM or all application
Manually
--------
Manually works for Debian, Fedora and Archlinux.
1. Start VM
**Note:** In case of App VM start the Template on which the AppVM is based on.
2. Enable `Global Dark Theme`
cd ~/.config/
mkdir gtk-3.0
cd gtk-3.0/
touch settings.ini
add the following lines to `settings.ini`
[Settings]
gtk-application-prefer-dark-theme=1
3. follow step 6 and 7 in: Using `Gnome-Tweak-Tool`

7
customization/dispvm-customization.md
View File

@ -9,8 +9,11 @@ redirect_from:
- /wiki/UserDoc/DispVMCustomization/
---
DispVM Customization
====================
Changing the template used as a basis for Disposable VM
========================================================
-------------------------------------------------------
You may want to use a non-default template as a basis for Disposable VM. One example is to use a less-trusted template with some less trusted, 3rd party, often unsigned, applications installed, such as e.g. 3rd part printer drivers.
@ -33,7 +36,7 @@ One can easily verify if the new Disposable VM template is indeed based on a cus
Customization of Disposable VM
==============================
------------------------------
It is possible to change the settings of each new Disposable VM (DispVM). This can be done by customizing the DispVM template:

10
customization/fedora-minimal-template-customization.md
View File

@ -139,7 +139,7 @@ Managing GUI theme / appearance is often complex because when you do not want to
For this reason, we need to customize themes for each GUI framework that our application depends on.
This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), QT.
This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), Qt.
The apparance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM.
@ -189,7 +189,7 @@ The following programs can be used to see if theme has been correctly applied:
* GTK2 program: scite, thunderbird, firefox
* GTK3 program: lxterminal
* QT program: keepassx
* Qt program: keepassx
*Note*: testing in a TemplateVM will not work as expected because gnome-settings-daemon is not started in TemplateVM.
so test your themes in an AppVM and then update the TemplateVM accordingly.
@ -251,9 +251,9 @@ Edit/Create the following file: /etc/dconf/db/qubes.d/locks/theme.lock:
Finally, regenerate the dconf database
> dconf update
### Uniform look for QT & GTK
### Uniform look for Qt & GTK
Getting an uniform look for QT & GTK is not achieved yet. A good source is on the following link [UNIFORMTHEME]
Getting an uniform look for Qt & GTK is not achieved yet. A good source is on the following link [UNIFORMTHEME]
Two case:
@ -265,7 +265,7 @@ Two case:
You can verify if it is enabled by searching for "style=GTK+" in /etc/xdg/Trolltech.conf.
If style is changed to another name, it will be used instead of your GTK theme.
*Note*: check that ~/.config/Trolltech.conf in your AppVMs is not defining another "style=" because it will take precedence over your global QT theme.
*Note*: check that ~/.config/Trolltech.conf in your AppVMs is not defining another "style=" because it will take precedence over your global Qt theme.
[3GMODEM]: https://www.codeenigma.com/community/blog/installing-3g-usb-modems-linux

31
customization/i3.md
View File

@ -14,12 +14,12 @@ redirect_from:
i3 is part of the testing repository (as of Qubes R3.1) and can be installed from there
using the dom0 update mechanism.
$ qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3
Qubes-specific configuation is available in a separate package and can be installed
optionally. Otherwise you can write your own configuration (see below).
$ qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3-settings-qubes
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing i3-settings-qubes
That's it. After logging out, you can select i3 in the login manager.
@ -82,33 +82,6 @@ After that you can just install the generated rpm like any other local package
Log out, select i3, then log in again.
### Configuration
**Warning**: Be careful when writing configuration/scripts for the dom0. A script which communicates with the qubes VMs could potentially open a security hole.
Things needed/recommended to be done:
1. Create [a script][xdg_autostart_script] to start all entries in the xdg
autostart directory. This is necessary to bring transient vm's up and
restore state.
2. Change dmenu to i3-dmenu-desktop in the i3 configuration file. This
respects xdg desktop files and gives you a good way of starting programs in
specific domains.
3. Install i3status or use a [different kind of script][i3bar_script] to drive
i3bar.
4. You could install and bind tools to change backlight and volume levels in
i3's config. You could also run kmix and xfce4-power-manager, which are
part of a normal Qubes installation, and bind the keys for you.
5. Qubes does automatic screen locking and so should you. Install `xautolock`
and `i3lock` in dom0 and then add
exec --no-startup-id "xautolock -detectsleep -time 3 -locker 'i3lock -d -c 000000' -notify 30 -notifier \"notify-send -t 2000 'Locking screen in 30 seconds'\""
to your i3 config to enable it.
6. By default `$mod+Return` in i3 will open a new terminal in dom0. If you
prefer to start a new terminal in the domain of the currently active
window, use [a script like this][terminal_start_script].
[xdg_autostart_script]:https://gist.github.com/SietsevanderMolen/7b4cc32ce7b4884513b0a639540e454f
[i3bar_script]: https://gist.github.com/SietsevanderMolen/e7f594f209dfaa3596907e427b657e30
[terminal_start_script]: https://gist.github.com/SietsevanderMolen/7c6f2b5773dbc0c08e1509e49abd1e96

32
customization/kde.md
View File

@ -8,6 +8,38 @@ redirect_from: /en/doc/kde/
Using KDE in dom0
=================
Installation
------------
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
R3.2, however, [XFCE is the new default desktop environment](https://www.qubes-os.org/doc/releases/3.2/release-notes/). Nonetheless, it is
still possible to install KDE by issuing this command in dom0:
$ sudo qubes-dom0-update @kde-desktop-qubes
You can also change your default login manager (lightdm) to the new KDE default: sddm
* first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs:
~~~
[XDisplay]
ServerArguments=-nolisten tcp -background none
~~~
* disable the lightdm service:
~~~
$ sudo systemctl disable lightdm
~~~
* enable the sddm service:
~~~
$ sudo systemctl enable sddm
~~~
* reboot
Window Management
-----------------

22
customization/windows-template-customization.md
View File

@ -26,7 +26,6 @@ Only keep:
*Note*: Windows search is recommended because it is a nightmare to find something in menus if it is not enabled (it removes the search bar from the start menu, from the explorer, and from the control panel).
*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. on a new install it is generally old versions anyway and it will be quicker to install directly the new versions later.
Services
Windows services
---------------------------
@ -48,7 +47,6 @@ Disable the following services that are not required or have no sense in a VM co
* Volume Shadow Copy (see next note in the performance section)
* Windows defender
* Windows Firewall
* Power
*Notes*: IP Helper is required as it is used by Qubes Agent to configure the IP address.
@ -108,20 +106,24 @@ If you remove these tasks they may be recreated automatically by various windows
* SystemRestore: All
* WindowsBackup: All
Disable hibernation
------------------------------
Power options
-------------
and clean hyberfil.sys
First, enable the "Power" Windows service. Then, set all of the following:
1. Ensure that you disabled the Power service (you may need to reboot so that the Power service is effectively stopped).
* Put the computer to sleep: `Never`
* Turn the display off: `Never`
* Turn off hard disk after: Setting (Minutes): `0`
2. Run a cmd.exe as an administrator:
> powercfg -h off
Turn off hibernation. Open a command prompt (`cmd.exe`) as an administrator,
then execute:
C:\hyberfil.sys should now be deleted
powercfg -h off
The hibernation file (`C:\hyberfil.sys`) should now be deleted.
Manual tasks that can/should be started in the template
===================================
-------------------------------------------------------
* Disk defragmentation

10
customization/xfce.md
View File

@ -14,17 +14,9 @@ XFCE installation in dom0
**Disclaimer: XFCE isn't fully integrated with Qubes environment, it still requires notable amount of manual configuration after install**
Requirements (as of 10/24/2012):
- qubes-core-dom0-2.0.37 (not released yet, possible to build from "master" branch of marmarek's repo)
Installation:
qubes-dom0-update --enablerepo=qubes-dom0-unstable @XFCE
Then you need to create /etc/sysconfig/desktop to stay with KDM, as GDM still starts invalid Xorg startup script:
DISPLAYMANAGER=KDE
sudo qubes-dom0-update @xfce-desktop-qubes
Reboot the system. At system startup, select "Xfce session" in login screen (menu on the right bottom corner of the screen).

0
developers/debugging/automated-tests.md → debugging/automated-tests.md
View File

0
developers/debugging/profiling.md → debugging/profiling.md
View File

78
debugging/safe-remote-ttys.md Normal file
View File

@ -0,0 +1,78 @@
---
layout: doc
title: Safe Remote Dom0 Terminals
permalink: /doc/safe-remote-ttys/
redirect_from:
- /en/doc/safe-remote-ttys/
- /doc/safe-remote-ttys/
---
Safe Remote Dom0 Terminals
==========================
If you do not have working graphics in Dom0, then using a terminal can be quite annoying!
This was the case for the author while trying to debug PCI-passthrough of a machine's primary (only) GPU.
Your first thought might be to just allow network access to Dom0, enable ssh, and connect in remotely.
But, this gravely violates the Qubes security model.
Instead, a better solution is to split the input and output paths of using a terminal.
Use your normal keyboard for input, but have the output go to a remote machine in a unidirectional manner.
To do this, we make use of script(1), qvm-run, and optionally your network transport of choice.
To a different VM
-----------------
As an example of forwarding terminal output to another VM on the same machine:
~~~
$ mkfifo /tmp/foo
$ qvm-run -p some-vm 'xterm -e "cat 0<&5" 5<&0' </tmp/foo >/dev/null 2>&1 &
$ script -f /tmp/foo
~~~
To a different machine
----------------------
In this case over SSH (from a network-connected VM):
~~~
$ mkfifo /tmp/foo
$ qvm-run -p some-vm \
'ssh user@host sh -c "DISPLAY=:0 xterm -e \"cat 0<&5\" 5<&0"' \
</tmp/foo >/dev/null 2>&1 &
$ script -f /tmp/foo
~~~
Note that no data received over SSH is ever treated as terminal input in Dom0.
The input path remains only from your trusted local keyboard.
Multiple terminals
------------------
For multiple terminals, you may find it easier to just use tmux than to try to blindly switch to the correct window.
Terminal size
-------------
It is up to you to ensure the sizes of the local and remote terminal are the same, otherwise things may display incorrectly (especially in interactive programs).
Depending on your shell, the size of your local (blind) terminal is likely stored in the `$LINES` and `$COLUMNS` variables.
~~~
$ echo $COLUMNS $LINES
80 24
~~~
A note on serial consoles
-------------------------
If your machine has a serial console, you may with to use that, but note that a similar split-I/O model should be used to ensure Dom0 integrity.
If you use the serial console as normal (via e.g. getty on ttyX, and logging in as normal), then the machine at the end of the serial cable could compromise your machine!
Ideally, you would take input from your trusted keyboard, and only send the output over the serial cable via e.g. disabling getty and using:
~~~
script -f /dev/ttyS0
~~~
You don't even need to connect the TX pin.

0
developers/debugging/test-bench.md → debugging/test-bench.md
View File

207
debugging/vm-interface.md Normal file
View File

@ -0,0 +1,207 @@
---
layout: doc
title: VM Configuration Interface
permalink: /doc/vm-interface/
redirect_from:
- /en/doc/vm-interface/
- /doc/VMInterface/
- /doc/SystemDoc/VMInterface/
- /wiki/SystemDoc/VMInterface/
---
VM Configuration Interface
==========================
Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
- QubesDB
- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
- Qubes RPC (called at VM startup, or when configuration changed)
- GUI protocol
QubesDB
--------------------
### Keys exposed by dom0 to VM ###
- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
- `/qubes-vm-persistence` - what data do persist between VM restarts:
- `full` - all disks
- `rw-only` - only `/rw` disk
- `none` - none
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `/qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
- `/qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService)
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-ip - IP address for this VM (only when VM has netvm set)
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) (in Qubes 3.2 and later, previously `/qubes-gateway` was used for this purpose)
- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server (in Qubes 3.2 and later, previously `/qubes-netvm-gateway` was used for this purpose)
- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
#### Firewall rules in 3.x ####
QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
separate key for each target VM. Entries:
- `/qubes-iptables` - control entry - dom0 writing `reload` here signal `qubes-firewall` service to reload rules
- `/qubes-iptables-header` - rules not related to any particular VM, should be applied before domains rules
- `/qubes-iptables-domainrules/NNN` - rules for domain `NNN` (arbitrary number)
in `iptables-save` format. Rules are self-contained - fill `FORWARD` iptables
chain and contains all required matches (source IP address etc), as well as
final default action (`DROP`/`ACCEPT`)
VM after applying rules may signal some error, writing a message to
`/qubes-iptables-error` key. This does not exclude any other way of
communicating problem - like a popup.
#### Firewall rules in 4.x ####
QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as
a separate entry, grouped on target VM:
- `/qubes-firewall/SOURCE_IP` - base tree under which rules are placed. All
rules there should be applied to filter traffic coming from `SOURCE_IP`. This
can be either IPv4 or IPv6 address.
Dom0 will do an empty write to this top level entry after finishing rules
update, so VM can setup a watch here to trigger rules reload.
- `/qubes-firewall/SOURCE_IP/policy` - default action if no rule matches:
`drop` or `accept`.
- `/qubes-firewall/SOURCE_IP/NNNN` - rule number `NNNN` - decimal number,
padded with zeros. Se below for rule format. All the rules should be
applied in order of rules implied by those numbers. Note that QubesDB
itself does not impose any ordering (you need to sort the rules after
retrieving them). The first rule has number `0000`.
Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
by space. Order of those pairs in a single rule is undefined. QubesDB enforces
a limit on a single entry length - 3072 bytes.
Possible options for a single rule:
- `action`, values: `accept`, `drop`; this is present it every rule
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dstname`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but
not any DNS server), on both TCP and UDP
- `dstports`, value: destination ports range separated with `-`, valid only
together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80`
- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
echo request, valid only together with `proto=icmp`
Rule matches only when all predicates matches. Only one of `dst4`, `dst6`,
`dstname`, `specialtarget` can be used in a single rule.
If tool applying firewall encounter any parse error (unknown option, invalid
value etc), it should drop all the traffic coming from that `SOURCE_IP`,
regardless of properly parsed rules.
Example valid rules:
- `action=accept dst4=8.8.8.8 proto=udp dstports=53-53`
- `action=drop dst6=2a00:1450:4000::/37 proto=tcp`
- `specialtarget=dns action=accept`
- `specialtarget=dns action=drop proto=tcp` - drop DNS queries sent using TCP
- `action=drop`
### Keys set by VM for passing info to dom0 ###
- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
- Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux.
- Qubes 4.0+ format: used memory size in the VM, in kbytes
- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries:
- `desc` - device description (ASCII text)
- `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write
- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
- `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3)
Qubes RPC
---------
Services called by dom0 to provide some VM configuration:
- `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
- `qubes.WaitForSession` - called to wait for full VM startup
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
1. Caller sends name of requested icon. This can be one of:
* `xdgicon:NAME` - search for NAME in standard icons theme
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
* file name
2. The service responds with image dimensions: width and height as
decimal numbers, separated with space and with EOL marker at the and; then
image data in RGBA format (32 bits per pixel)
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
triggered manually from dom0 by calling `qvm-sync-clock`). The service
receives one line at stdin - time in format of `date -u -Iseconds`, for
example `2015-07-31T16:10:43+0000`.
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
or `SEAMLESS`
- `qubes.ResizeDisk` - called to inform that underlying disk was resized.
Name of disk image is passed on standard input (`root`, `private`, `volatile`,
or other). This is used starting with Qubes 4.0.
Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by
the user (one line, terminated by '\n'), the backup archive ([description of
backup format](/doc/BackupEmergencyRestoreV2/))
- `qubes.DetachPciDevice` - service called in reaction to `qvm-pci -d` call on
running VM. The service receives one word - BDF of device to detach. When the
service call ends, the device will be detached
- `qubes.Filecopy` - receive some files from other VM. Files sent in [qfile format](/doc/qfilecopy/)
- `qubes.OpenInVM` - open a file in called VM. Service receives a single file on stdin (in
[qfile format](/doc/qfilecopy/). After a file viewer/editor is terminated, if
the file was modified, can be sent back (just raw content, without any
headers); otherwise service should just terminate without sending anything.
This service is used by both `qvm-open-in-vm` and `qvm-open-in-dvm` tools. When
called in DispVM, service termination will trigger DispVM cleanup.
- `qubes.Restore` - retrieve Qubes backup. The service receives backup location
entered by the user (one line, terminated by '\n'), then should output backup
archive in [qfile format](/doc/qfilecopy/) (core-agent-linux component contains
`tar2qfile` utility to do the conversion
- `qubes.SelectDirectory`, `qubes.SelectFile` - services which should show
file/directory selection dialog and return (to stdout) a single line
containing selected path, or nothing in case of cancellation
- `qubes.SuspendPre` - service called in every VM with PCI device attached just
before system suspend
- `qubes.SuspendPost` - service called in every VM with PCI device attached just
after system resume
- `qubes.SyncNtpClock` - service called to trigger network time synchronization.
Service should synchronize local VM time and terminate when done.
- `qubes.WindowIconUpdater` - service called by VM to send icons of individual
windows. The protocol there is simple one direction stream: VM sends window ID
followed by icon in `qubes.GetImageRGBA` format, then next window ID etc. VM
can send icon for the same window multiple times to replace previous one (for
example for animated icons)
- `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line
Currently Qubes still calls few tools in VM directly, not using service
abstraction. This will change in the future. Those tools are:
- `/usr/lib/qubes/qubes-download-dom0-updates.sh` - script to download updates (or new packages to be installed) for dom0 (`qubes-dom0-update` tool)
- `date -u -Iseconds` - called directly to retrieve time after calling `qubes.SyncNtpClock` service (`qvm-sync-clock` tool)
- `nm-online -x` - called before `qubes.SyncNtpClock` service call by `qvm-sync-clock` tool
- `resize2fs` - called to resize filesystem on /rw partition by `qvm-grow-private` tool
- `gpk-update-viewer` - called by Qubes Manager to display available updates in a TemplateVM
- `systemctl start qubes-update-check.timer` (and similarly stop) - called when enabling/disabling updates checking in given VM (`qubes-update-check` [qvm-service](/doc/qubes-service/))
Additionally automatic tests extensively calls various commands directly in VMs. We do not plan to change that.
GUI protocol
------------
GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.

0
developers/debugging/windows-debugging.md → debugging/windows-debugging.md
View File

57
developers/building/kde-dom0.md
View File

@ -1,57 +0,0 @@
---
layout: doc
title: KDE dom0
permalink: /doc/kde-dom0/
redirect_from:
- /en/doc/kde-dom0/
- /doc/KdeDom0/
- /wiki/KdeDom0/
---
Qubes-customized KDE packages for Dom0
======================================
The Qubes kde-dom0 project (see [Source Code](/doc/source-code/)) contains the source code needed for building the customized KDE packages for use in Qubes Dom0 (the user desktop). The packages are based on Fedora 12 KDE packages, but are heavily slimmed down (Qubes doesn't need lots of KDE functionality in Dom0, such as most of the KDE apps). In the near future those KDE packages will also get some Qubes specific extensions, such as coloured titlebars/frames nicely integrated into the KDE Window Manager. And, of course, custom themes, e.g. for KDM :)
Getting the sources
-------------------
~~~
git clone git://qubes-os.org/mainstream/kde-dom0.git kde-dom0
~~~
Building the packages
---------------------
It's best to use Fedora 12 or 13 as a development system.
First, you should download and verify the original KDE sources (not part of the kde-dom0 repository):
~~~
make get-sources verify-sources
~~~
Now, check if you have all the required build dependencies:
~~~
make prep
~~~
Install any required packages that `make` might have complained about. Then you're ready to build the rpms (you might want to adjust the release of each rpm package by editing the `rel` variable at the beginning of each `.spec` file):
~~~
make rpms
~~~
**Note:** The `kdebase-*` packages build process requires corresponding `kdelibs-devel` package to be installed first. If your build system is based on Fedora 12/13, and if the `kdelibs-devel` package exist in Fedora repo that is based the same KDE software version (e.g. 4.4.3) as the KDE packages you're building (see the `version` file), than you should be able to use the Fedora package:
~~~
yum install kdelibs-devel-{version}
~~~
If not, then you should build your `kdelibs-devel` first (`cd kdelibs-devel && make rpms`), then install it on your build system, and then you can build all the rest (`make rpms`).
Installing KDE packages from Qubes repository
---------------------------------------------
TODO

34
developers/contributing.md
View File

@ -1,34 +0,0 @@
---
layout: doc
title: Contributing
permalink: /doc/contributing/
redirect_from:
- /en/doc/contributing/
- /doc/ContributingHowto/
- /wiki/ContributingHowto/
---
How can I contribute to the Qubes Project?
==========================================
Ok, so you think Qubes Project is cool and you would like to contribute? You are very welcome!
First you should decide what you are interested in (and good in). The Qubes project would welcome contributions in various areas:
- Testing and [bug reporting](/doc/reporting-bugs/)
- Code audit (e.g. gui-daemon)
- New features
- Artwork (plymouth themes, KDM themes, installer themes, wallpapers, etc)
- [Documentation](/doc/doc-guidelines)
Perhaps the best starting point is to have a look at the [issues](https://github.com/QubesOS/qubes-issues/issues) to see what are the most urgent tasks to do.
Before you engage in some longer activity, e.g. implementing a new feature, it's always good to contact us first (preferably via the [qubes-devel](/doc/mailing-lists/) list), to avoid a situation when two or more independent people would work on the same feature at the same time, doubling each other's work. When you contact us and devote to a particular task, we will create a ticket for this task with info who is working on this feature and what is the expected date of some early code to be posted.
When you are ready to start some work, read how to [access Qubes sources and send patches](/doc/source-code/).
You can also contribute in other areas than coding and testing, e.g. by providing mirrors for Qubes rpm repositories, providing feedback about what features you would like to have in Qubes, or perhaps even preparing some cool You Tube videos that would demonstrate some Qubes' features. You are always encouraged to discuss your ideas on qubes-devel.
You should be aware, however, that we will not blindly accept all the contributions! We will accept only the quality ones. Open source doesn't mean lack of quality control! If we reject your patch, please do not get discouraged, try fixing it so that it adheres to the required standards. We will only reject contributions in the good faith, to make Qubes a better OS.
Thanks, [The Qubes Project team](/team).

129
developers/debugging/vm-interface.md
View File

@ -1,129 +0,0 @@
---
layout: doc
title: VM Configuration Interface
permalink: /doc/vm-interface/
redirect_from:
- /en/doc/vm-interface/
- /doc/VMInterface/
- /doc/SystemDoc/VMInterface/
- /wiki/SystemDoc/VMInterface/
---
VM Configuration Interface
==========================
Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
- XenStore
- QubesDB - replacing most of xenstore (in R3 only)
- Qubes RPC (called at VM startup, or when configuration changed)
- GUI protocol
xenstore
--------
Keys exposed by dom0 to VM (only Qubes specific included):
- `qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
- `qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
- `qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
- `qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using qvm-service command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService)
- `qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- \`qubes-ip - IP address for this VM (only when VM has netvm set)
- `qubes-gateway` - default gateway IP and primary DNS address (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
- `qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); because this is also set as primary DNS in connected VMs, traffic sent to this IP on port 53 should be redirected to DNS server
- `qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
- `qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
Keys set by VM for passing info to dom0:
- `memory/meminfo` - used memory (updated by qubes-meminfo-writer), input information for qmemman; Format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux
- `qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries:
- `desc` - device description (ASCII text)
- `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write
- `qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
- `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3)
Qubes RPC
---------
Services called by dom0 to provide some VM configuration:
- `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y`
- `qubes.WaitForSession` - called to wait for full VM startup
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
1. Caller sends name of requested icon. This can be one of:
* `xdgicon:NAME` - search for NAME in standard icons theme
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
* file name
2. The service responds with image dimensions: width and height as
decimal numbers, separated with space and with EOL marker at the and; then
image data in RGBA format (32 bits per pixel)
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
triggered manually from dom0 by calling `qvm-sync-clock`). The service
receives one line at stdin - time in format of `date -u -Iseconds`, for
example `2015-07-31T16:10:43+0000`.
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
or `SEAMLESS`
Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by
the user (one line, terminated by '\n'), the backup archive ([description of
backup format](/doc/BackupEmergencyRestoreV2/))
- `qubes.DetachPciDevice` - service called in reaction to `qvm-pci -d` call on
running VM. The service receives one word - BDF of device to detach. When the
service call ends, the device will be detached
- `qubes.Filecopy` - receive some files from other VM. Files sent in [qfile format](/doc/qfilecopy/)
- `qubes.OpenInVM` - open a file in called VM. Service receives a single file on stdin (in
[qfile format](/doc/qfilecopy/). After a file viewer/editor is terminated, if
the file was modified, can be sent back (just raw content, without any
headers); otherwise service should just terminate without sending anything.
This service is used by both `qvm-open-in-vm` and `qvm-open-in-dvm` tools. When
called in DispVM, service termination will trigger DispVM cleanup.
- `qubes.Restore` - retrieve Qubes backup. The service receives backup location
entered by the user (one line, terminated by '\n'), then should output backup
archive in [qfile format](/doc/qfilecopy/) (core-agent-linux component contains
`tar2qfile` utility to do the conversion
- `qubes.SelectDirectory`, `qubes.SelectFile` - services which should show
file/directory selection dialog and return (to stdout) a single line
containing selected path, or nothing in case of cancellation
- `qubes.SuspendPre` - service called in every VM with PCI device attached just
before system suspend
- `qubes.SuspendPost` - service called in every VM with PCI device attached just
after system resume
- `qubes.SyncNtpClock` - service called to trigger network time synchronization.
Service should synchronize local VM time and terminate when done.
- `qubes.WindowIconUpdater` - service called by VM to send icons of individual
windows. The protocol there is simple one direction stream: VM sends window ID
followed by icon in `qubes.GetImageRGBA` format, then next window ID etc. VM
can send icon for the same window multiple times to replace previous one (for
example for animated icons)
- `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line
Currently Qubes still calls few tools in VM directly, not using service
abstraction. This will change in the future. Those tools are:
- `/usr/lib/qubes/qubes-download-dom0-updates.sh` - script to download updates (or new packages to be installed) for dom0 (`qubes-dom0-update` tool)
- `date -u -Iseconds` - called directly to retrieve time after calling `qubes.SyncNtpClock` service (`qvm-sync-clock` tool)
- `nm-online -x` - called before `qubes.SyncNtpClock` service call by `qvm-sync-clock` tool
- `resize2fs` - called to resize filesystem on /rw partition by `qvm-grow-private` tool
- `gpk-update-viewer` - called by Qubes Manager to display available updates in a TemplateVM
- `systemctl start qubes-update-check.timer` (and similarly stop) - called when enabling/disabling updates checking in given VM (`qubes-update-check` [qvm-service](/doc/qubes-service/))
Additionally automatic tests extensively calls various commands directly in VMs. We do not plan to change that.
GUI protocol
------------
GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.

81
developers/reporting-bugs.md
View File

@ -1,81 +0,0 @@
---
layout: doc
title: Reporting Bugs
permalink: /doc/reporting-bugs/
redirect_from:
- /en/doc/reporting-bugs/
- /doc/BugReportingGuide/
- /wiki/BugReportingGuide/
---
Bug Reporting Guide
===================
One of the most important contribution task is reporting the bugs you have found.
Asking a Question
-----------------
Before you ask, do some searching and reading. Check [the
docs](https://www.qubes-os.org/doc/), Google, GitHub, and StackOverflow. If
your question is something that has been answered many times before, the
project maintainers might be tired of repeating themselves.
Whenever possible, ask your question on the Qubes mailing list which is
located [here](https://groups.google.com/forum/#!forum/qubes-users). This
allows anyone to answer and makes the answer available for the next person
with the same question.
Submitting a Bug Report (or "Issue")
------------------------------------
On GitHub, "Bug Reports" are called "Issues."
Issues can be submitted to the Qubes project located at
[https://github.com/QubesOS/qubes-issues](https://github.com/QubesOS/qubes-issues).
### Has This Been Asked Before?
Before you submit a bug report, you should search existing issues. Be 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.
### Nope, Hasn't Been Asked Before
If you can't find anything in the existing issues, don't be shy about
filing a new one.
You should be sure to include the version the project, as well as versions
of related software. For example, be sure to include the Qubes release
version (R2, R3) and specific version numbers of package causing problems
(if known).
If your issue is related to hardware, provide as many details as possible
about the hardware, which could include using commandline tools such as
`lspci`.
Project maintainers really appreciate thorough explanations. It usually
helps them address the problem more quickly, so everyone wins!
Improving the Code
------------------
The best way is to "Fork" the repo on GitHub. This will create a copy of
the repo on your GitHub account.
Before you set out to improve the code, you should have a focused idea in
mind of what you want to do.
Each commit should do one thing, and each PR should be one specific
improvement. Each PR needs to be signed.
* [How can I contribute to the Qubes Project?](https://www.qubes-os.org/doc/ContributingHowto/)
* [Developer Documentation](https://www.qubes-os.org/doc/)
* [Package Release Workflow](https://github.com/QubesOS/qubes-builder/blob/master/doc/ReleaseManagerWorkflow.md)

52
developers/system-doc.md
View File

@ -1,52 +0,0 @@
---
layout: doc
title: System Documentation
permalink: /doc/system-doc/
redirect_from:
- /en/doc/system-doc/
- /doc/SystemDoc/
- /wiki/SystemDoc/
---
System Documentation for Developers
===================================
Fundamentals
------------
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
(The original 2009 document that started this all...)
* [Security-critical elements of Qubes OS](/doc/security-critical-code/)
* [Qrexec: command execution in VMs](/doc/qrexec3/)
* [Qubes GUI virtualization protocol](/doc/gui/)
* [Networking in Qubes](/doc/networking/)
* [Implementation of template sharing and updating](/doc/template-implementation/)
Services
--------
* [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/doc/qmemman/)
* [Implementation of DisposableVMs](/doc/dvm-impl/)
* [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
* VM secure update mechanism (forthcoming)
Debugging
---------
* [Profiling python code](/doc/profiling/)
* [Test environment in separate machine for automatic tests](/doc/test-bench/)
* [Automated tests](/doc/automated-tests/)
* [VM-dom0 internal configuration interface](/doc/vm-interface/)
* [Debugging Windows VMs](/doc/windows-debugging/)
Building
--------
* [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
* [Development Workflow](/doc/development-workflow/)
* [KDE Dom0 packages for Qubes](/doc/kde-dom0/)
* [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/)
* [Building USB passthrough support (experimental)](/doc/pvusb/)
* [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
* [Building the Archlinux Template](/doc/building-archlinux-template/)

163
doc.md
View File

@ -1,5 +1,5 @@
---
layout: default
layout: doc-index
title: Documentation
permalink: /doc/
redirect_from:
@ -8,27 +8,44 @@ redirect_from:
- /wiki/UserDoc/
- /doc/QubesDocs/
- /wiki/QubesDocs/
- /help/
- /en/help/
- /en/community/
- /community/
---
User Documentation
==================
The Basics
----------
* [A Tour of Qubes OS](/tour/)
* [What is Qubes OS?](/intro/)
* [Video Tours](/video-tours/)
* [Screenshots](/screenshots/)
* [Getting Started](/getting-started/)
* [User FAQ](/doc/user-faq/)
* [Mailing Lists](/mailing-lists/)
* [How to Contribute](/doc/contributing/)
Security Information
--------------------
* [Security Main Page](/security/)
* [Security Pack](/doc/security-pack/)
* [Security Bulletins](/doc/security-bulletins/)
* [Canaries](/doc/canaries/)
* [Why and How to Verify Signatures](/doc/verifying-signatures/)
* [Qubes PGP Keys](http://keys.qubes-os.org/keys/)
Choosing Your Hardware
----------------------
* [System Requirements](/doc/system-requirements/)
* [Hardware Compatibility List (HCL)](/hcl/)
* [Qubes-Certified Laptops](/doc/certified-laptops/)
* [Hardware Certification](/hardware-certification/)
Installing & Upgrading Qubes
----------------------------
* [Qubes Downloads](/downloads/)
* [Installation Guide](/doc/installation-guide/)
* [Upgrade Guides](/doc/upgrade/)
@ -37,13 +54,13 @@ Installing & Upgrading Qubes
* [Try Qubes without installing: Qubes Live USB (alpha)](/doc/live-usb/)
* [Supported Versions](/doc/supported-versions/)
* [Version Scheme](/doc/version-scheme/)
* [Custom Installation](/doc/custom-install/)
Common Tasks
------------
* [Copying and Pasting Text Between Domains](/doc/copy-paste/)
* [Copying and Moving Files Between Domains](/doc/copying-files/)
* [Copying Files to and from dom0](/doc/copy-to-dom0/)
* [Copying from (and to) dom0](/doc/copy-from-dom0/)
* [Updating Software in dom0](/doc/software-update-dom0/)
* [Updating and Installing Software in VMs](/doc/software-update-vm/)
* [Backup, Restoration, and Migration](/doc/backup-restore/)
@ -56,54 +73,59 @@ Common Tasks
Managing Operating Systems within Qubes
---------------------------------------
* [TemplateVMs](/doc/templates/)
* [Templates: Fedora - minimal](/doc/templates/fedora-minimal/)
* [Templates: Fedora](/doc/templates/fedora/)
* [Templates: Fedora Minimal](/doc/templates/fedora-minimal/)
* [Templates: Debian](/doc/templates/debian/)
* [Templates: Archlinux](/doc/templates/archlinux/)
* [Templates: Ubuntu](/doc/templates/ubuntu/)
* [Templates: Whonix](/doc/whonix/)
* [Pentesting](/doc/pentesting/)
* [Pentesting: BlackArch](/doc/pentesting/blackarch/)
* [Pentesting: Kali](/doc/pentesting/kali/)
* [Pentesting: PTF](/doc/pentesting/ptf/)
* [Windows: Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/)
* [Windows: Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/)
* [Windows: Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/)
* [Windows: Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/)
* [Windows: Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/)
* [Fedora: Upgrading the Fedora 23 Template to Fedora 24](/doc/template/fedora/upgrade-23-to-24/)
* [Fedora: Upgrading the Fedora 21 Template to Fedora 23](/doc/template/fedora/upgrade-21-to-23/)
* [Fedora: Upgrading the Fedora 20 Template to Fedora 21](/doc/template/fedora/upgrade-20-to-21/)
* [Fedora: Upgrading the Fedora 18 Template to Fedora 20](/doc/template/fedora/upgrade-18-to-20/)
* [Debian: Upgrading the Debian 8 Template to Debian 9](/doc/template/debian/upgrade-8-to-9/)
* [How to Reinstall a TemplateVM](/doc/reinstall-template)
* [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/)
* [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/doc/windows-tools-2/)
* [Uninstalling Qubes Tools for Windows 2.x](/doc/uninstalling-windows-tools-2/)
* [Upgrading the Fedora 21 Template](/doc/fedora-template-upgrade-21/)
* [Upgrading the Fedora 20 Template](/doc/fedora-template-upgrade-20/)
* [Upgrading the Fedora 18 Template](/doc/fedora-template-upgrade-18/)
* [Upgrading the Debian 8 Template](/doc/debian-template-upgrade-8/)
* [Tips for Using Linux in an HVM](/doc/linux-hvm-tips/)
* [Creating a NetBSD VM](/doc/netbsd/)
Security Guides
---------------
* [Qubes OS Project Security Information](/security/)
* [Security Guidelines](/doc/security-guidelines/)
* [Understanding Qubes Firewall](/doc/qubes-firewall/)
* [Understanding Qubes Firewall](/doc/firewall/)
* [Understanding and Preventing Data Leaks](/doc/data-leaks/)
* [Installing Anti Evil Maid](/doc/anti-evil-maid/)
* [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/)
* [Using GPG more securely in Qubes: Split GPG](/doc/split-gpg/)
* [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/)
* [[Unofficial] Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt)
* [Configuring YubiKey for user authentication](/doc/yubi-key/)
* [Note regarding password-less root access in VM](/doc/vm-sudo/)
Privacy Guides
--------------
* [Whonix for Privacy & Anonymity](/doc/whonix/)
* [Running Tails in Qubes](/doc/tails/)
* [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/)
* [TorVM](/doc/torvm/)
* [Martus](/doc/martus/)
* [Signal](/doc/signal/)
Configuration Guides
--------------------
* [Configuration Files](/doc/config-files/)
* [How to set up a ProxyVM as a VPN Gateway](/doc/vpn/)
* [Storing AppVMs on Secondary Drives](/doc/secondary-storage/)
@ -132,7 +154,6 @@ Configuration Guides
Customization Guides
--------------------
* [DispVM Customization](/doc/dispvm-customization/)
* [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization)
* [Customizing Windows 7 templates](/doc/windows-template-customization)
@ -140,24 +161,26 @@ Customization Guides
* [Installing XFCE in dom0](/doc/xfce/)
* [Installing i3 in dom0](/doc/i3/)
* [Language Localization](/doc/language-localization/)
* [Dark Theme in Dom0 and DomU](/doc/dark-theme/)
* [How to make any file in a TemplateBasedVM persistent using bind-dirs](/doc/bind-dirs/)
Troubleshooting
---------------
* [Home directory is out of disk space error](/doc/out-of-memory/)
* [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
* [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
* [Solving problems with Macbook Air 2012](https://groups.google.com/group/qubes-devel/browse_thread/thread/b8b0d819d2a4fc39/d50a72449107ab21#8a9268c09d105e69)
* [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
* [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/)
* [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/)
* [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/)
* [Getting Lenovo 450 to work with Qubes](/doc/lenovo450-tinkering/)
* [Getting Lenovo Thinkpad X201 to work with Qubes](/doc/thinkpad_x201/)
* [Troubleshooting UEFI related problems](/doc/uefi-troubleshooting/)
* [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/)
* [How to remove VMs manually](/doc/remove-vm-manually/)
Reference Pages
---------------
* [Dom0 Command-Line Tools](/doc/dom0-tools/)
* [DomU Command-Line Tools](/doc/vm-tools/)
* [Glossary of Qubes Terminology](/doc/glossary/)
@ -169,23 +192,87 @@ Presentation Slides
-------------------
* [[PDF] LinuxCon 2014 -- Qubes OS R2 Tutorial](/attachment/wiki/slides/LinuxCon_2014_Qubes_Tutorial.pdf)
* [[PDF] LinuxCon 2014 -- Qubes OS Keynote](/attachment/wiki/slides/LinuxCon_2014_Qubes_Keynote.pdf)
* [[PDF] RMLL 2016 -- Improving client systems security with Qubes OS](/attachment/wiki/slides/RMLL_2016_Improving-client-systems-security.pdf)
Developer Documentation
=======================
For Developers
--------------
* [System Documentation](/doc/system-doc/)
* [Developers' FAQ](/doc/devel-faq/)
* [Feature Development Tracker](/qubes-issues/)
* [Reporting Security Issues](/security/)
* [Reporting Bugs](/doc/reporting-bugs/)
The Basics
----------
* [Developer FAQ](/doc/devel-faq/)
* [Report a Security Issue](/security/)
* [Report a Bug](/doc/reporting-bugs/)
* [How to Contribute](/doc/contributing/)
* [Source Code](/doc/source-code/)
* [How to Contribute to the Qubes OS Project](/doc/contributing/)
* [Qubes OS License](/doc/license/)
* [Coding Guidelines](/doc/coding-style/)
* [Documentation Guidelines](/doc/doc-guidelines/)
* [Code Signing](/doc/code-signing/)
* [Community-Developed Feature Tracker](/qubes-issues/)
* [Books for Developers](/doc/devel-books/)
* [Qubes OS License](/doc/license/)
* [Style Guide](/doc/style-guide/)
* [Usability & UX](/doc/usability-ux/)
Security Information
--------------------
* [Security Main Page](/security/)
* [Security Goals](/doc/security-goals/)
* [Security Pack](/doc/security-pack/)
* [Security Bulletins](/doc/security-bulletins/)
* [Security Bulletin Checklist](/doc/security-bulletins/checklist/)
* [Security Bulletin Template](/doc/security-bulletins/template/)
* [Canaries](/doc/canaries/)
* [Why and How to Verify Signatures](/doc/verifying-signatures/)
* [Qubes PGP Keys](http://keys.qubes-os.org/keys/)
System
------
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
* [Security-critical elements of Qubes OS](/doc/security-critical-code/)
* [Qrexec: command execution in VMs](/doc/qrexec3/)
* [Qubes GUI virtualization protocol](/doc/gui/)
* [Networking in Qubes](/doc/networking/)
* [Implementation of template sharing and updating](/doc/template-implementation/)
* [Storage Pools](/doc/storage-pools/)
Services
--------
* [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/doc/qmemman/)
* [Implementation of DisposableVMs](/doc/dvm-impl/)
* [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
* VM secure update mechanism (forthcoming)
Debugging
---------
* [Profiling python code](/doc/profiling/)
* [Test environment in separate machine for automatic tests](/doc/test-bench/)
* [Automated tests](/doc/automated-tests/)
* [VM-dom0 internal configuration interface](/doc/vm-interface/)
* [Debugging Windows VMs](/doc/windows-debugging/)
* [Safe Remote Dom0 Terminals](/doc/safe-remote-ttys/)
Building
--------
* [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
* [Development Workflow](/doc/development-workflow/)
* [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/)
* [Building USB passthrough support (experimental)](/doc/pvusb/)
* [Building Qubes Templates](https://github.com/QubesOS/qubes-template-configs)
* [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
* [Building the Archlinux Template](/doc/building-archlinux-template/)
Releases
--------
* [Release checklist](/doc/releases/todo/)
* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)

14
hardware/certified-laptops.md
View File

@ -26,8 +26,10 @@ the hardware will not being modified in any way (malicious or not).
For more general information about choosing hardware for Qubes, please see the
[System Requirements] and the [Hardware Compatibility List].
Purism Librem 13
----------------
Certified for Qubes R3.x
------------------------
### Purism Librem 13 ###
[![image of Librem 13](/attachment/site/qubes-plus-purism.png)](https://puri.sm/librem-13/)
@ -49,9 +51,15 @@ compatibility with Qubes:
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel
Certified for Qubes R4.x
------------------------
There are [updated requirements] for Qubes R4.x certification. Currently, no
laptops are certified for Qubes R4.x. This page will be updated once
R4.x-certified laptops are available.
[System Requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[Hardware Certification]: /hardware-certification/
[updated requirements]: /news/2016/07/21/new-hw-certification-for-q4/

1
hardware/hcl.md
View File

@ -39,7 +39,6 @@ In order to generate a HCL report in Qubes, simply open a terminal in dom0 (KDE:
You are encouraged to submit your HCL report for the benefit of further Qubes development and other users.
If you would like to submit your HCL report, please send the **HCL Info** `.yml` file to [\`qubes-users@googlegroups.com\`](/doc/mailing-lists/) with the subject `HCL - <your machine model name>`.
Please include any useful information about any Qubes features you may have tested (see the legend below), as well as general machine compatibility (video, networking, sleep, etc.).
If you have problems with your hardware try a different kernel in the [Troubleshooting menu](/doc/InstallationGuideR2rc1/#troubleshooting-problems-with-the-installer).
Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To generate these add the `-s` or `--support` command line option.
**Please note:**

62
hardware/system-requirements.md
View File

@ -8,45 +8,62 @@ redirect_from:
- /wiki/SystemRequirements/
---
System Requirements
===================
# System Requirements #
Minimum
-------
## Qubes Release 3.x ##
### Minimum ###
* 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
* 4 GB RAM
* 32 GB disk space
* Legacy boot mode ([UEFI is not supported yet][UEFI])
* Legacy boot mode (required for R3.0 and earlier; UEFI is supported beginning
with R3.1)
Recommended
-----------
### Recommended ###
* Fast SSD (strongly recommended)
* Intel GPU (strongly preferred)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility
List]).
* Intel VT-x or AMD-v technology (required for running HVM domains, such as
* [Intel VT-x] or [AMD-V] (required for running HVM domains, such as
Windows-based AppVMs)
* Intel VT-d or AMD IOMMU technology (required for effective isolation of
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] (required for effective isolation of
network VMs)
* TPM with proper BIOS support (required for [Anti Evil Maid])
## Qubes Release 4.x ##
Choosing Hardware
-----------------
### Minimum ###
* 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
* [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)]
* 4 GB RAM
* 32 GB disk space
### Recommended ###
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* ATI GPUs have not been formally tested (but see the [Hardware Compatibility
List]).
* TPM with proper BIOS support (required for [Anti Evil Maid])
* A non-USB keyboard or multiple USB controllers
* Also consider the [hardware certification requirements for Qubes 4.x].
## Choosing Hardware ##
* Please see the [Hardware Compatibility List] for a compilation of
hardware reports generated and submitted by users across various Qubes
versions. (For more information about the HCL itself, see [here][hcl-doc]).
* For more certain hardware compatibility, you may wish to consider a
[Qubes-certified laptop].
[Qubes-certified laptop]. (For information about how a computer becomes
Qubes-certified, see [Hardware Certification].)
Important Notes
---------------
## Important Notes ##
* Qubes **can** be installed on systems which do not meet the recommended
requirements. Such systems will still offer significant security
@ -75,14 +92,21 @@ Important Notes
* [Advice on finding a VT-d capable notebook][vt-d-notebook].
[UEFI]: https://github.com/QubesOS/qubes-issues/issues/794
[nvidia]: /doc/install-nvidia-driver/
[hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/
[Hardware Certification]: /hardware-certification/
[Hardware Compatibility List]: /hcl/
[hcl-doc]: /doc/hcl/
[hcl-report]: /doc/HCL/#generating-and-submitting-new-reports
[hcl-report]: /doc/hcl/#generating-and-submitting-new-reports
[Anti Evil Maid]: /doc/anti-evil-maid/
[Qubes-certified laptop]: /doc/certified-laptops/
[live USB]: /doc/live-usb/
[#230]: https://github.com/QubesOS/qubes-issues/issues/230
[vt-d-notebook]: https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J
[Intel VT-x]: https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29
[AMD-V]: https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29
[Intel VT-d]: https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d
[AMD-Vi (aka AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29
[EPT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables
[RVI]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing

193
installing/custom-install.md Normal file
View File

@ -0,0 +1,193 @@
---
layout: doc
title: Custom Installation
permalink: /doc/custom-install/
redirect_from:
- /doc/encryption-config/
---
Custom Installation
===================
In the present context, "custom installation" refers to things like manual
partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
Installer Defaults (R3.2)
-------------------------
For reference, these are the defaults for a single disk:
~~~
Mount Point: `/`
Desired Capacity: (your choice)
Device Type: `LVM`
Volume Group: `qubes_dom0`
File System: `ext4`
Name: `root`
Mount Point: `/boot`
Desired Capacity: 500 MiB (recommended)
Device Type: Standard Partition
File System: `ext4`
Mount Point: (none)
Desired Capacity: 9.44 GiB (recommended)
Device Type: LVM
Volume Group: qubes_dom0
File System: `swap`
Name: `swap`
~~~
Typical Partition Schemes
-------------------------
If you want your partition/LVM scheme to look like the Qubes default but
with a few tweaks, follow these examples. With a single disk, the result
should look something like this:
~~~
NAME TYPE MOUNTPOINT
sda disk
├──sda1 part /boot
└──sda2 part
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
~~~
If you're using `mdadm` software RAID, it should look something like this:
~~~
NAME TYPE MOUNTPOINT
sda disk
├──sda1 part
│ └──md0 raid1 /boot
└──sda2 part
└──md1 raid1
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
sdb disk
├──sdb1 part
│ └──md0 raid1 /boot
└──sdb2 part
└──md1 raid1
└──luks-<UUID> crypt
├──qubes_dom0-root lvm /
└──qubes_dom0-swap lvm [SWAP]
~~~
Example: LVM on LUKS on RAID (R3.2)
-----------------------------------
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual
console.
1. (Optional) Wipe both disks:
# hdparm --user-master u --security-set-pass pass /dev/sda
# time hdparm --user-master u --security-erase-enhanced pass /dev/sda
# hdparm --user-master u --security-set-pass pass /dev/sdb
# time hdparm --user-master u --security-erase-enhanced pass /dev/sdb
2. Create desired partitions:
# fdisk /dev/sda
<create partitions>
# fdisk /dev/sdb
<create partitions>
3. Create RAID devices:
# mdadm --create --verbose /dev/md0 --level=mirror --raid-devices=2 /dev/sda1 /dev/sdb1
# mdadm --create --verbose /dev/md1 --level=mirror --raid-devices=2 /dev/sda2 /dev/sdb2
4. Create LUKS encrypted volume:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 5000 --verify-passphrase luksFormat /dev/md1
5. Open encrypted volume:
# cryptsetup open /dev/md1 luks
6. Create LVM volumes:
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -n root -l +100%FREE qubes_dom0
7. Proceed with installer. At the disk selection screen, select:
[x] I will configure partitioning.
[ ] Encrypt my data.
Continue normally from here.
Manual Encryption Configuration (R3.1)
--------------------------------------
Qubes OS uses full disk encryption (FDE) by default. If you are an advanced
user who wishes to customize your encryption parameters during installation,
this page can help.
The Qubes installer uses `cryptsetup` (LUKS/dm-crypt) under the hood. You can
configure the encryption options while installing Qubes as follows:
01. Boot into the installer. Wait for first GUI screen to appear where it asks
about language/localization .
02. Press `Ctrl+Alt+F2` on your keyboard to escape to a shell session. (If you
are on a laptop, and your laptop keyboard does not work properly, you may have
to plug in a USB keyboard.)
03. Check and adjust the partitioning on the drive you plan to install to with
`parted`. For example, you can leave the partition table as `msdos/MBR` type,
then create a 500 MB ext4 boot partition, a 10 GB swap partition, and use the
rest of the drive (minus overprovisioning space for SSDs) for the root
partition.
04. Run to set the LUKS options as you like and set the passphrase:
# cryptsetup <options> luksFormat <partition>
For example:
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 5000 --verify-passphrase luksFormat /dev/sda2
05. (Optional) Make sure the new container works:
# cryptsetup open /dev/sda2 test
# mkfs.ext4 /dev/mapper/test
# mount /dev/mapper/test /mnt/test
# umount /dev/mapper/test
# cryptsetup close test
06. Everything should be set with the preparation, so press `Ctrl+Alt+F7` to go
back to the GUI installer.
07. Continue installing as usual. When you get to the disk
partitioning/allocation part, pay attention.
08. When you select the disk, it may complain about only having a few MB of
space. Uncheck the "Encrypt and ask me about the passphrase later" box and
press the "Custom" button.
09. In this menu, you should see the unencrypted boot partition and the encrypted
LUKS partitions you created earlier. You must unlock the LUKS partition here,
i.e. enter passphrases.
10. Set the mount points on these partitions once they are decrypted. (This part
may be a bit glitchy, but you should be able to get it working after a
reboot.) For example, set the mount point for the primary LUKS partition as
`/`. Make sure the "Encrypted" box stays checked and that you check the
"Format" box (required for the root partition). Similarly, set `/boot` as
the mount point for the unencrypted boot partition and `swap` as the mount
point for the swap partition.
11. Now the install should complete without any other issues. When it's
finished, you'll have LUKS-encrypted partitions with the options you chose
above. You can verify this command in dom0:
# cryptsetup luksDump <partition>
For example:
# cryptsetup luksDump /dev/sda2

2
installing/live-usb.md
View File

@ -100,7 +100,7 @@ Downloading and burning
-----------------------
1. Download the ISO (and its signature for verification) from the
[downloads page](/downloads/#qubes-live-usb-alpha/).
[downloads page](/downloads/#qubes-live-usb-alpha).
2. "Burn" (copy) the ISO onto a USB drive (replace `/dev/sdX` with your USB
drive device):

57
installing/supported-versions.md
View File

@ -4,37 +4,51 @@ title: Supported Versions
permalink: /doc/supported-versions/
---
<style>
article td, article th {
border-width: 2px;
border-style: double;
padding: 5px;
}
</style>
Supported Versions
==================
Qubes OS
--------
Qubes OS releases are supported for **six months** after each subsequent major
or minor release. The version scheme is explained [here](/doc/version-scheme/).
All available current and past downloads can be found [here](/downloads/).
or minor release (see [Version Scheme]). The current release and past major
releases are always available on the [Downloads] page, while all ISOs, including
past minor releases, are available from our [FTP server].
| Qubes OS Version | Start Date | End Date | Status |
| ---------------- | ---------- | ---------- | --------------------------- |
| Release 1 | 2012-09-03 | 2015-03-26 | Old, unsupported |
| Release 2 | 2014-09-26 | 2016-04-01 | Old, unsupported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, supported |
| Release 3.1 | 2016-03-09 | TBA | Current, supported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Old, unsupported |
| Release 3.1 | 2016-03-09 | 2017-03-29 | Old, supported |
| Release 3.2 | 2016-09-29 | TBA | Current, supported |
| Release 4.0 | TBA | TBA | In development |
Templates
---------
The table below shows the [template](/doc/templates/) versions supported by each
Qubes OS release. Currently, only Fedora and Debian templates are officially
supported.
Dom0
----
The table below shows the OS used for dom0 in each Qubes OS release.
| Qubes OS Version | Dom0 OS |
| ---------------- | --------- |
| Release 1 | Fedora 13 |
| Release 2 | Fedora 18 |
| Release 3.0 | Fedora 20 |
| Release 3.1 | Fedora 20 |
| Release 3.2 | Fedora 23 |
| Release 4.0 | TBA |
**Note:** Dom0 is isolated from domUs. DomUs can access only a few interfaces,
such as Xen, device backends (in the dom0 kernel and in other VMs, such as the
NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.). These components are
[security-critical], and we provide updates for all of them (when necessary),
regardless of the support status of the base distribution. For this reason, we
consider it safe to continue using a given base distribution in dom0 even after
it has reached end-of-life.
TemplateVMs
-----------
The table below shows the [TemplateVM] versions supported by each Qubes OS
release. Currently, only Fedora and Debian TemplateVMs are officially supported.
| Qubes OS Version | Fedora Versions | Debian Versions |
| ---------------- | --------------- | --------------------------------------------- |
@ -42,9 +56,16 @@ supported.
| Release 2 | 21 | None |
| Release 3.0 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie") |
| Release 3.1 | 21, 22\*, 23 | 7 ("wheezy")\*, 8 ("jessie"), 9 ("stretch")\* |
| Release 3.2 | TBA | TBA |
| Release 3.2 | 23, 24\* | 8 ("jessie"), 9 ("stretch")\* |
| Release 4.0 | TBA | TBA |
\* Denotes versions for which we have published the packages but have not done
extensive testing.
[Version Scheme]: /doc/version-scheme/
[Downloads]: /downloads/
[FTP server]: https://ftp.qubes-os.org/
[security-critical]: /doc/security-critical-code/
[TemplateVM]: /doc/templates/

2
installing/upgrade/upgrade-to-r2.md
View File

@ -19,7 +19,7 @@ Current Qubes R2 Beta 3 (R2B3) systems can be upgraded in-place to the latest R2
Upgrade Template and Standalone VM(s)
-------------------------------------
- Qubes R2 comes with new template based on Fedora 20. You can upgrade existing template according to procedure described [here](/doc/FedoraTemplateUpgrade/).
- Qubes R2 comes with new template based on Fedora 20. You can upgrade existing template according to procedure described [here](/doc/fedora-template-upgrade-20/).
- **It also possible to download a new Fedora 20-based template from our repositories**. To do this please first upgrade the Dom0 distro as described in the section below.

1
installing/upgrade/upgrade-to-r3.0.md
View File

@ -103,6 +103,7 @@ Upgrading template on already upgraded dom0
When for some reason you did not upgraded all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be somehow more complicated. This can be a case when you restore backup done on Qubes R2.
When you start R2 template/standalone VM on R3.0, there will be some limitations:
1. qrexec will not connect (you will see an error message during VM startup)
2. GUI will not connect - you will not see any VM window
3. VM will not be configured - especially it will not have network access

5
installing/upgrade/upgrade-to-r3.1.md
View File

@ -105,6 +105,11 @@ will have changed. Once the system boots up again, you can reseal your Anti Evil
Maid passphrase to the new configuration. Please consult the Anti Evil Maid
[documentation](/doc/anti-evil-maid) for instructions on how to do that.
If you use USB VM, you may encounter problem with starting it on updated Xen
version (because of strict default settings). Take a look at
[User FAQ](/doc/user-faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot)
for details.
Once you have upgraded dom0, you can install new templates from Qubes R3.1
repositories, in particular the new default Fedora 23 template:

167
installing/upgrade/upgrade-to-r3.2.md Normal file
View File

@ -0,0 +1,167 @@
---
layout: doc
title: Upgrading to R3.2
permalink: /doc/upgrade-to-r3.2/
redirect_from:
- /en/doc/upgrade-to-r3.2/
- /doc/UpgradeToR3.2/
- /doc/UpgradeToR3.2rc1/
---
Upgrading Qubes R3.1 to R3.2
======================================
**Before attempting either an in-place upgrade or a clean installation, we
strongly recommend that users [back up their systems](/doc/backup-restore/).**
Current Qubes R3.1 systems can be upgraded in-place to the latest R3.2
by following the procedure below.
Upgrading dom0
--------------
1. Close Qubes Manager (right click on its tray icon -\> Exit)
2. Open a terminal in Dom0. (E.g., Start -\> System Settings -\> Konsole.)
3. Install `qubes-release` package carrying R3.2 repository information.
sudo qubes-dom0-update --releasever=3.2 qubes-release
If you made any manual changes to repository definitions, new definitions
will be installed as `/etc/yum.repos.d/qubes-dom0.repo.rpmnew` (you'll see
a message about it during package installation). In such a case, you need
to manually apply the changes to `/etc/yum.repos.d/qubes-dom0.repo` or
simply replace it with .rpmnew file.
If you are using Debian-based VM as UpdateVM (`sys-firewall` by default),
you need to download few more packages manually, but **do not install
them** yet:
sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools lvm2
(...)
Transaction Summary
===============================================================
Install 16 Packages (+ 31 Dependent packages)
Upgrade 4 Packages (+200 Dependent packages)
Total download size: 173 M
Is this ok [y/d/N]: n
Exiting on user command
Your transaction was saved, rerun it with:
yum load-transaction /tmp/yum_save_tx.....
4. Upgrade dom0 to R3.2:
sudo qubes-dom0-update
You may wish to disable the screensaver "Lock screen" feature for this step, as
during the update XScreensaver may encounter an "Authentication failed" issue,
requiring a hard reboot. Alternatively, you may simply move the mouse regularly.
5. If the previous step completed successfully, your `qubes-core-dom0` version
should be `3.2.3` or higher. This can be verified with the command `yum info
qubes-core-dom0`. If it's not, repeat the previous step with the `--clean` option.
6. Update configuration files.
Some of configuration files were saved with `.rpmnew` extension as the
actual files were modified. During upgrade, you'll see information about
such cases, like:
warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew
This will happen for every configuration you have modified manually and for
a few that has been modified by Qubes scripts. If you are not sure what to
do about them, below is a list of commands to deal with few common cases
(either keep the old one, or replace with the new one):
rm -f /etc/group.rpmnew
rm -f /etc/shadow.rpmnew
rm -f /etc/qubes/guid.conf.rpmnew
mv -f /etc/nsswitch.conf{.rpmnew,}
mv -f /etc/pam.d/postlogin{.rpmnew,}
mv -f /etc/salt/minion.d/f_defaults.conf{.rpmnew,}
mv -f /etc/dracut.conf{.rpmnew,}
7. Reboot dom0.
Please note that if you use [Anti Evil Maid](/doc/anti-evil-maid), it won't be
able to unseal the passphrase the first time the system boots after performing
this in-place upgrade procedure since the Xen, kernel, and initramfs binaries
will have changed. Once the system boots up again, you can reseal your Anti Evil
Maid passphrase to the new configuration. Please consult the Anti Evil Maid
[documentation](/doc/anti-evil-maid) for instructions on how to do that.
At first login after upgrade you may got a message like this:
Your saved session type 'kde-plasma' is not valid any more.
Please select a new one, otherwise 'default' will be used.
This is result of upgrade KDE4 (`kde-plasma`) to KDE5 (`plasma`). Simply choose
your favorite desktop environment and continue.
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R3.1, there are few TemplateVMs and no StandaloneVMs.
However, users are free to create StandaloneVMs More information on using
multiple TemplateVMs, as well as StandaloneVMs, can be found
[here](/doc/software-update-vm/). The steps described in this section should be
repeated in **all** the user's Template and Standalone VMs.
### Upgrade Fedora templates: ###
**Note:** This will only upgrade your Fedora template from Qubes 3.1 to Qubes
3.2. This will *not* upgrade your Fedora template from Fedora 23 to Fedora 24.
In order to do that, please see the
[Fedora 23 template upgrade instructions](/doc/fedora-template-upgrade-23/).
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
2. Install the `qubes-upgrade-vm` package:
sudo dnf install --refresh qubes-upgrade-vm
3. Proceed with a normal upgrade in the template:
sudo dnf upgrade --refresh
4. Add new packages (only needed in default template):
sudo dnf install qubes-mgmt-salt-vm-connector
5. Shut down the template VM.
### Upgrade Debian (and Whonix) templates: ###
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
2. Update repository definition:
sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r3.1/r3.2/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
3. Proceed with a normal update in the template:
sudo apt-get update
sudo apt-get dist-upgrade
4. Add new packages (only needed in default template):
sudo apt-get install qubes-mgmt-salt-vm-connector
5. Remove unnecessary now file:
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
6. Shut down the template VM.

1
installing/upgrade/upgrade.md
View File

@ -13,4 +13,5 @@ Qubes OS Upgrade Guides
* [Upgrading from R2 Beta 3 to R2](/doc/upgrade-to-r2/)
* [Upgrading from R2 to R3.0](/doc/upgrade-to-r3.0/)
* [Upgrading from R3.0 to R3.1](/doc/upgrade-to-r3.1/)
* [Upgrading from R3.1 to R3.2](/doc/upgrade-to-r3.2/)

225
installing/verifying-signatures.md
View File

@ -14,30 +14,63 @@ On Digital Signatures and Key Verification
What Digital Signatures Can and Cannot Prove
--------------------------------------------
Most people – even programmers – are confused about the basic concepts underlying digital signatures. Therefore, most people should read this section, even if it looks trivial at first sight.
Most people – even programmers – are confused about the basic concepts
underlying digital signatures. Therefore, most people should read this section,
even if it looks trivial at first sight.
Digital signatures can prove both **authenticity** and **integrity** to a reasonable degree of certainty. **Authenticity** ensures that a given file was indeed created by the person who signed it (i.e., that it was not forged by a third party). **Integrity** ensures that the contents of the file have not been tampered with (i.e., that a third party has not undetectably altered its contents *en route*).
Digital signatures can prove both **authenticity** and **integrity** to a
reasonable degree of certainty. **Authenticity** ensures that a given file was
indeed created by the person who signed it (i.e., that it was not forged by a
third party). **Integrity** ensures that the contents of the file have not been
tampered with (i.e., that a third party has not undetectably altered its
contents *en route*).
Digital signatures **cannot** prove any other property, e.g., that the signed file is not malicious. In fact, there is nothing that could stop someone from signing a malicious program (and it happens from time to time in reality).
Digital signatures **cannot** prove any other property, e.g., that the signed
file is not malicious. In fact, there is nothing that could stop someone from
signing a malicious program (and it happens from time to time in reality).
The point is, of course, that people must choose who they will trust (e.g., Linus Torvalds, Microsoft, the Qubes Project, etc.) and assume that if a given file was signed by a trusted party, then it should not be malicious or buggy in some horrible way. But the decision of whether to trust any given party is beyond the scope of digital signatures. It's more of a sociological and political decision.
The point is, of course, that people must choose who they will trust (e.g.,
Linus Torvalds, Microsoft, the Qubes Project, etc.) and assume that if a given
file was signed by a trusted party, then it should not be malicious or buggy in
some horrible way. But the decision of whether to trust any given party is
beyond the scope of digital signatures. It's more of a sociological and
political decision.
Once we make the decision to trust certain parties, digital signatures are useful, because they make it possible for us to limit our trust only to those few parties we choose and not to worry about all the "Bad Things That Can Happen In The Middle" between us and them, e.g., server compromises (qubes-os.org will surely be compromised one day), dishonest IT staff at the hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc.
Once we make the decision to trust certain parties, digital signatures are
useful, because they make it possible for us to limit our trust only to those
few parties we choose and not to worry about all the "Bad Things That Can
Happen In The Middle" between us and them, e.g., server compromises
(qubes-os.org will surely be compromised one day), dishonest IT staff at the
hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc.
By verifying all the files we download which purport to be authored by a party we've chosen to trust, we eliminate concerns about the bad things discussed above, since we can easily detect whether any files have been tampered with (and subsequently choose to refrain from executing, installing, or opening them).
By verifying all the files we download which purport to be authored by a party
we've chosen to trust, we eliminate concerns about the bad things discussed
above, since we can easily detect whether any files have been tampered with
(and subsequently choose to refrain from executing, installing, or opening
them).
However, for digital signatures to make any sense, we must ensure that the public keys we use for signature verification are indeed the original ones. Anybody can generate a GPG key pair that purports to belong to "The Qubes Project," but of course only the key pair that we (i.e., the Qubes developers) generated is the legitimate one. The next section explains how to verify the validity of the Qubes signing keys.
However, for digital signatures to make any sense, we must ensure that the
public keys we use for signature verification are indeed the original ones.
Anybody can generate a GPG key pair that purports to belong to "The Qubes
Project," but of course only the key pair that we (i.e., the Qubes developers)
generated is the legitimate one. The next section explains how to verify the
validity of the Qubes signing keys.
Importing Qubes Signing Keys
----------------------------
Every file published by the Qubes Project (ISO, RPM, TGZ files and git repositories) is digitally signed by one of the developer or release signing keys. Each such key is signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)).
Every file published by the Qubes Project (ISO, RPM, TGZ files and git
repositories) is digitally signed by one of the developer or release signing
keys. Each such key is signed by the [Qubes Master Signing Key]
(`0xDDFA1A3E36879494`).
The public portion of the Qubes Master Signing Key can be imported directly from a [ keyserver](https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples) (specified on first use with --keyserver URI, keyserver saved in `~/.gnupg/gpg.conf`), e.g.,
The public portion of the Qubes Master Signing Key can be imported directly
from a [keyserver] (specified on first use with `--keyserver <URI>`, keyserver
saved in `~/.gnupg/gpg.conf`), e.g.,
gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
or downloaded [here](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) and imported with gpg,
or downloaded [here][Qubes Master Signing Key] and imported with gpg,
$ gpg --import ./qubes-master-signing-key.asc
@ -45,15 +78,23 @@ or fetched directly with gpg.
$ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
For additional security we also publish the fingerprint of the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) here in this document:
For additional security we also publish the fingerprint of the Qubes Master
Signing Key here in this document:
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key
There should also be a copy of this key at the project's main website, in the [Qubes Security Pack](/doc/security-pack/), and in the archives of the project's [developer](https://groups.google.com/forum/#!msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ) and [user](https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ) mailing lists.
There should also be a copy of this key at the project's main website, in the
[Qubes Security Pack], and in the archives of the project's
[developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
Once you have obtained the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)), you should verify the fingerprint of this key very carefully by obtaining copies of the fingerprint from trustworthy independent sources and comparing them to the downloaded key's fingerprint to ensure they match. Then set its trust level to "ultimate" (oh, well), so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key:
Once you have obtained the Qubes Master Signing Key,
you should verify the fingerprint of this key very carefully by obtaining
copies of the fingerprint from trustworthy independent sources and comparing
them to the downloaded key's fingerprint to ensure they match. Then set its
trust level to "ultimate" (oh, well), so that it can be used to automatically
verify all the keys signed by the Qubes Master Signing Key:
$ gpg --edit-key 0x36879494
@ -96,9 +137,11 @@ Once you have obtained the Qubes Master Signing Key ([`0x36879494`](https://keys
gpg> q
Now you can easily download any of the developer or release signing keys that happen to be used to sign particular ISO, RPM, TGZ files or git tags.
Now you can easily download any of the developer or release signing keys that
happen to be used to sign particular ISO, RPM, TGZ files or git tags.
For example: Qubes OS Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) is used for all Release 3 ISO images.
For example, the Qubes OS [Release 3 Signing Key] (`0xCB11CA1D03FA5082`) is
used for all Release 3 ISO images:
$ gpg --recv-keys 0xC52261BE0A823221D94CA1D1CB11CA1D03FA5082
gpg: requesting key 03FA5082 from hkp server keys.gnupg.net
@ -109,20 +152,27 @@ For example: Qubes OS Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-o
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
You can also download all the currently used developers' signing keys and current and older release signing keys (and also a copy of the Qubes Master Signing Key) from the [keys directory on our server](https://keys.qubes-os.org/keys/) and from the [Qubes Security Pack](/doc/security-pack/).
You can also download all the currently used developers' signing keys and
current and older release signing keys (and also a copy of the Qubes Master
Signing Key) from the [Qubes OS Keyserver] and from the [Qubes Security Pack].
The developer signing keys are set to be valid for 1 year only, while the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)) has no expiration date. This latter key was generated and is kept only within a dedicated, air-gapped "vault" machine, and the private portion will (hopefully) never leave this isolated machine.
The developer signing keys are set to be valid for 1 year only, while the Qubes
Master Signing Key has no expiration date. This latter key was generated and is
kept only within a dedicated, air-gapped "vault" machine, and the private
portion will (hopefully) never leave this isolated machine.
You can now verify the ISO image (`Qubes-R3.1-x86_64.iso`) matches its signature (`Qubes-R3.1-x86_64.iso.asc`):
You can now verify the ISO image (`Qubes-R3.2-x86_64.iso`) matches its
signature (`Qubes-R3.2-x86_64.iso.asc`):
$ gpg -v --verify Qubes-R3.1-x86_64.iso.asc Qubes-R3.1-x86_64.iso
$ gpg -v --verify Qubes-R3.2-x86_64.iso.asc Qubes-R3.2-x86_64.iso
gpg: armor header: Version: GnuPG v1
gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release 3 Signing Key"
gpg: binary signature, digest algorithm SHA256
The Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc)) used to sign this ISO image should be signed by the Qubes Master Signing Key ([`0x36879494`](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)):
The Release 3 Signing Key used to sign this ISO image should be signed by the
Qubes Master Signing Key:
$ gpg --list-sig 03FA5082
pub 4096R/03FA5082 2014-11-19
@ -130,72 +180,125 @@ The Release 3 Signing Key ([`0x03FA5082`](https://keys.qubes-os.org/keys/qubes-r
sig 3 03FA5082 2014-11-19 Qubes OS Release 3 Signing Key
sig 36879494 2014-11-19 Qubes Master Signing Key
Having problems verifying the ISO images? Make sure you have the corresponding release signing key and see this thread:
[https://groups.google.com/group/qubes-devel/browse\_thread/thread/4bdec1cd19509b38/9f8e219c41e1b232](https://groups.google.com/group/qubes-devel/browse_thread/thread/4bdec1cd19509b38/9f8e219c41e1b232)
Verifying Digests
-----------------
Each ISO is accompanied by a plain text file ending in `.DIGESTS`. This file contains the output of running several different crytographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests." For example, `Qubes-R3.1-x86_64.iso` is accompanied by `Qubes-R3.1-x86_64.iso.DIGESTS` which has the following content:
Each ISO is also accompanied by a plain text file ending in `.DIGESTS`. This
file contains the output of running several different crytographic hash
functions on the ISO in order to obtain alphanumeric outputs known as "digests"
or "hash values." These hash values are provided as an alternative verification
method to PGP signatures (though the `.DIGESTS` file is itself also PGP-signed
--- see below). If you've already verified the signatures on the ISO directly,
then verifying digests is not necessary. You can always find all the `.DIGESTS`
files for every Qubes ISO in the [Qubes Security Pack].
As an example, `Qubes-R3.2-x86_64.iso` is accompanied by
`Qubes-R3.2-x86_64.iso.DIGESTS` which has the following content:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
f99634b05d15f6bb2ac02ee03e4338a0 *Qubes-R3.1-x86_64.iso
990b7765ee209b42b3cad78673463daae769c729 *Qubes-R3.1-x86_64.iso
2d82a684d507ad5789ed83272af4311fd04375e782364d5dd9df4b3d7118cc28 *Qubes-R3.1-x86_64.iso
083d6cfc3fb5dc97fd91d8f9f70301c154e3674114ff1727b0415c2c663b233c22e0830d0bfc1f7a532549d7e39c6ef5cfde6a90a650343b47ba57d3e8e92ca7 *Qubes-R3.1-x86_64.iso
3c951138b8b9867d8657f173c1b58b82 *Qubes-R3.2-x86_64.iso
1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-R3.2-x86_64.iso
6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-R3.2-x86_64.iso
de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-R3.2-x86_64.iso
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAEBCAAGBQJW4AqUAAoJEMsRyh0D+lCCo+cP/A/96SmGSPmnMxIor0ODsZNh
HtGCfFPhB2KnpLMOVUMRidoMWTzL1+J7HpWYdOS7hPhlcbDfX4A0C4QCs4b0Wkc7
npha/GabQuek0HSi2uKt2YQtADq9yPjpqhc3Q2crbnL9UPmKv/XdECfpnK9zSRAE
RKl7Uj5RAPuLQ7ee4uQ8lIXWUm6IljpHnm4cG+WP2QYLCkS8BWq18Bl9s0fKdj47
JzIkhpyc6Vr9a7UBBxghF+Cb9WrPy22sTtE7eQYHRibh38xdMPOw0tb9F6AMAVeC
hK6+xJVz+7xERtRWTQPk4LOPeHIU21xJyVipkwb+T0SrQgsNwSXsSGPe0PiNU9Xk
khMbKGcbA+rnQiCS/9EKORNyULRAHvD6WXUqNyIS9trhcx49fxU8taPXKze947p1
XvWbqBWHIcCvKVQ3t/okmNN7OXfUCIDJ9bx+qyoLsIU2BF/aZZv+5ijK26D3H+xQ
G+2DMIynDMOlHSioCM3I1M0Ml5sB21G0VMJF9r9r8RrDop5cVGdgksie0JvpZ/ep
N/L7ozf1gvrO2euVslelMOUJcBjeisT214g6/DNjQ9Ox5SkDWIXrS2ZtR/zToApg
x3T0IusOQQhdpC8I0nnXPL/tgyRV8UFNBhxIec7IKnGwvQlVYMFYVomPh7vJhfdl
GMMP3JlFAaxghZWU14+F
=FiJ5
Version: GnuPG v2
iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
3N/6YZw1gSuvBlTquP27
=e9oD
-----END PGP SIGNATURE-----
Four digests have been computed for this ISO. The hash functions used, in order
from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that
the ISO you downloaded matches any of these hash values is by using the
respective `*sum` programs:
Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that the ISO you downloaded matches any of these is by using `openssl` from the command line:
$ md5sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
md5sum: WARNING: 23 lines are improperly formatted
$ sha1sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
sha1sum: WARNING: 23 lines are improperly formatted
$ sha256sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
sha256sum: WARNING: 23 lines are improperly formatted
$ sha512sum -c Qubes-R3.2-x86_64.iso.DIGESTS
Qubes-R3.2-x86_64.iso: OK
sha512sum: WARNING: 23 lines are improperly formatted
$ openssl dgst -md5 Qubes-R3.1-x86_64.iso
MD5(Qubes-R3.1-x86_64.iso)= f99634b05d15f6bb2ac02ee03e4338a0
$ openssl dgst -sha1 Qubes-R3.1-x86_64.iso
SHA1(Qubes-R3.1-x86_64.iso)= 990b7765ee209b42b3cad78673463daae769c729
$ openssl dgst -sha256 Qubes-R3.1-x86_64.iso
SHA256(Qubes-R3.1-x86_64.iso)= 2d82a684d507ad5789ed83272af4311fd04375e782364d5dd9df4b3d7118cc28
$ openssl dgst -sha512 Qubes-R3.1-x86_64.iso
SHA512(Qubes-R3.1-x86_64.iso)=
083d6cfc3fb5dc97fd91d8f9f70301c154e3674114ff1727b0415c2c663b233c22e0830d0bfc1f7a532549d7e39c6ef5cfde6a90a650343b47ba57d3e8e92ca7
The `OK` response tells us that the hash value for that particular hash
function matches. The program also warns us that there are 23 improperly
formatted lines, but this is to be expected. This is because each file contains
lines for several different hash values (as mentioned above), but each `*sum`
program verifies only the line for its own hash function. In addition, there
are lines for the PGP signature which the `*sum` programs do not know how to
read.
Another way is to use `openssl` to compute each hash value, then compare them
to the contents of the `.DIGESTS` file.:
$ openssl dgst -md5 Qubes-R3.2-x86_64.iso
MD5(Qubes-R3.2-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
$ openssl dgst -sha1 Qubes-R3.2-x86_64.iso
SHA1(Qubes-R3.2-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
$ openssl dgst -sha256 Qubes-R3.2-x86_64.iso
SHA256(Qubes-R3.2-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
$ openssl dgst -sha512 Qubes-R3.2-x86_64.iso
SHA512(Qubes-R3.2-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
(Notice that the outputs match the values from the `.DIGESTS` file.)
However, it is possible that an attacker replaced `Qubes-R3.1-x86_64.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-R3.1-x86_64.iso.DIGESTS` with his own set of values. Therefore, ideally, we should also verify the authenticity of the listed hash values. Since `Qubes-R3.1-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use `gpg` to verify it from the command line:
However, it is possible that an attacker replaced `Qubes-R3.2-x86_64.iso` with
a malicious ISO, computed the hash values for that ISO, and replaced the values
in `Qubes-R3.2-x86_64.iso.DIGESTS` with his own set of values. Therefore,
ideally, we should also verify the authenticity of the listed hash values.
Since `Qubes-R3.2-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use
`gpg` to verify it from the command line:
$ gpg -v --verify Qubes-R3.1-x86_64.iso.DIGESTS
$ gpg -v --verify Qubes-R3.2-x86_64.iso.DIGESTS
gpg: armor header: Hash: SHA256
gpg: armor header: Version: GnuPG v1
gpg: armor header: Version: GnuPG v2
gpg: original file name=''
gpg: Signature made Wed 09 Mar 2016 03:35:48 AM PST using RSA key ID 03FA5082
gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release 3 Signing Key"
gpg: textmode signature, digest algorithm SHA256
The signature is good. Assuming our copy of the `Qubes OS Release 3 Signing Key` is also authentic (see above), we can be confident that these hash values came from the Qubes devs.
The signature is good. Assuming our copy of the `Qubes OS Release 3 Signing
Key` is also authentic (see above), we can be confident that these hash values
came from the Qubes devs.
Verifying Qubes Code
--------------------
Developers who fetch code from our Git server should always verify tags on the latest commit. Any commits that are not followed by a signed tag should not be trusted!
Developers who fetch code from our Git server should always verify tags on the
latest commit. Any commits that are not followed by a signed tag should not be
trusted!
To verify a signature on a git tag, you can use:
$ git tag -v <tag name>
[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
[keyserver]: https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples
[Qubes Security Pack]: /doc/security-pack/
[devel-master-key-msg]: https://groups.google.com/d/msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ
[user-master-key-msg]: https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ
[mailing lists]: /mailing-lists/
[Release 3 Signing Key]: https://keys.qubes-os.org/keys/qubes-release-3-signing-key.asc
[Qubes OS Keyserver]: https://keys.qubes-os.org/keys/

115
managing-os/hvm.md
View File

@ -15,20 +15,20 @@ Creating and using HVM (fully virtualized) domains
What are HVM domains?
---------------------
HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow to create domains based on any OS, if one only has its installation ISO. E.g. this allows to have Windows-based VMs in Qubes.
HVM domains (Hardware VM), in contrast to PV domains (Paravirtualized domains), allow one to create domains based on any OS for which one has an installation ISO. For example, this allows one to have Windows-based VMs in Qubes.
Interested readers might want to check [this article](http://theinvisiblethings.blogspot.com/2012/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linuxed-based PV domains).
Interested readers might want to check [this article](http://theinvisiblethings.blogspot.com/2012/03/windows-support-coming-to-qubes.html) to learn why it took so long for Qubes OS to support HVM domains (Qubes 1 only supported Linux based PV domains).
Creating an HVM domain
----------------------
First, lets create a new HVM domain (use the --hvm switch to qvm-create, or choose HVM type in the Qubes Manager VM creation dialog box):
First, lets create a new HVM domain. Use the --hvm switch to qvm-create, or choose HVM type in the Qubes Manager VM creation dialog box:
~~~
qvm-create win7 --hvm --label green
~~~
(Of course, the name of the domain ("win7"), as well as it's label ("green"), are just exemplary).
(The name of the domain ("win7") as well as it's label ("green") are just exemplary of course).
If you receive an error like this one, then you must first enable VT-x in your BIOS:
@ -36,72 +36,141 @@ If you receive an error like this one, then you must first enable VT-x in your B
libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64
~~~
Now, we need to install an OS inside this VM, this can done by attaching an installation ISO upon starting the VM (this currently can be done only from command line, but in the future we surely will added an option to do this also from the manager):
Now we need to install an OS inside this VM. This can done by attaching an installation ISO to and starting the VM (this can currently only be done from command line, but in the future we will surely add an option to do this also from the manager):
~~~
qvm-start win7 --cdrom=/usr/local/iso/win7_en.iso
~~~
The command above assumes the installation ISO was somehow transferred to Dom0, e.g. copied using `dd` command from an installation CDROM. If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`:
The above command assumes the installation ISO was transferred to Dom0 (copied using `dd` command from an installation CDROM for example). If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`:
~~~
qvm-start win7 --cdrom=/dev/cdrom
~~~
Now, the VM will start booting from the attached CDROM device, which in the example above just happens to be the Windows 7 installation disk. Depending on the OS that is being installed in the VM, one might be required to start the VM several times (as is the case e.g. with Windows 7 installation), because whenever the installer wants to "reboot the system", it actually shutdowns the VM (and Qubes won't automatically start it), so several invocations of qvm-start command (as shown above) might be needed.
Next the VM will start booting from the attached CDROM device (which in the example above just happens to be a Windows 7 installation disk). Depending on the OS that is being installed in the VM one might be required to start the VM several times (as is the case with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shutdowns the VM and Qubes won't automatically start it. Several invocations of qvm-start command (as shown above) might be needed.
[![r2b1-win7-installing.png](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing.png)
Using Installation ISOs located in other VMs
--------------------------------------------
Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. However, for security reasons, networking is disabled for Qubes Dom0, which makes it not possible to download an ISO within Dom0. Also Qubes do not provide any (easy to use) mechanisms for copying files between AppVMs and Dom0, and generally tries to discourage such actions. So, it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. And the good news is that this is indeed not required -- one can use the following syntax when specifying the location of /usr/local/iso/win7\_en.iso the installation ISO:
Sometimes one wants to download the installation ISO from the Web and use it for HVM creation. For security reasons, networking is disabled for Qubes Dom0, which makes it impossible to download an ISO within Dom0. Qubes also does not provide any easy to use mechanisms for copying files between AppVMs and Dom0 and generally tries to discourage such actions. Due to these factors it would be inconvenient to require that the installation ISO for an HVM domain be always located in Dom0. The good news, however, is that this is indeed not required. One can use the following syntax when specifying the location of an installation ISO (such as the Windows 7 installation ISO):
~~~
--cdrom=[appvm]:[/path/to/iso/within/appvm]
~~~
Assuming e.g. the an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM, and located within `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM and use this ISO as an installation media with the following command (issued in Dom0, of course):
Assuming that an installation ISO named `ubuntu-12.10-desktop-i386.iso` has been downloaded in `work-web` AppVM and is located within the `/home/user/Downloads` directory within this AppVM, one can immediately create a new HVM using this ISO as an installation media with the following command issued in Dom0:
~~~
qvm-create --hvm ubuntu --label red
qvm-start ubuntu --cdrom=work-web:/home/user/Downloads/ubuntu-12.10-desktop-i386.iso
~~~
Of course the AppVM where the ISO is kept must also be running for this to work (this VM is now serving the ISO and acting as a disk backend).
The AppVM where the ISO is kept must be running for this to work as this VM is now serving the ISO and acting as a disk backend.
![r2b1-installing-ubuntu-1.png](/attachment/wiki/HvmCreate/r2b1-installing-ubuntu-1.png)
Converting VirtualBox VM to HVM
-------------------------------
Microsoft provides [free 90 day evaluation VirtualBox VMs for browser testing](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/).
About 60 GB of disk space is required for conversion, use external harddrive if needed. Final root.img size is 40 GB.
In Debian AppVM, install qemu-utils and unzip:
~~~
sudo apt install qemu-utils unzip
~~~
Unzip VirtualBox zip file:
~~~
unzip *.zip
~~~
Extract OVA tar archive:
~~~
tar -xvf *.ova
~~~
Convert vmdk to raw:
~~~
qemu-img convert -O raw *.vmdk win10.raw
~~~
Create new HVM in Dom0, with amount of RAM in MB you wish:
~~~
qvm-create --hvm win10 --label red --mem=4096
~~~
Copy file to Dom0:
~~~
qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /var/lib/qubes/appvms/win10/root.img
~~~
Start win10 VM:
~~~
qvm-start win10
~~~
**Optional ways to get more information**
Filetype of OVA file:
~~~
file *.ova
~~~
List files of OVA tar archive:
~~~
tar -tf *.ova
~~~
List filetypes supported by qemu-img:
~~~
qemu-img -h | tail -n1
~~~
Setting up networking for HVM domains
-------------------------------------
Just like standard (paravirtualized) AppVMs, the HVM domains got fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts, running within each AppVM, are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html).
Just like standard paravirtualized AppVMs, the HVM domains get fixed IP addresses centrally assigned by Qubes. Normally Qubes agent scripts running within each AppVM are responsible for setting up networking within the VM according the configuration created by Qubes. Such centrally managed networking infrastructure allows for [advanced networking configuration](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html).
However, a generic HVM domain, e.g. a standard Windows or Ubuntu installation, has (at least initially) no Qubes agent scripts running inside it, and thus requires manual networking configuration, so that it match the values assigned by Qubes for this domain.
A generic HVM domain such as a standard Windows or Ubuntu installation, however, has no Qubes agent scripts running inside it initially and thus requires manual networking configuration so that it match the values assigned by Qubes for this domain.
Even though we do have a small DHCP server (that runs inside HVM untrusted stub domain) to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers built in (but not Qubes tools) and which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm), and so our DHCP server is not useful.
Even though we do have a small DHCP server that runs inside HVM untrusted stub domain to make the manual network configuration not necessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers (but not Qubes tools) built in which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm). In this instance our DHCP server is not useful.
In order to manually configure networking in a VM, one should first find out the IP/netmask/gateway assigned to the particular VM by Qubes. This can be seen e.g. in the Qubes Manager in the VM's properties:
![r2b1-manager-networking-config.png](/attachment/wiki/HvmCreate/r2b1-manager-networking-config.png)
Alternatively, one can use `qvm-ls -n` command to obtain the same information.
Alternatively, one can use `qvm-ls -n` command to obtain the same information. One should configure the networking within the HVM according to those settings (IP/netmask/gateway). One should set DNS addresses to the same IP as gateway.
Now, one should configure the networking within the HVM according to those settings (IP/netmask/gateway). Only IPv4 networking is currently supported in Qubes. Set DNS address to the same IP as gateway.
Only IPv4 networking is currently supported in Qubes.
**Note:** If one plans on installing Qubes Tools for Windows guests (see below) it is 'not' necessary to configure networking manually as described in this section, because the tools will take care of setting the networking automatically for such Windows domains.
Using Template-based HVM domains
--------------------------------
TODO (Coming in Qubes R2 beta 3).
Please see our dedicated page on [installing and using Windows-based AppVMs](/doc/windows-appvms/).
Cloning HVM domains
-------------------
Just like normal AppVMs, the HVM domains can also be cloned, either using a command-line `qvm-clone` command, or via manager's 'Clone VM' option in the right-click menu.
Just like normal AppVMs, the HVM domains can also be cloned either using a command-line `qvm-clone` command or via manager's 'Clone VM' option in the right-click menu.
The cloned VM will get identical root and private image, and essentially will be identical to the original VM, except that it will get a different MAC address for the networking interface:
The cloned VM will get identical root and private image and will essentially be an identical of the original VM except that it will get a different MAC address for the networking interface:
~~~
[joanna@dom0 ~]$ qvm-prefs win7
@ -157,7 +226,7 @@ drive : None
timezone : localtime
~~~
Note how the MAC addresses differ between those two, otherwise identical VMs. Of course, the IP addresses, assigned by Qubes, will also be different, to allow networking to function properly:
Note how the MAC addresses differ between those two otherwise identical VMs. The IP addresses assigned by Qubes will also be different of course to allow networking to function properly:
~~~
[joanna@dom0 ~]$ qvm-ls -n
@ -167,7 +236,7 @@ Note how the MAC addresses differ between those two, otherwise identical VMs. Of
/.../
~~~
If, for any reason, one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM:
If for any reason one would like to make sure that the two VMs have the same MAC address, one can use qvm-prefs to set a fixed MAC address for the VM:
~~~
[joanna@dom0 ~]$ qvm-prefs win7-copy -s mac 00:16:3E:5E:6C:05
@ -196,10 +265,6 @@ drive : None
timezone : localtime
~~~
Please note that as of now Qubes does not support shared templates for HVM domains. This means that HVM domains cloned this way will have two separate copies of the whole filesystems. This has consequences in taking much more disk space compared to standard AppVMs that share the root fs with the Template VM. Another consequence is that it's probably not legal to clone a proprietary OS, such as Windows this way, unless your license specifically allows for that (even though Windows Activation won't complain when one sets identical MAC address for the cloned VMs, it's doubtful practice at best).
In the near future we plan on introducing shared template also for HVM domains, hopefully solving the problems described above.
Installing Qubes support tools in Windows 7 VMs
-----------------------------------------------
@ -210,7 +275,7 @@ Assigning PCI devices to HVM domains
HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs. E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc.
Once problem, however, at the moment, is that after the whole system gets suspend into S3 sleep, and subsequently resumed, such attached devices stop working and should be restarted within the VM. Under Windows this can be achieved by opening the Device Manager, selecting the actual device, such as a USB controller, and then first 'Disabling', and then 'Enabling' the device again. This is illustrated on the screenshot below:
One problem at the moment however, is that after the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working and should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again. This is illustrated on the screenshot below:
[![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)

39
managing-os/linux-hvm-tips.md
View File

@ -11,6 +11,45 @@ redirect_from:
Tips for Linux in HVM domain
============================
How to fix bootup kernel error
-------------------------------
This concerns the following:
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
This has been tested with Qubes `R3.2-RC3`. Note that the issue may be related
to the `bochs_drm` video driver. To fix this:
1. Edit the file `/etc/default/grub`.
2. Find the line which starts:
~~~
GRUB_CMDLINE_LINUX=
~~~
3. Remove this text from that line:
~~~
rhgb
~~~
4. Add this text to that line:
~~~
modprobe.blacklist=bochs_drm
~~~
5. Run this command:
~~~
grub2-mkconfig --output=/boot/grub2/grub.cfg
~~~
The HVM should no longer display the error if it's related to the `bochs_drm`
kernel driver.
Screen resolution
-----------------

30
managing-os/pentesting.md Normal file
View File

@ -0,0 +1,30 @@
---
layout: doc
title: Penetration Testing
permalink: /doc/pentesting/
---
**Legal notice:**
The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without such a permission can have legal consequences.
To avoid such legal conflicts please refer to the [EC-Council: Code of Ethics](https://www.eccouncil.org/Support/code-of-ethics).
Penetration Testing
===================
"A penetration test, informally pen test, is an attack on a computer system that looks for security weaknesses, potentially gaining access to the computer's features and data." (source [Penetration test](https://en.wikipedia.org/wiki/Penetration_test)).
Penetration Testing Distributions
---------------------------------
The following install instructions explain how to setup a penetration testing distribution within Qubes OS.
- [BlackArch](/doc/pentesting/blackarch/)
- [Kali](/doc/pentesting/kali/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
Using Qubes OS to host a "hacking" laboratory
---------------------------------------------
Qubes OS is a hypervisor based operating system. Qubes OS can host various operating systems such as Linux, Unix or Windows and run them in parallel. Qubes OS can therefor be used to host your own "hacking" laboratory.

96
managing-os/pentesting/blackarch.md Normal file
View File

@ -0,0 +1,96 @@
---
layout: doc
title: How to Create a BlackArch VM
permalink: /doc/pentesting/blackarch/
redirect_from:
- /doc/blackarch/
---
**General Remainder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool provider.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to Create a BlackArch VM
============================
[BlackArch](http://www.blackarch.org) Linux is an [Arch Linux](http://www.archlinux.org/)-based distribution for penetration testers and security researchers. The repository contains [1434](http://www.blackarch.org/tools.html) tools.
- List of [tools](http://www.blackarch.org/tools.html)
- [Installation Instructions](http://www.blackarch.org/downloads.html)
Create ArchLinux Based BlackArch Template
-----------------------------------------
1. Create ArchlLinux Template
- Follow the [Archlinux Template instructions](/doc/templates/archlinux/)
2. Update Template
sudo pacman -Syyu
3. Clone template
1. Via Qubes VM Manager
2. Via command line
qvm-clone archlinux blackarch
4. Install BlackArch repository
$ curl -O https://blackarch.org/strap.sh
# The SHA1 sum should match: 86eb4efb68918dbfdd1e22862a48fda20a8145ff
$ sha1sum strap.sh
# Set execute bit
$ chmod +x strap.sh
# Run strap.sh
$ sudo ./strap.sh
5. Install tools
- install all tools
sudo pacman -S blackarch
- or by category:
# list available categories
pacman -Sg | grep blackarch
# install category
sudo pacman -S blackarch-<category>
# example
sudo pacman -S blackarch-forensic
- or specific tool
# Search for tool
pacman -Ss <tool-name>
# Install tool
sudo pacman -S <tool-name>
# Example
pacman -Ss burpsuite
sudo pacman -S burpsuite
6. Create a AppVMs based on the `blackarch` template
- (Optional) Attach necessary devices
Alternative Options to BlackArch
--------------------------------
- [Kali](/doc/pentesting/kali/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
- [Pentesting](/doc/pentesting/)

202
managing-os/pentesting/kali.md Normal file
View File

@ -0,0 +1,202 @@
---
layout: doc
title: How to create a Kali Linux VM
permalink: /doc/pentesting/kali/
redirect_from:
- /doc/kali/
---
**General Remainder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool provider.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to Create a Kali Linux VM
=============================
This guide is being created to give guidance on ways in which you could create a [Kali Linux](https://www.kali.org/) penetration testing VM (Qube) in Qubes OS.
Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM. One way is to create a HVM and use the offical ISO to install the system or convert a [Virtual Image](https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/). Another way is to clone the Qubes OS Debian image and turn it into a Kali Linux distribution.
Kali Linux HVM
--------------
1. Download the Kali installation DVD
2. Create a new HVM
3. Start the HVM with attached CD/DVD
qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
Create Debian Based Kali Template
---------------------------------
1. *(Optional)* Install `debian-8` template (if not already installed)
2. Update your `debian-8` template
sudo apt-get update
sudo apt-get dist-upgrade
3. Clone `debian-8` template (two options)
1. Via Qubes VM Manager
![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png)
2. Via command line
qvm-clone debian-8 kali
4. Start and upgrade the `kali` Template from Debian 8 to Debian 9
sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list
sudo sed -i 's/jessie/stretch/g' /etc/apt/sources.list.d/qubes-r3.list
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get autoremove
**Note:** From now on there are two possible ways either doing everything manually or automatically with [Katoolin](https://github.com/LionSec/katoolin).
Katoolin is a script (written in Python) which helps you to install Kali tools.
5. *manually* - Add Kali Linux repositories
1. Add Kali Linux repositories to `/etc/apt/sources.list`
deb http://http.kali.org/kali kali-rolling main contrib non-free
deb http://repo.kali.org/kali kali-bleeding-edge main
2. Add kali signing key
- The signing key can be found here [Download Kali Linux Images Securely](https://www.kali.org/downloads/)
sudo apt-key adv --keyserver hkp://keys.gnupg.net --recv-keys 7D8D0BF6
sudo apt-get update
6. *katoolin* - Install Katoolin and add Kali Linux repositories
1. Install Katoolin
sudo apt-get install git
git clone https://github.com/LionSec/katoolin.git
sudo cp katoolin/katoolin.py /usr/bin/katoolin
sudo chmod +x /usr/bin/katoolin
rm -rf katoolin
2. Add Kali Linux repositories
- start katoolin
sudo katoolin
- select 'Add Kali repositories & Update'
1) Add Kali repositories & Update
2) View Categories
3) Install classicmenu indicator
4) Install Kali menu
5) Help
kat > 1
![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png)
- select 'Add kali linux repositories'
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 1
![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png)
- update Kali repositories
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 2
- quit katoolin by pressing `CRTL` + `c` keys
What do you want to do ?> ^CShutdown requested...Goodbye...
7. Cleanup and update `kali` template
sudo apt-get dist-upgrade
sudo apt-get autoremove
8. Shutdown and trim `kali` template
- Shutdown `kali` template
sudo shutdown -h now
- In `dom0` console:
qvm-trim-template kali
9. Start image
10. *manually* - Install tools
**Warning:** `kali-linux` and `kali-linux-full` does currently not work properly. Please use `Katoolin` or `PTF`.
1. List available packages
sudo apt-cache search kali-linux
2. Select and install tools
- install base system
sudo apt-get install kali-linux
- or install all tools
sudo apt-get install kali-linux-full
- or select specific (example):
sudo apt-get install kali-linux-top10 kali-linux-web
11. *katoolin* - Install tools
1. View Categories
- start katoolin
sudo katoolin
- select `2) View Categories`
2. Select the categories/tools you want to install
- For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu](http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/)
- **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`.
12. Create a AppVMs based on the `kali` template
- (Optional) Attach necessary devices
Alternative Options to Kali
---------------------------
- [BlackArch](/doc/pentesting/blackarch/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
- [Pentesting](/doc/pentesting/)

121
managing-os/pentesting/ptf.md Normal file
View File

@ -0,0 +1,121 @@
---
layout: doc
title: How to create Penetration Testers Framework (PTF) VM
permalink: /doc/pentesting/ptf/
redirect_from:
- /doc/ptf/
---
**General Remainder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool provider.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to create Penetration Testers Framework (PTF) VM
====================================================
"The PenTesters Framework (PTF) is a Python script designed for Debian/Ubuntu/ArchLinux based distributions to create a similar and familiar distribution for Penetration Testing.
PTF attempts to install all of your penetration testing tools (latest and greatest), compile them, build them, and make it so that you can install/update your distribution on any machine." (source [PTF Readme](https://github.com/trustedsec/ptf/blob/master/README.md))
**Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for examples requires a newer Ruby version than Debian 8 has in the repositories. Therefor the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools.
Create Debian Based Penetration Testers Framework (PTF) Template
----------------------------------------------------------------
1. Create PTF template
1. Follow [Create Debian Based Kali Template](/doc/pentesting/kali/) till step 7.
2. (Optional) Rename the cloned template to `ptf`
2. Download PTF
sudo apt-get install git
cd /opt
sudo git clone https://github.com/trustedsec/ptf.git
- (Optional) Configure PTF
1. Go to configuration directory
cd /opt/ptf/config
2. Edit the configuration file
for example by using vim:
sudo vim ptf.config
the configuration options are described in the `ptf.config` file
3. Install PTF
cd /opt/ptf
sudo ./ptf
**Note:** the config file has to be in the same directory as the executable. It is not
possible to do sudo ptf/ptf
PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on.
4. Install/Update modules (tools)
1. Start PTF
sudo ptf
![PTF start banner](/attachment/wiki/PTF/ptf-banner.png)
2. Show available modules (tools)
ptf> show modules
3. Install/Update modules (all/)
- Install/Update all tools
ptf> use modules/install_update_all
- or by category Install/Update
ptf> use modules/code-audit/install_update_all
- or individually (example Metasploit)
1. Search for module
ptf> search metasploit
[*] Search results below:
modules/exploitation/metasploit
2. Use module
ptf> use modules/exploitation/metasploit
ptf:(modules/exploitation/metasploit)>
3. Install module
ptf:(modules/exploitation/metasploit)>install
4. Run Metasploit
ptf:(modules/exploitation/metasploit)>exit
ptf> quit
[*] Exiting PTF - the easy pentest platform creation framework.
sudo msfconsole
5. Create a AppVMs based on the `ptf` template
- (Optional) Attach necessary devices
Alternative Options to PTF
--------------------------
- [BlackArch](/doc/pentesting/blackarch/)
- [Kali](/doc/pentesting/kali/)
- [Pentesting](/doc/pentesting/)

39
managing-os/reinstall-template.md
View File

@ -9,12 +9,39 @@ redirect_from:
How to Reinstall a TemplateVM
=============================
If you suspect your [TemplateVM] is broken, misconfigured, or compromised,
or if you wish to do a clean reinstall in order to upgrade to a new version, you
can reinstall any TemplateVM from the Qubes repository. In what follows, the
phrase "target TemplateVM" refers to whichever TemplateVM you want to reinsatll.
If you want to reinstall more than one TemplateVM, repeat these instructions for
each one.
If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you
can reinstall any TemplateVM that was installed from the Qubes repository.
Starting in Qubes 3.1, the process is greatly simplified.
First, copy any files that you wish to keep from the TemplateVM's `/home` and
`/rw` folders to a safe storage location. Then, in a dom0 terminal, run:
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
Replace `qubes-template-package-name` with the name of the *package* of the
template you wish to reinstall. For example, use `qubes-template-fedora-24` if
you wish to reinstall the `fedora-24` template. Only one template can be
reinstalled at a time.
**Reminder:** If you're trying to reinstall a template that is not in an enabled
repo, you must enable that repo. For example:
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
**Note:** VMs that are using the reinstalled template will not be affected until they are
restarted.
Manual Reinstallation Method
----------------------------
If you're using Qubes 3.0 or older, you should use the manual reinstallation
method. You can also use this method on later Qubes versions if, for any reason,
you want to reinstall a template manually.
In what follows, the term "target TemplateVM" refers to whichever TemplateVM you
want to reinstall. If you want to reinstall more than one TemplateVM, repeat
these instructions for each one.
1. (Optional) Clone the existing target TemplateVM.

21
managing-os/templates.md
View File

@ -17,7 +17,7 @@ TemplateBasedVMs is installed. The default template is based on Fedora,
but there are additional templates based on other Linux distributions. There
are also templates available with or without certain software preinstalled. The
concept of TemplateVMs is initially described
[here](/doc/getting-started/#appvms-domains-and-templatevms). The technical
[here](/getting-started/#appvms-qubes-and-templatevms). The technical
details of this implementation are described in the developer documentation
[here](/doc/template-implementation/).
@ -85,14 +85,25 @@ Important Notes
update a template from dom0 (and thereby lose any user modifications in the
existing template), you must first uninstall the existing template from dom0:
$ sudo yum remove qubes-template-fedora-23
$ sudo yum remove qubes-template-fedora-24
* Standalone VMs using Template VMs as a basis can be created easily. These
VMs receive a *copy* of the operating system and do not get automatically
updated when Template VMs are updated--they must be updated individually.
* Template VMs can occupy more space on the dom0 filesystem than necessary
because they cannot employ automatic TRIM/discard on the root fs. The
`qvm-trim-template` command in dom0 is used to recover this unused space.
Conversely, the root filesystems in Standalone VMs *can* employ
TRIM/discard on the root fs using normal tools and configuration options.
* On XFCE based Dom0, a manual action may be required to remove the "Start Menu"
sub-menu of the removed TemplateVM. For example, to remove a dangling sub-menu
for a removed "fedora-21" template, open a Dom0 Terminal and type:
for a removed "fedora-24" template, open a Dom0 Terminal and type:
$ sudo rm ~/.local/share/applications/fedora-21-*
$ sudo rm ~/.local/share/applications/fedora-24-*
Just make sure there are no other TemplateVMs whose names start with "fedora-21"
Just make sure there are no other TemplateVMs whose names start with "fedora-24"
or else their menu items will be removed too.

64
managing-os/templates/archlinux.md
View File

@ -23,7 +23,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
## Instructions ##
<br>
**These are the instructions for Qubes 3.1. They will take you step by step thru the entire process start to finish**
**These are the instructions for Qubes 3.2. They will take you step by step through the entire process start to finish**
*Note: Currently there are no binary packages and it must be compiled from source using the instructions below.*
@ -80,15 +80,17 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* python-sh
* dailog
* dialog
* rpm-sign
* gnupg
<br>
* The tools can usually be installed all together with the following terminal command string:
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign**
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign gnupg**
<br>
<br>
![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png)
@ -98,19 +100,19 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
##### **4: Installing the "Qubes Automated Build System":** #####
* To get the most current build system its best to use marmarek's git repository.
* Download the latest stable qubes-builder repository:
* $ **git clone https://github.com/marmarek/qubes-builder.git**
* $ **git clone https://github.com/QubesOS/qubes-builder.git**
<br>
<br>
![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png)
<br>
<br>
* You will now have the Qubes Builder System environment installed in the directory below:
* **/home/user/qubes-builder**
<br>
* You will now have the Qubes Builder System environment installed in the directory below:
* **/home/user/qubes-builder/**
<br>
<br>
@ -120,11 +122,11 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
*In the future this should not be needed once a change is made to the 'setup' script.*
* Edit the '**qubes-os-r3.1.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice.
* Edit the '**qubes-os-r3.2.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice.
* **$ cd /home/user/qubes-builder/example-config/**
* **$ nano -W qubes-os-r3.1.conf** or **$ gedit qubes-os-r3.1.conf** or etc….
* **$ nano -W qubes-os-r3.2.conf** or **$ gedit qubes-os-r3.2.conf** or etc….
<br>
<br>
![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png)
@ -172,7 +174,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* This screen will give you the choice of which Qubes Release to build the template for.
* Select '**Qubes Release 3.1**'
* Select '**Qubes Release 3.2**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
@ -185,6 +187,9 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Select 'QubesOS/qubes- Stable - Default Repo'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
<br>
<br>
* Screen "**Build Template Only?**"
@ -192,7 +197,7 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12a.png)
<br>
<br>
@ -200,9 +205,9 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Deselect '**Fedora**'
* Deselect '**mgnt_salt**'
* Deselect '**mgmt_salt**'
* Select '**archlinux**'
* Select '**builder-archlinux**'
* Select '**OK**' Press **Enter**
<br>
@ -213,10 +218,18 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s.
* Select '**No**' Press '**Enter**'
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png)
<br>
<br>
* Then wait for download to finish and press '**OK**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png)
<br>
<br>
* Screen '**Template Distribution Selection**' allows you to choose the actual template/s you wish to build.
@ -237,19 +250,6 @@ Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
<br>
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png)
<br>
<br>
* Archlinux builder is not(yet?) in official Qubes release branch, so it has to be downloaded from different repository.
* Open file builder.conf with your favourite text editor and find section **"O V E R R I D E B R A N C H"** (single space
between letters) and add:
* **GIT_URL_builder_archlinux = $(GIT_BASEURL)/marmarek/qubes-builder-archlinux.git**
<br>
<br>
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17a.png)
<br>
<br>
<br>
##### **7: Install all the dependencies:** #####
@ -388,7 +388,7 @@ Please check out:
[XYNE's (dev) Powerpill](http://xyne.archlinux.ca/projects/powerpill/)
**Important Note:** Until Powerpill is configured you will have to open network access to the template to get the initial packages etc downloaded. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services thru the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access)
**Important Note:** Until Powerpill is configured you will have to open network access to the template to get the initial packages etc downloaded. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services through the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access)
<br>
<br>
@ -676,9 +676,9 @@ Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux.
* There May also be a similar issue of dependencies with Xorg.
* Upgrade Relfector functionality to allow its use thru the QUPS
* Upgrade Relfector functionality to allow its use through the QUPS
* Pacman functionality changes and allows it to be directly configured to work thru QUPS.
* Pacman functionality changes and allows it to be directly configured to work through QUPS.
<br>
@ -694,6 +694,6 @@ Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux.
* [How can I contribute to the Qubes Project?](/doc/contributing/)
* [Guidelines for Documentation Contributors](doc/doc-guidelines/)
* [Guidelines for Documentation Contributors](/doc/doc-guidelines/)
<br>

9
managing-os/templates/debian.md
View File

@ -34,14 +34,10 @@ Debian 7 (wheezy) - old stable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-7
(The download will take a while, and there will be no progress indicator.)
Debian 8 (jessie) - stable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-8
(The download will take a while, and there will be no progress indicator.)
Debian 9 (stretch) - testing:
A prebuilt template is not yet available, but there are two options for
@ -59,3 +55,8 @@ Known issues
------------
If you want to help in improving the template, feel free to [contribute](/wiki/ContributingHowto).
More information
----------------
* [Debian wiki](https://wiki.debian.org/Qubes)

17
managing-os/debian-template-upgrade-8.md → managing-os/templates/debian/upgrade-8-to-9.md
View File

@ -1,8 +1,9 @@
---
layout: doc
title: Upgrading the Debian 8 Template
permalink: /doc/debian-template-upgrade-8/
title: Upgrading the Debian 8 Template to Debian 9
permalink: /doc/template/debian/upgrade-8-to-9/
redirect_from:
- /doc/debian-template-upgrade-8/
- /en/doc/debian-template-upgrade-8/
- /doc/DebianTemplateUpgrade8/
- /wiki/DebianTemplateUpgrade8/
@ -13,8 +14,10 @@ Upgrading the Debian 8 Template
Disclaimer: Debian 9 (Stretch) is marked testing for a reason. You may notice stability problems when using it.
Summary: Upgrading the Standard Debian 8 Template to Debian 9
-------------------------------------------------------------
Please note that if you installed packages from one of the testing repositories you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r3.list` before attempting the upgrade. Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
Summary: Upgrading a Debian 8 Template to Debian 9
--------------------------------------------------
[user@dom0 ~]$ qvm-clone debian-8 debian-9
[user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal
@ -78,7 +81,7 @@ any template based on the standard Debian 8 template.
Compacting the Upgraded Template
================================
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
@ -110,7 +113,7 @@ TemplateVM's max size + the actually used space there) free space in dom0.
[user@dom0 ~]$ mv root.img.new root.img
Additional Information
======================
----------------------
It should be noted that Debian 9 (Stretch) is currently marked testing and
should be treat as such. For projects that need absolute stability, upgrading
@ -124,4 +127,4 @@ Relevant Mailing List Discussions
---------------------------------
* [Stretch Template Installation](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/4rdayBF_UTc)
* [Stretch availability in 3.2](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/cekPfBqQMOI)
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)

115
managing-os/templates/fedora-minimal.md
View File

@ -12,71 +12,64 @@ redirect_from:
Fedora - minimal
================
The template weighs only about 300MB and has most of the stuff cut off, except for minimal X and xterm. It is really just a barebone and not even usable in this form - but you can customize it to meet your needs. You can find some usage examples in the section below.
The template only weighs about 300 MB and has only the most vital packages installed, including a minimal X and xterm installation.
The minimal template, however, can be easily extended to fit your requirements. The sections below contain the instructions on duplicating the template and provide some examples for commonly desired use cases.
Installation
------------
The Fedora minimal template can be installed with the following command:
Install
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-24-minimal
~~~
The download may take a while depending on your connection speed.
Duplication and first steps
---------------------------
It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name.
~~~
[user@dom0 ~]$ qvm-clone fedora-24-minimal your-new-clone
~~~
You must start the template in order to customize it.
A recommended first step is to install the `sudo` package, which is not installed by default in the minimal template:
~~~
[user@your-new-clone ~]$ su -
[user@your-new-clone ~]$ dnf install sudo
~~~
Customization
-------------
Customizing the template for specific use cases normally only requires installing additional packages.
The following table provides an overview of which packages are needed for which purpose.
As expected, the required packages are to be installed in the running template with the following command. Replace "packages` with a space-delimited list of packages to be installed.
~~~
[user@your-new-clone ~]$ sudo dnf install packages
~~~
Use case | Description | Required steps
--- | --- | ---
**Standard utilities** | If you need the commonly used utilities | Install the following packages: `pciutils` `vim-minimal` `less` `psmisc` `gnome-keyring`
**FirewallVM** | You can use the minimal template as a [FirewallVM](/doc/firewall/), such as the basis template for `sys-firewall` | No extra packages are needed for the template to work as a firewall.
**NetVM** | You can use this template as the basis for a NetVM such as `sys-net` | Install the following packages: `NetworkManager` `NetworkManager-wifi` `network-manager-applet` `wireless-tools` `dbus-x11 dejavu-sans-fonts` `tinyproxy` `notification-daemon` `gnome-keyring`.
**NetVM (extra firmware)** | If your network devices need extra packages for the template to work as a network VM | Use the `lspci` command to identify the devices, then run `dnf search firmware` (replace `firmware` with the appropriate device identifier) to find the needed packages and then install them.
**Network utilities** | If you need utilities for debugging and analyzing network connections | Install the following packages: `tcpdump` `telnet` `nmap` `nmap-ncat`
**USB** | If you want USB input forwarding to use this template as the basis for a [USB](/doc/usb/) qube such as `sys-usb` | Install `qubes-input-proxy-sender`
**VPN** | You can use this template as basis for a [VPN](/doc/vpn/) qube | Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN packages you need, based on the VPN technology you'll be using, and install them. Some GNOME related packages may be needed as well. After creation of a machine based on this template, follow the [VPN howto](/doc/vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager) to configure it.
Logging
-------
It can be installed via the following command:
The `rsyslog` logging service is not installed by default, as all logging is instead being handled by the `systemd` journal.
Users requiring the `rsyslog` service should install it manually.
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-23-minimal
~~~
To access the `journald` log, use the `journalctl` command.
Download will take a while and there will be no progress indicator.
Usage
-----
It is a good idea to clone the original template, and make any changes in the new clone instead:
~~~
[user@dom0 ~]$ qvm-clone fedora-23-minimal <your new template name>
~~~
The sudo package is not installed by default, so let's install it:
~~~
[user@F23-Minimal ~]$ su -
[user@F23-Minimal ~]$ dnf install sudo
~~~
The rsyslog logging service is not installed by default. All logging is now being handled by the systemd journal. Users requiring the rsyslog service should install it manually.
To access the journald log, use the `journalctl` command.
### as a NetVM
If you want to use this template to for standard NetVMs you should install some more packeges:
~~~
[user@F21-Minimal ~]$ sudo dnf install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tinyproxy
~~~
And maybe some more optional but useful packages as well:
~~~
[user@F21-Minimal ~]$ sudo dnf install pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat gnome-keyring
~~~
If your network device needs some firmware then you should also install the corresponding packages as well. The `lspci` and `dnf search firmware` command will help to choose the right one :)
### as a ProxyVM
If you want to use this template as a ProxyVM you may want to install even more packages
#### Firewall
This template is now ready to use for a standard firewall VM.
#### VPN
The needed packages depend on the VPN technology. The `dnf search "NetworkManager VPN plugin"` command may help you to choose the right one. You should also install the corresponding GNOME related packages as well.
[More details about setting up a VPN Gateway](/wiki/VPN#ProxyVM)
#### TOR
[UserDoc/TorVM](/wiki/UserDoc/TorVM)

11
managing-os/templates/fedora.md Normal file
View File

@ -0,0 +1,11 @@
---
layout: doc
title: The Fedora TemplateVM
permalink: /doc/templates/fedora/
---
The Fedora TemplateVM
=====================
The Fedora TemplateVM is the default TemplateVM in Qubes OS.

9
managing-os/fedora-template-upgrade-18.md → managing-os/templates/fedora/upgrade-18-to-20.md
View File

@ -1,14 +1,15 @@
---
layout: doc
title: Upgrading the Fedora 18 Temlpate
permalink: /doc/fedora-template-upgrade-18/
title: Upgrading the Fedora 18 Template to Fedora 20
permalink: /doc/template/fedora/upgrade-18-to-20/
redirect_from:
- /doc/fedora-template-upgrade-18/
- /en/doc/fedora-template-upgrade-18/
- /doc/FedoraTemplateUpgrade18/
- /wiki/FedoraTemplateUpgrade/
---
Upgrading the Fedora 18 Temlpate
Upgrading the Fedora 18 Template
================================
(**Note:** There is a [newer version of this page for upgrading from Fedora 20 to Fedora 21](/doc/fedora-template-upgrade-20/).)
@ -50,7 +51,7 @@ sudo yum --releasever=20 --setopt=cachedir=/mnt/removable distro-sync
After upgrade is finished, you can remove /var/tmp/template-upgrade-cache.img file.
Compacting templates root.img
=============================
-----------------------------
fstrim, nor "discard" mount option do not work on template root fs, so when some file is removed in the template, space isn't freed in dom0. This means that template will use about twice a space that is really need after upgrade.

11
managing-os/fedora-template-upgrade-20.md → managing-os/templates/fedora/upgrade-20-to-21.md
View File

@ -1,8 +1,9 @@
---
layout: doc
title: Upgrading the Fedora 20 Template
permalink: /doc/fedora-template-upgrade-20/
title: Upgrading the Fedora 20 Template to Fedora 21
permalink: /doc/template/fedora/upgrade-20-to-21/
redirect_from:
- /doc/fedora-template-upgrade-20/
- /en/doc/fedora-template-upgrade-20/
- /doc/FedoraTemplateUpgrade20/
- /wiki/FedoraTemplateUpgrade20/
@ -157,7 +158,7 @@ minimal template) is the same as the procedure for the standard template above,
Compacting the Upgraded Template
================================
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
@ -190,7 +191,7 @@ TemplateVM's max size + the actually used space there) free space in dom0.
Additional Information
======================
----------------------
As mentioned above, you may encounter the following `yum` error:
@ -219,6 +220,6 @@ list which also apply to TemplateVM management and migration in general:
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
Known issues with Fedora 21
===========================
---------------------------
* [The "Update VM" command in Qubes Manager does not work](https://github.com/QubesOS/qubes-issues/issues/982).

13
managing-os/fedora-template-upgrade-21.md → managing-os/templates/fedora/upgrade-21-to-23.md
View File

@ -1,8 +1,9 @@
---
layout: doc
title: Upgrading the Fedora 21 Template
permalink: /doc/fedora-template-upgrade-21/
title: Upgrading the Fedora 21 Template to Fedora 23
permalink: /doc/template/fedora/upgrade-21-to-23/
redirect_from:
- /doc/fedora-template-upgrade-21/
- /en/doc/fedora-template-upgrade-21/
- /doc/FedoraTemplateUpgrade21/
- /wiki/FedoraTemplateUpgrade21/
@ -140,7 +141,7 @@ minimal template) is the same as the procedure for the standard template above,
Compacting the Upgraded Template
================================
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
@ -173,7 +174,7 @@ TemplateVM's max size + the actually used space there) free space in dom0.
Additional Information
======================
----------------------
As mentioned above, you may encounter the following `yum` error:
@ -202,13 +203,13 @@ list which also apply to TemplateVM management and migration in general:
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
Upgrading to Fedora 22
======================
----------------------
You may choose to upgrade to Fedora 22 instead of Fedora 23. In that case,
simply replace version "23" with "22" in all above commands.
Known issues with Fedora 23
===========================
---------------------------
* [Graphical update tools (using PackageKit) does not work](https://github.com/QubesOS/qubes-issues/issues/982).
* [Dnf (new Fedora package manager) needs a lot of time to process repository metadata](https://bugzilla.redhat.com/show_bug.cgi?id=1227014), you may want to use `yum-deprecated` for now

238
managing-os/templates/fedora/upgrade-23-to-24.md Normal file
View File

@ -0,0 +1,238 @@
---
layout: doc
title: Upgrading the Fedora 23 Template to Fedora 24
permalink: /doc/template/fedora/upgrade-23-to-24/
redirect_from:
- /doc/fedora-template-upgrade-23/
- /en/doc/fedora-template-upgrade-23/
- /doc/FedoraTemplateUpgrade23/
- /wiki/FedoraTemplateUpgrade23/
---
Upgrading the Fedora 23 Template
================================
Summary: Upgrading the Standard Fedora 23 Template to Fedora 24
---------------------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-24`).
[user@dom0 ~]$ qvm-clone fedora-23 fedora-24
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal
[user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img
[user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-24 ~]$ sudo dnf clean all
[user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-trim-template fedora-24
(Optional cleanup: Switch everything over to the new template and delete the old
one. See instructions below for details.)
Detailed: Upgrading the Standard Fedora 23 Template to Fedora 24
----------------------------------------------------------------
These instructions will show you how to upgrade the standard Fedora 23
TemplateVM to Fedora 24. The same general procedure may be used to upgrade any
template based on the standard Fedora 23 template.
**Note:** The command-line prompt on each line indicates where each command
should be entered (`@dom0` or `@fedora-24`).
1. Ensure the existing template is not running.
[user@dom0 ~]$ qvm-shutdown fedora-23
2. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-23 fedora-24
[user@dom0 ~]$ qvm-run -a fedora-24 gnome-terminal
3. Attempt the upgrade process in the new template.
[user@fedora-24 ~]$ sudo dnf clean all
[user@fedora-24 ~]$ sudo dnf --releasever=24 distro-sync
**Note:** `dnf` might ask you to approve importing a new package signing
key. For example, you might see a prompt like this one:
warning: /var/cache/dnf/fedora-d02ca361e1b58501/packages/python2-babel-2.3.4-1.fc24.noarch.rpm: Header V3 RSA/SHA256 Signature, key ID 81b46521: NOKEY
Importing GPG key 0x81B46521:
Userid : "Fedora (24) <fedora-24-primary@fedoraproject.org>"
Fingerprint: 5048 BDBB A5E7 76E5 47B0 9CCC 73BD E983 81B4 6521
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-24-x86_64
Is this ok [y/N]:
This key was already checked when it was installed (notice that the "From"
line refers to a location on your local disk), so you can safely say yes to
this prompt.
**Note:** If you encounter no errors, proceed to step 4. If you do encounter
errors, see the next two points first.
* If `dnf` reports that you do not have enough free disk space to proceed
with the upgrade process, create an empty file in dom0 to use as a cache
and attach it to the template as a virtual disk.
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-block -A fedora-24 dom0:/var/tmp/template-upgrade-cache.img
Then reattempt the upgrade process, but this time use the virtual disk
as a cache.
[user@fedora-24 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-24 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-24 ~]$ sudo dnf clean all
[user@fedora-24 ~]$ sudo dnf --releasever=24 --setopt=cachedir=/mnt/removable distro-sync
If this attempt is successful, proceed to step 4.
* `dnf` may complain:
At least X MB more space needed on the / filesystem.
In this case, one option is to [resize the TemplateVM's disk
image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
4. Shut down the new TemplateVM (from the command-line or Qubes VM Manager).
[user@dom0 ~]$ qvm-shutdown fedora-24
5. Remove the cache file, if you created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
6. Trim the new template (see [Compacting the Upgraded Template] for details
and other options).
[user@dom0 ~]$ qvm-trim-template fedora-24
7. (Recommended) Switch everything that was set to the old template to the new
template, e.g.:
1. Make the new template the default template:
Qubes Manager --> Global settings --> Default template
2. Base AppVMs on the new template. In Qubes Manager, for each VM that is
currently based on `fedora-23` that you would like to base on
`fedora-24`, enter its VM settings and change the Template selection:
Qubes Manager --> (Select a VM) --> VM settings --> Template
3. Base the [DispVM] template on the new template.
If you have set the new template as your default template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template
Otherwise:
[user@dom0 ~]$ qvm-create-default-dvm fedora-24
8. (Optional) Remove the old template. (Make sure to type `fedora-23`, not
`fedora-24`.)
[user@dom0 ~]$ sudo dnf remove qubes-template-fedora-23
Summary: Upgrading the Minimal Fedora 23 Template to Fedora 24
--------------------------------------------------------------
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0` or `@fedora-24`).
[user@dom0 ~]$ qvm-clone fedora-23-minimal fedora-24-minimal
[user@dom0 ~]$ qvm-run -a fedora-24-minimal xterm
[user@fedora-24-minimal ~]$ su -
[root@fedora-24-minimal ~]# dnf clean all
[user@fedora-24-minimal ~]# dnf --releasever=24 distro-sync
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-24-minimal
(If you encounter insufficient space issues, you may need to use the methods
described for the standard template above.)
Differences Between the Standard and Minimal Upgrade Procedures
---------------------------------------------------------------
The procedure for upgrading the minimal template (or any template based on the
minimal template) is the same as the procedure for the standard template above,
**with the following exceptions**:
1. `gnome-terminal` is not installed by default. Unless you've installed it
(or another terminal emulator), use `xterm`. (Of course, you can also use
`xterm` for the standard template, if you prefer.)
2. `sudo` is not installed by default. Unless you've installed it, use `su` as
demonstrated above. (Of course, you can also use `su` for the standard
template, if you prefer.)
Compacting the Upgraded Template
--------------------------------
Neither `fstrim` nor the `discard` mount option works on the TemplateVM's root
filesystem, so when a file is removed in the template, space is not freed in
dom0. This means that the template will use about twice as much space as is
really necessary after upgrading.
You can use the `qvm-trim-template` tool:
[user@dom0 ~]$ qvm-trim-template fedora-24
Upgrading StandaloneVMs
-----------------------
The procedure for upgrading a StandaloneVM from Fedora 23 to Fedora 24 is the
same as for a TemplateVM, except that `qvm-trim-template` does not work on
StandaloneVMs. Instead, you should run the following command inside the
StandaloneVM in order to compact it:
$ sudo fstrim -v -a
Additional Information
----------------------
As mentioned above, you may encounter the following `dnf` error:
At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by
uninstalling packages. You may then reinstalling them again after you
finish the upgrade process, if desired). However, you may end up having to
increase the disk image size anyway (see previous option).
3. Increase the `root.img` size with `qvm-grow-root`.
4. Do the upgrade in parts, e.g., by using package groups. (First upgrade
`@core` packages, then the rest.)
5. Do not perform an in-place upgrade. Instead, simply download and install a
new template package, then redo all desired template modifications.
With regard to the last option, here are some useful messages from the
mailing list which also apply to TemplateVM management and migration in
general:
* [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J)
* [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ)
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[Compacting the Upgraded Template]: #compacting-the-upgraded-template
[DispVM]: /doc/dispvm/

18
managing-os/templates/ubuntu.md
View File

@ -12,10 +12,10 @@ redirect_from:
Ubuntu template(s)
==================
If you like to use Ubuntu Linux distribution in your AppVMs, you can build and
install one of available Ubuntu templates. Those template currently are not
If you would like to use Ubuntu Linux distribution in your AppVMs, you can build and
install one of the available Ubuntu templates. These templates are currently not
available in ready to use binary packages, because Canonical does not allow
to redistribute a modified Ubuntu. The redistribution is not allowed by their
redistribution of a modified Ubuntu. The redistribution is not allowed by their
[Intellectual property rights policy](http://www.ubuntu.com/legal/terms-and-policies/intellectual-property-policy).
@ -30,15 +30,9 @@ To quickly prepare the builder configuration, you can use `setup` script
available in the repository - it will interactively ask you which templates you
want to build.
Known issues
------------
Ubuntu 14.4 LTS (Trusty) can be built with little effort.
Building an Ubuntu 14.4 LTS template can be difficult ([see](https://groups.google.com/forum/#!topic/qubes-users/w0uZNr8nno8)).
A workaround is creating an ubuntu HVM A and use X over ssh from a second vm B ([see](https://groups.google.com/forum/#!topic/qubes-users/-wkG7E55PUI)).
To do this you have to enable networking between A and B, or set B as netvm of A.
If B supports copy and paste or seamless mode so does (indirectly) A. (you will be missing some features. e.g.: send file to vm A)
Doing this reduces the security of A to the security of B!
This is no problem, if B's only purpose is providing X over ssh only for vm A.
----------
If you want to help in improving the template, feel free to
[contribute](/wiki/ContributingHowto).
[contribute](/doc/contributing/).

2
managing-os/uninstalling-windows-tools-2.md → managing-os/windows/uninstalling-windows-tools-2.md
View File

@ -60,7 +60,7 @@ If you need network access to copy the uninstall script to the HVM, use *Safe Mo
The uninstall script
====================
--------------------
Save it as a .BAT file in the HVM and run in Safe Mode.

22
managing-os/windows-appvms.md → managing-os/windows/windows-appvms.md
View File

@ -51,6 +51,14 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-too
This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed.
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that:
- Start command prompt as Administrator, i.e. right click on the Command Prompt icon and choose "Run as administrator"
- In the command prompt type `bcdedit /set testsigning on`
- Reboot your Windows VM
In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`:
~~~
@ -59,9 +67,7 @@ qvm-start lab-win7 --install-windows-tools
Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory.
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. How to do that is explained in the `README` file also located on the installation CDROM. In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
After successful installation, the Windows VM must be shut down and started again.
After successful installation, the Windows VM must be shut down and started again, possibly a couple of times (see [this page](/doc/windows-tools-3/) for detailed configuration options).
Qubes (R2 Beta 3 and later releases) will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command:
@ -69,7 +75,7 @@ Qubes (R2 Beta 3 and later releases) will automatically detect the tools has bee
qvm-prefs <your-appvm-name>
~~~
NOTE: it is recommended to increase the default value of `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0:
NOTE: it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0:
~~~
qvm-prefs -s <vm-name> qrexec_timeout 300
@ -104,10 +110,10 @@ To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press C
![windows-seamless-7.png](/attachment/wiki/WindowsAppVms/windows-seamless-7.png)
Forcing Windows AppVM into full desktop mode
--------------------------------------------
Changing between seamless and full desktop mode
-----------------------------------------------
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager.
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default.
Using template-based Windows AppVMs (Qubes R2 Beta 3 and later)
---------------------------------------------------------------
@ -123,7 +129,7 @@ qvm-create --hvm-template win7-x64-template -l green
- The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active.
- User profiles are moved to the private disk on the next reboot after the private disk is initialized. Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there. This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot. That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after.
It also makes sense to disable Automatic Updates for all the Windows-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives).
It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
Once the template has been created and installed it is easy to create AppVMs based on:

0
managing-os/windows-tools-2.md → managing-os/windows/windows-tools-2.md
View File

13
managing-os/windows-tools-3.md → managing-os/windows/windows-tools-3.md
View File

@ -32,16 +32,17 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl
**In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause severe problems, including disk image/files corruption in Qubes HVMs. We're investigating this. *However*, the problem doesn't always occur in tests -- disk drivers often work *if they are installed separately after the main portion of QWT is up and running*. **Do this at your own risk** of course, but we welcome reports of success/failure in any case. With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
Verbose installation
--------------------
Xen PV driver components may display a message box asking for reboot during installation -- it's safe to ignore them and defer the reboot.
If the install process fails you can retry it using the command line below to get a detailed installation log (and send that to us):
Installation logs
-----------------
`msiexec /i path-to-qubes-tools.msi /lv path-to-log-file.txt`
If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `<user profile>\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`.
Uninstalling QWT 3.x is **not recommended**. It will most likely make the OS non-bootable because drivers for Xen storage devices will be uninstalled. This will be fixed in the future.
Uninstalling QWT is supported from version 3.2.1. Uninstalling previous versions is **not recommended**.
After uninstalling you need to manually enable the DHCP Client Windows service, or set IP settings yourself to restore network access.
Configuration
-------------

84
privacy/anonymizing-your-mac-address.md
View File

@ -9,26 +9,62 @@ redirect_from:
Anonymizing your MAC Address
============================
Changing the default [MAC Address](https://en.wikipedia.org/wiki/MAC_address) of your hardware is [crucial in protecting
privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1). Currently, Qubes OS *does not* "anonymize" or spoof the MAC Address, so until this is implemented by default you can randomize your MAC Address with the following guide.
Although it is not the only metadata broadcast by network hardware, changing the default [MAC Address](https://en.wikipedia.org/wiki/MAC_address) of your hardware could be [an important step in protecting
privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1). Currently, Qubes OS *does not* automatically "anonymize" or spoof the MAC Address, so until this is implemented by default you can randomize your MAC Address with one of the following guides using either Network Manager or macchanger...
## Configuring Qubes
## Upgrading and configuring Network Manager in Qubes
Newer versions of Network Manager have a robust set of options for randomizing MAC addresses, and can handle the entire process across reboots, sleep/wake cycles and different connection states. In particular, versions 1.4.2 and later should be well suited for Qubes.
NM 1.4.2 is currently available from the Debian 9 (testing) repository, and has been tested in Qubes using a Debian template [upgraded to version 9.](https://www.qubes-os.org/doc/debian-template-upgrade-8/)
In the Debian 9 template you intend to use as a NetVM, check that Network Manager version is now at least 1.4.2:
~~~
$ sudo NetworkManager -V
1.4.2
~~~
Write the settings to a new file in the `/etc/NetworkManager/conf.d/` directory, such as `mac.conf`. The following example enables Wifi and Ethernet MAC address randomization while scanning (not connected), and uses a randomly generated but persistent MAC address for each individual Wifi and Ethernet connection profile.
~~~
[device]
wifi.scan-rand-mac-address=yes
[connection]
wifi.cloned-mac-address=stable
ethernet.cloned-mac-address=stable
~~~
`stable` generates a random address that persists for each boot session.
`random` generates a random address each time a link goes up.
To see all the available configuration options, refer to the man page: `man nm-settings`
Next, create a new NetVM using the new template and assign network devices to it.
Finally, shutdown all VMs and change the settings of sys-firewall, etc. to use the new NetVM.
You can check the MAC address currently in use by looking at the status pages of your router device(s), or in the NetVM with the command `sudo ip link show`.
## Configuring Qubes with macchanger and scripts
First thing you need to do is install **macchanger** package by opening your `fedora-23` TemplateVM and typing
```
~~~
sudo dnf install macchanger
```
~~~
Then create the file `macspoof@.service` in `fedora-23` located at `/etc/systemd/system/` directory using a text editor such as `vim`, `emacs`, or `gedit`
```
~~~
sudo gedit /etc/systemd/system/macspoof@.service
```
~~~
Paste the following inside of that newly created file
```
~~~
[Unit]
Description=macchanger on %I
# Hack since macspoof@%i contains @ which is not allowed yet
@ -44,15 +80,15 @@ Type=oneshot
[Install]
WantedBy=multi-user.target
```
~~~
**How random do you want your MAC address?**
Note in the above line `ExecStart=/usr/bin/macchanger -e %I` we recommend the use of `macchanger` with the `-e` flag which randomizes the MAC address to an address by the same device vendor/manufacturer. There a [number of other flags](http://manpages.ubuntu.com/manpages/xenial/en/man1/macchanger.1.html) you could use instead, such as `-r` which makes a totally random MAC address, which may map to a non-existent device vendor/manufacturer and make it obvious you are spoofing your MAC address. Some reasons why we have recommended `-e` rather than `-r` are in these resources:
* https://tails.boum.org/contribute/design/MAC_address/#index5h2
* https://tails.boum.org/contribute/design/MAC_address/#limitation-only-spoof-nic-part
* https://help.ubuntu.com/community/AnonymizingNetworkMACAddresses#Fully_Random
* <https://tails.boum.org/contribute/design/MAC_address/#index5h2>
* <https://tails.boum.org/contribute/design/MAC_address/#limitation-only-spoof-nic-part>
* <https://help.ubuntu.com/community/AnonymizingNetworkMACAddresses#Fully_Random>
**Get the right iface names**
@ -60,7 +96,7 @@ It's crucial to get the correct **iface name** for the devices (ethernet and wif
open your `sys-net` (or wherever your device drivers are) and type in `terminal` the command `ifconfig` the printout
will look like:
```
~~~
enp0s0: flags=4099<UP,BROADCAST,MULTICAST> mtu 1500
ether 9e:d6:53:02:4b:b6 txqueuelen 1000 (Ethernet)
RX packets 0 bytes 0 (0.0 B)
@ -86,7 +122,7 @@ wlp0s1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 32 bytes 3712 (3.6 KiB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
```
~~~
The **iface name** values you're interested in are `enp0s0` and `wlp0s1` as those represent your ethernet and wifi
devices, respectively.
@ -98,29 +134,29 @@ respectively. *Copy these MAC addresses down somewhere for later.*
Now, go back to your `fedora-23` TemplateVM and use the `touch` command to create service files in the appropriate
place, note that the `iface name` values at the end:
```
~~~
cd /var/run/qubes-service/
sudo touch macspoof-enp0s0
sudo touch macspoof-wlp0s1
```
~~~
Verify the correct files exist in the directory
```
~~~
[user@fedora-23 qubes-service]$ ls
cups macspoof-wlp0s1 qubes-update-check
macspoof-enp0s0 meminfo-writer updates-proxy-setup
```
~~~
Now, also within the TemplateVM, type the following commands for each hardware device that you want to randomize a MAC
addresses for
```
~~~
sudo systemctl enable macspoof@wlp0s1
Created symlink from /etc/systemd/system/multi-user.target.wants/macspoof@wlp0s1.service to /etc/systemd/system/macspoof@.service.
sudo systemctl enable macspoof@enp0s0
Created symlink from /etc/systemd/system/multi-user.target.wants/macspoof@enp0s0.service to /etc/systemd/system/macspoof@.service.
```
~~~
Now you can do the following:
- Stop your `fedora-23` VM
@ -132,10 +168,10 @@ Open your VM settings for `sys-net`, navigate to Services, and add the new servi
Alternatively, you can enable these services for `sys-net` from the command line by opening up Terminal in `dom0` and running the following:
```
~~~
qvm-service -e sys-net macspoof-wlp0s1
qvm-service -e sys-net macspoof-enp0s0
```
~~~
Now restart `sys-net`.
@ -147,14 +183,14 @@ Your MAC address should now randomize each time you restart your computer or res
---
## Usage Notes
## Usage Notes - Macchanger
This approach to MAC Randomizing has been tested and used by some users as well as some of the Qubes team. Observations that are to be expected are:
- This does not randomize your MAC Address on sleep and wake state (only on restarting the `sys-net` VM)
- The `sys-net` networking VM takes longer for device drivers to start up than usual, this delayed startup may cause the first attempt of `sys-whonix` to connect to Tor to fail
## Disabling / Uninstalling
## Disabling / Uninstalling Macchanger
To disable MAC Randomizing if you find that a network connecting to does not like changing MAC Addresses, you can disable temporarily or if you want to permanently remove this solution, do the following:

79
privacy/signal.md Normal file
View File

@ -0,0 +1,79 @@
---
layout: doc
title: Signal
permalink: /doc/signal/
---
Signal
======
What is [Signal]?
[According to Wikipedia:][signal-wikipedia]
> Signal is an encrypted instant messaging and voice calling application
> for Android and iOS. It uses end-to-end encryption to secure all
> communications to other Signal users. Signal can be used to send and receive
> encrypted instant messages, group messages, attachments and media messages.
> Users can independently verify the identity of their messaging correspondents
> by comparing key fingerprints out-of-band. During calls, users can check the
> integrity of the data channel by checking if two words match on both ends of
> the call.
>
> Signal is developed by Open Whisper Systems. The clients are published as free
> and open-source software under the GPLv3 license.
How to install Signal in Qubes
------------------------------
If you're a Signal user on Android, you can now have Signal inside Qubes.
1. Install the Chromium browser in a TemplateVM.
2. Shut down the TemplateVM.
3. Create a new AppVM based on this TemplateVM.
4. Launch Chromium browser in the new AppVM, type `chrome://extensions/` in the
address bar, and follow the link to the Chrome app store.
4. In the app store, search for "Signal Private Messenger" and install the app.
5. The app launches automatically on first install. Follow the prompts to "link"
this app with your phone.
6. Signal should now work in your AppVM.
Creating a Shortcut in the applications menu
--------------------------------------------
Let's make Signal a bit more usable by creating a shortcut in our desktop
panel that launches Signal directly. This assumes that you're using KDE or Xfce in Dom0,
you use Signal in an AppVM named `Signal`, and this AppVM uses `fedora-23` as its TemplateVM.
1. Follow [these instructions][shortcut] to create a desktop shortcut on the Desktop of your Signal AppVM.
Let's assume the shortcut file you get is `/home/user/Desktop/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop`
2. Copy this shortcut file to the AppVM's TemplateVM - in this case, to `fedora-23`.
3. You'll also want to copy across an icon for your new shortcut - you can find this at
`/home/user/.local/share/icons/hicolor/48x48/apps/chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png`
Copy this icon to the `fedora-23` TemplateVM.
4. Open a terminal in your `fedora-23` TemplateVM and `cd` to `/home/user/QubesIncoming/Signal/`.
You should find your shortcut and icon files just transferred across from the Signal AppVM.
Move these files to the following locations:
[user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.desktop /usr/share/applications/
[user@fedora-23 Signal]$ sudo mv chrome-bikioccmkafdpakkkcpdbhpfkkhcmohk-Default.png /usr/share/icons/hicolor/48x48/
5. From a Dom0 terminal, instruct Qubes to synchronize the application menus of this TemplateVM:
[user@dom0 ~]$ qvm-sync-appmenus fedora-23
6. With your mouse select the `Q` menu -> `Domain: Signal` -> `Signal: Add more shortcuts`
Select `Signal Private Messenger` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window.
7. Then follow the `Q` menu once more, right-click on the new `Signal: Signal Private Messenger` menu item and select `Add to Panel`.
You can now launch the Signal messenger inside its own dedicated AppVM with a single click from KDE's panel.
-----
[Signal]: https://whispersystems.org/
[signal-wikipedia]: https://en.wikipedia.org/wiki/Signal_(software)
[shortcut]: http://support.whispersystems.org/hc/en-us/articles/216839277-Where-is-Signal-Desktop-on-my-computer-
[shortcut-desktop]: /doc/managing-appvm-shortcuts/#tocAnchor-1-1-1
[message]: https://groups.google.com/d/msg/qubes-users/rMMgeR-KLbU/XXOFri26BAAJ
[mailing list]: /mailing-lists/

10
privacy/whonix.md
View File

@ -34,11 +34,13 @@ To install Whonix, you must have a working Qubes machine already.
* [Customizing Whonix](/doc/whonix/customize/)
* [Uninstall Whonix from Qubes](/doc/whonix/uninstall/)
*The following links are on Whonix's website and are technical.*
*The following links are on Whonix's website and may be technical.*
* [Security Advice for after installing Whonix on Qubes](https://www.whonix.org/wiki/Post_Install_Advice)
* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges#How_to_use_bridges_in_Whonix)
* [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix)
* [Using Whonix with DisposableVMs](https://www.whonix.org/blog/qubes-whonix-dispvm)
* [Security Advice for after installing Whonix on Qubes](https://www.whonix.org/wiki/Post_Install_Advice)
* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges#How_to_use_bridges_in_Whonix)
* [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix)
* [How to use Corridor (a Tor traffic whitelisting gateway) with Whonix](https://www.whonix.org/wiki/Corridor)
## Support for Whonix

2
reference/dom0-tools/qvm-service.md
View File

@ -88,7 +88,7 @@ Enable CUPS service. The user can disable cups in VM which do not need printing
crond
Default: disabled
Enable CRON service.
Enable CRON service. To have cron jobs persist across reboots, /var/spool/cron is bind-mounted from /rw/bind-dirs. To override this see [Bind-Dir Instructions](/doc/bind-dirs/) )
network-manager
Default: enabled in NetVM

18
reference/glossary.md
View File

@ -82,7 +82,8 @@ applications, but not for running them.
TemplateBasedVM
---------------
Any [VM](#vm) which depends on a TemplateVM for its root filesystem.
Any [VM](#vm) which depends on a [TemplateVM](#templatevm) for its root
filesystem.
Standalone(VM)
--------------
@ -164,8 +165,19 @@ Any [HVM](#hvm) which functions as a [TemplateVM](#templatevm) by supplying its
root filesystem to other VMs. In Qubes, TemplateHVMs are referred to as **HVM
templates**.
PVH
---
TemplateBasedHVM
----------------
Any [HVM](#hvm) that depends on a [TemplateVM](#templatevm) for its root
filesystem.
ServiceVM
---------
Service Virtual Machine. A [VM](#vm) the primary purpose of which is to provide
a service or services to other VMs. NetVMs and ProxyVMs are examples of
ServiceVMs.
PVHVM
-----
[PV](#pv) on [HVM](#hvm). To boost performance, fully virtualized HVM guests can
use special paravirtual device drivers (PVHVM or PV-on-HVM drivers). These
drivers are optimized PV drivers for HVM environments and bypass the emulation

4
releases/3.1/release-notes.md
View File

@ -7,8 +7,6 @@ permalink: /doc/releases/3.1/release-notes/
Qubes R3.1 release notes
========================
*this page is a draft for yet unreleased version*
New features since 3.0
----------------------
@ -73,6 +71,6 @@ using](/doc/releases/3.0/release-notes/#upgrading) first, then follow the
instructions above. This will be time consuming process.
[salt-doc]: /doc/salt/
[pvgrub-doc]: /doc/managing-vm-kernel/#tocAnchor-1-3
[pvgrub-doc]: /doc/managing-vm-kernel/#using-kernel-installed-in-the-vm
[input-proxy]: https://github.com/QubesOS/qubes-app-linux-input-proxy/blob/master/README.md
[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed

Some files were not shown because too many files have changed in this diff Show More